@decocms/start 0.36.4 → 0.37.0

package/package.json

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

package/scripts/migrate/transforms/jsx.ts

@@ -171,6 +171,55 @@ export function transformJsx(content: string): TransformResult {
     notes.push("Replaced 'class' in interface definitions with 'className'");
   }
 
+  // Remove `alt` prop from non-img elements (<a>, <iframe>, <div>, etc.)
+  // In React, `alt` is only valid on <img>, <input type="image">, <area>
+  const altOnNonImgRegex = /(<(?:a|iframe|div|span|button|section)\s[^>]*?)\s+alt=(?:\{[^}]*\}|"[^"]*"|'[^']*')/g;
+  if (altOnNonImgRegex.test(result)) {
+    result = result.replace(
+      /(<(?:a|iframe|div|span|button|section)\s[^>]*?)\s+alt=(?:\{[^}]*\}|"[^"]*"|'[^']*')/g,
+      "$1",
+    );
+    changed = true;
+    notes.push("Removed invalid alt prop from non-img elements");
+  }
+
+  // Remove `type` prop from non-form elements (<span>, <div>, etc.)
+  // In React, `type` is only valid on <input>, <button>, <select>, <textarea>, <script>, <style>, <link>
+  const typeOnInvalidRegex = /(<(?:span|div|p|section|header|footer|nav|main|article|aside)\s[^>]*?)\s+type=(?:\{[^}]*\}|"[^"]*"|'[^']*')/g;
+  if (typeOnInvalidRegex.test(result)) {
+    result = result.replace(
+      /(<(?:span|div|p|section|header|footer|nav|main|article|aside)\s[^>]*?)\s+type=(?:\{[^}]*\}|"[^"]*"|'[^']*')/g,
+      "$1",
+    );
+    changed = true;
+    notes.push("Removed invalid type prop from non-form elements");
+  }
+
+  // setTimeout/setInterval return type: use window.setTimeout for correct typing
+  // In Node/CF Workers, setTimeout returns Timeout object, not number
+  // window.setTimeout always returns number
+  if (/\bsetTimeout\b/.test(result) && /:\s*number/.test(result)) {
+    // Only replace bare setTimeout when it's assigned to a typed variable
+    result = result.replace(
+      /\b(?<!window\.)setTimeout\(/g,
+      "window.setTimeout(",
+    );
+    result = result.replace(
+      /\b(?<!window\.)setInterval\(/g,
+      "window.setInterval(",
+    );
+    result = result.replace(
+      /\b(?<!window\.)clearTimeout\(/g,
+      "window.clearTimeout(",
+    );
+    result = result.replace(
+      /\b(?<!window\.)clearInterval\(/g,
+      "window.clearInterval(",
+    );
+    changed = true;
+    notes.push("Prefixed setTimeout/setInterval with window. for correct typing");
+  }
+
   // Ensure React import exists if we introduced React.* references
   if (
     (result.includes("React.") || result.includes("React,")) &&

package/src/apps/autoconfig.ts

@@ -25,7 +25,7 @@ interface AppAutoconfigurator {
 }
 
 const KNOWN_APPS: Record<string, AppAutoconfigurator> = {
-	"deco-resend": async (block: any) => {
+	"deco-resend": async (block: any): Promise<Record<string, InvokeAction>> => {
 		try {
 			const [resendClient, resendActions] = await Promise.all([
 				import("@decocms/apps/resend/client" as string),
@@ -40,7 +40,7 @@ const KNOWN_APPS: Record<string, AppAutoconfigurator> = {
 					"[autoconfig] deco-resend: no API key found." +
 					" Set DECO_CRYPTO_KEY to decrypt CMS secrets, or set RESEND_API_KEY as fallback.",
 				);
-				return {};
+				return {} as Record<string, InvokeAction>;
 			}
 
 			configureResend({

package/src/cms/sectionLoaders.ts

@@ -33,6 +33,17 @@ interface CacheableSectionConfig {
   maxAge: number;
 }
 
+type CacheableSectionInput = CacheableSectionConfig | import("../sdk/cacheHeaders").CacheProfileName;
+
+function resolveSectionCacheConfig(input: CacheableSectionInput): CacheableSectionConfig {
+  if (typeof input === "string") {
+    const { getCacheProfile } = require("../sdk/cacheHeaders") as typeof import("../sdk/cacheHeaders");
+    const profile = getCacheProfile(input);
+    return { maxAge: profile.loader.fresh };
+  }
+  return input;
+}
+
 const cacheableSections: Map<string, CacheableSectionConfig> = G.__deco.cacheableSections;
 
 interface SectionCacheEntry {
@@ -64,9 +75,9 @@ function sectionCacheKey(component: string, props: Record<string, unknown>): str
  * Works for both eager sections (speeds up SSR) and deferred sections
  * (speeds up individual fetch on scroll).
  */
-export function registerCacheableSections(configs: Record<string, CacheableSectionConfig>): void {
+export function registerCacheableSections(configs: Record<string, CacheableSectionInput>): void {
   for (const [key, config] of Object.entries(configs)) {
-    cacheableSections.set(key, config);
+    cacheableSections.set(key, resolveSectionCacheConfig(config));
   }
 }
 

package/src/routes/cmsRoute.ts

@@ -41,7 +41,7 @@ import {
 import { getSiteSeo } from "../cms/loader";
 import { runSectionLoaders, runSingleSectionLoader } from "../cms/sectionLoaders";
 import {
-  type CacheProfile,
+  type CacheProfileName,
   cacheHeaders,
   detectCacheProfile,
   routeCacheDefaults,
@@ -328,7 +328,7 @@ export interface CmsRouteOptions {
 
 type CmsPageLoaderData = {
   name?: string;
-  cacheProfile?: CacheProfile;
+  cacheProfile?: CacheProfileName;
   seo?: PageSeo;
   device?: Device;
   resolvedSections?: Array<{ component: string }>;

package/src/sdk/cacheHeaders.ts

@@ -1,22 +1,27 @@
 /**
- * Cache-Control header generation for different page types.
+ * Unified cache profile system for Deco storefronts.
  *
- * Produces spec-compliant `Cache-Control` values suitable for CDNs
- * (Cloudflare, Vercel, Fastly) with `s-maxage` and `stale-while-revalidate`.
+ * Each named profile (product, listing, search, static, etc.) defines cache
+ * timing across ALL layers — edge, browser, loader, and client — in a single
+ * object. This is the single source of truth for cache configuration.
+ *
+ * Sites override specific values via `setCacheProfile()` without touching
+ * framework code. Derivation functions (`cacheHeaders`, `routeCacheDefaults`,
+ * `loaderCacheOptions`, `edgeCacheConfig`) read from the profiles.
  *
  * @example
  * ```ts
- * // In a TanStack Start route:
- * import { cacheHeaders, routeCacheDefaults } from "@decocms/start/sdk/cacheHeaders";
- *
- * export const Route = createFileRoute('/products/$slug')({
- *   ...routeCacheDefaults("product"),
- *   headers: () => cacheHeaders("product"),
- * });
+ * // Site-level override (src/cache-config.ts):
+ * import { setCacheProfile } from "@decocms/start/sdk/cacheHeaders";
+ * setCacheProfile("product", { edge: { fresh: 600 } }); // 10min instead of 5min
  * ```
  */
 
-export type CacheProfile =
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type CacheProfileName =
   | "static"
   | "product"
   | "listing"
@@ -25,94 +30,156 @@ export type CacheProfile =
   | "private"
   | "none";
 
-export interface CacheHeadersConfig {
-  /** Browser max-age in seconds. */
-  maxAge: number;
-  /** CDN/edge max-age in seconds. */
-  sMaxAge: number;
-  /** Stale-while-revalidate window in seconds. */
-  staleWhileRevalidate: number;
-  /** Whether the response is public (cacheable by CDN). */
+/** Time windows for a single caching layer (in seconds). */
+export interface CacheTimingWindow {
+  /** How long content is considered fresh — served without origin contact. */
+  fresh: number;
+  /** After fresh expires, serve stale while refreshing in background. */
+  swr: number;
+  /** After fresh expires and origin is erroring, serve stale for this long. */
+  sie: number;
+}
+
+/** Unified cache profile covering all layers. */
+export interface CacheProfileConfig {
+  /** Edge / CDN layer (Cloudflare Cache API). Times in seconds. */
+  edge: CacheTimingWindow;
+  /** Browser layer (Cache-Control header). Times in seconds. */
+  browser: CacheTimingWindow;
+  /** In-memory loader layer. Times in milliseconds. */
+  loader: {
+    fresh: number;
+    sie: number;
+  };
+  /** Client-side TanStack Router. Times in milliseconds. */
+  client: {
+    staleTime: number;
+    gcTime: number;
+  };
+  /** Whether CDN can cache this profile. False = private, never cached. */
   isPublic: boolean;
 }
 
-const PROFILES: Record<CacheProfile, CacheHeadersConfig> = {
+/**
+ * Deep partial of CacheProfileConfig for site-level overrides.
+ * Only the fields you specify are merged; everything else keeps its default.
+ */
+export type CacheProfileOverrides = {
+  [K in keyof CacheProfileConfig]?: CacheProfileConfig[K] extends object
+    ? Partial<CacheProfileConfig[K]>
+    : CacheProfileConfig[K];
+};
+
+// ---------------------------------------------------------------------------
+// Default profiles
+// ---------------------------------------------------------------------------
+
+const PROFILES: Record<CacheProfileName, CacheProfileConfig> = {
   static: {
-    maxAge: 120,
-    sMaxAge: 86400,
-    staleWhileRevalidate: 86400,
+    edge: { fresh: 900, swr: 7200, sie: 21600 },
+    browser: { fresh: 120, swr: 1800, sie: 7200 },
+    loader: { fresh: 300_000, sie: 1_800_000 },
+    client: { staleTime: 300_000, gcTime: 1_800_000 },
     isPublic: true,
   },
   product: {
-    maxAge: 60,
-    sMaxAge: 300,
-    staleWhileRevalidate: 3600,
+    edge: { fresh: 300, swr: 1800, sie: 7200 },
+    browser: { fresh: 60, swr: 600, sie: 3600 },
+    loader: { fresh: 30_000, sie: 600_000 },
+    client: { staleTime: 60_000, gcTime: 300_000 },
     isPublic: true,
   },
   listing: {
-    maxAge: 30,
-    sMaxAge: 120,
-    staleWhileRevalidate: 600,
+    edge: { fresh: 120, swr: 900, sie: 3600 },
+    browser: { fresh: 30, swr: 300, sie: 1800 },
+    loader: { fresh: 60_000, sie: 300_000 },
+    client: { staleTime: 60_000, gcTime: 300_000 },
     isPublic: true,
   },
   search: {
-    maxAge: 0,
-    sMaxAge: 60,
-    staleWhileRevalidate: 300,
+    edge: { fresh: 60, swr: 300, sie: 1800 },
+    browser: { fresh: 0, swr: 120, sie: 600 },
+    loader: { fresh: 60_000, sie: 180_000 },
+    client: { staleTime: 30_000, gcTime: 120_000 },
     isPublic: true,
   },
   cart: {
-    maxAge: 0,
-    sMaxAge: 0,
-    staleWhileRevalidate: 0,
+    edge: { fresh: 0, swr: 0, sie: 0 },
+    browser: { fresh: 0, swr: 0, sie: 0 },
+    loader: { fresh: 0, sie: 0 },
+    client: { staleTime: 0, gcTime: 0 },
     isPublic: false,
   },
   private: {
-    maxAge: 0,
-    sMaxAge: 0,
-    staleWhileRevalidate: 0,
+    edge: { fresh: 0, swr: 0, sie: 0 },
+    browser: { fresh: 0, swr: 0, sie: 0 },
+    loader: { fresh: 0, sie: 0 },
+    client: { staleTime: 0, gcTime: 0 },
     isPublic: false,
   },
   none: {
-    maxAge: 0,
-    sMaxAge: 0,
-    staleWhileRevalidate: 0,
+    edge: { fresh: 0, swr: 0, sie: 0 },
+    browser: { fresh: 0, swr: 0, sie: 0 },
+    loader: { fresh: 0, sie: 0 },
+    client: { staleTime: 0, gcTime: 0 },
     isPublic: false,
   },
 };
 
+// ---------------------------------------------------------------------------
+// Profile accessors
+// ---------------------------------------------------------------------------
+
+export function getCacheProfile(profile: CacheProfileName): CacheProfileConfig {
+  return PROFILES[profile];
+}
+
 /**
- * Generate a `Cache-Control` header value from a named profile or custom config.
- * Returns a headers object ready to spread into route `headers()`.
+ * Override specific values of a cache profile. Only the fields you specify
+ * are merged; everything else keeps its default.
  *
- * Always includes `Vary: Accept-Encoding` for public responses.
+ * @example
+ * ```ts
+ * setCacheProfile("product", { edge: { fresh: 600 } });
+ * setCacheProfile("static", { loader: { sie: 3_600_000 } });
+ * ```
+ */
+export function setCacheProfile(
+  profile: CacheProfileName,
+  overrides: CacheProfileOverrides,
+): void {
+  const current = PROFILES[profile];
+  PROFILES[profile] = {
+    edge: { ...current.edge, ...overrides.edge },
+    browser: { ...current.browser, ...overrides.browser },
+    loader: { ...current.loader, ...overrides.loader },
+    client: { ...current.client, ...overrides.client },
+    isPublic: overrides.isPublic ?? current.isPublic,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Derivation: Cache-Control headers (browser layer)
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a `Cache-Control` header from a named profile.
+ * Returns a headers object ready to spread into route `headers()`.
  */
-export function cacheHeaders(
-  profileOrConfig: CacheProfile | CacheHeadersConfig,
-): Record<string, string> {
-  const config = typeof profileOrConfig === "string" ? PROFILES[profileOrConfig] : profileOrConfig;
+export function cacheHeaders(profile: CacheProfileName): Record<string, string> {
+  const p = PROFILES[profile];
 
-  if (!config.isPublic || (config.sMaxAge === 0 && config.maxAge === 0)) {
+  if (!p.isPublic || (p.edge.fresh === 0 && p.browser.fresh === 0)) {
     return {
       "Cache-Control": "private, no-cache, no-store, must-revalidate",
     };
   }
 
   const parts: string[] = ["public"];
-
-  if (config.maxAge > 0) {
-    parts.push(`max-age=${config.maxAge}`);
-  } else {
-    parts.push("max-age=0");
-  }
-
-  if (config.sMaxAge > 0) {
-    parts.push(`s-maxage=${config.sMaxAge}`);
-  }
-
-  if (config.staleWhileRevalidate > 0) {
-    parts.push(`stale-while-revalidate=${config.staleWhileRevalidate}`);
-  }
+  parts.push(p.browser.fresh > 0 ? `max-age=${p.browser.fresh}` : "max-age=0");
+  if (p.edge.fresh > 0) parts.push(`s-maxage=${p.edge.fresh}`);
+  if (p.browser.swr > 0) parts.push(`stale-while-revalidate=${p.browser.swr}`);
+  if (p.browser.sie > 0) parts.push(`stale-if-error=${p.browser.sie}`);
 
   return {
     "Cache-Control": parts.join(", "),
@@ -120,83 +187,61 @@ export function cacheHeaders(
   };
 }
 
-/**
- * Get the raw config for a named cache profile.
- * Useful when you need the numeric values (e.g. for custom logic).
- */
-export function getCacheProfileConfig(profile: CacheProfile): CacheHeadersConfig {
-  return PROFILES[profile];
+// ---------------------------------------------------------------------------
+// Derivation: Edge cache config (for workerEntry SWR/SIE logic)
+// ---------------------------------------------------------------------------
+
+export interface EdgeCacheConfig {
+  fresh: number;
+  swr: number;
+  sie: number;
+  isPublic: boolean;
 }
 
-/**
- * Override the default TTLs for a cache profile.
- * Useful when the built-in values don't match your site's
- * freshness requirements (e.g., longer product TTL for low-traffic stores).
- *
- * @example
- * ```ts
- * setCacheProfileConfig("product", { maxAge: 120, sMaxAge: 600, staleWhileRevalidate: 7200, isPublic: true });
- * ```
- */
-export function setCacheProfileConfig(profile: CacheProfile, config: CacheHeadersConfig): void {
-  PROFILES[profile] = config;
+export function edgeCacheConfig(profile: CacheProfileName): EdgeCacheConfig {
+  const p = PROFILES[profile];
+  return { ...p.edge, isPublic: p.isPublic };
 }
 
 // ---------------------------------------------------------------------------
-// Client-side route cache defaults (TanStack Router staleTime / gcTime)
+// Derivation: Client-side route cache defaults (TanStack Router)
 // ---------------------------------------------------------------------------
 
-interface RouteCacheDefaults {
-  /** How long route data is considered fresh on the client (ms). */
-  staleTime: number;
-  /** How long stale data is kept in memory before garbage collection (ms). */
-  gcTime: number;
-}
-
-const ROUTE_CACHE: Record<CacheProfile, RouteCacheDefaults> = {
-  static: { staleTime: 5 * 60_000, gcTime: 30 * 60_000 },
-  product: { staleTime: 60_000, gcTime: 5 * 60_000 },
-  listing: { staleTime: 60_000, gcTime: 5 * 60_000 },
-  search: { staleTime: 30_000, gcTime: 2 * 60_000 },
-  cart: { staleTime: 0, gcTime: 0 },
-  private: { staleTime: 0, gcTime: 0 },
-  none: { staleTime: 0, gcTime: 0 },
-};
-
 /**
  * Returns `{ staleTime, gcTime }` for a cache profile, ready to spread
  * into a TanStack Router route definition.
  *
  * In dev mode, uses short staleTime (5s) to keep data fresh enough for
- * development while avoiding redundant re-fetches during rapid
- * interactions (e.g. variant switching on a PDP).
- *
- * @example
- * ```ts
- * export const Route = createFileRoute("/$")({
- *   ...routeCacheDefaults("listing"),
- *   loader: ...,
- *   headers: () => cacheHeaders("listing"),
- * });
- * ```
+ * development while avoiding redundant re-fetches.
  */
-export function routeCacheDefaults(profile: CacheProfile): RouteCacheDefaults {
+export function routeCacheDefaults(profile: CacheProfileName): { staleTime: number; gcTime: number } {
   const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
   const isDev = env?.DECO_CACHE_DISABLE === "true" || env?.NODE_ENV === "development";
   if (isDev) return { staleTime: 5_000, gcTime: 30_000 };
-  return ROUTE_CACHE[profile];
+  return { ...PROFILES[profile].client };
+}
+
+// ---------------------------------------------------------------------------
+// Derivation: Loader cache options (for createCachedLoader)
+// ---------------------------------------------------------------------------
+
+export interface LoaderCacheOptions {
+  policy: "stale-while-revalidate";
+  maxAge: number;
+  staleIfError: number;
 }
 
 /**
- * Override the client-side route cache defaults for a profile.
- *
- * @example
- * ```ts
- * setRouteCacheDefaults("product", { staleTime: 120_000, gcTime: 10 * 60_000 });
- * ```
+ * Get loader-layer cache options for a profile.
+ * Pass directly to `createCachedLoader` as the options argument.
  */
-export function setRouteCacheDefaults(profile: CacheProfile, defaults: RouteCacheDefaults): void {
-  ROUTE_CACHE[profile] = defaults;
+export function loaderCacheOptions(profile: CacheProfileName): LoaderCacheOptions {
+  const p = PROFILES[profile];
+  return {
+    policy: "stale-while-revalidate",
+    maxAge: p.loader.fresh,
+    staleIfError: p.loader.sie,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -205,11 +250,10 @@ export function setRouteCacheDefaults(profile: CacheProfile, defaults: RouteCach
 
 interface CachePattern {
   test: (pathname: string, searchParams: URLSearchParams) => boolean;
-  profile: CacheProfile;
+  profile: CacheProfileName;
 }
 
 const builtinPatterns: CachePattern[] = [
-  // Private routes — must be first (highest priority)
   {
     test: (p) =>
       p.startsWith("/cart") ||
@@ -219,7 +263,6 @@ const builtinPatterns: CachePattern[] = [
       p.startsWith("/my-account"),
     profile: "private",
   },
-  // Internal / API routes
   {
     test: (p) =>
       p.startsWith("/api/") ||
@@ -228,17 +271,14 @@ const builtinPatterns: CachePattern[] = [
       p.startsWith("/_build"),
     profile: "none",
   },
-  // Search pages
   {
     test: (p, sp) => p === "/s" || p.startsWith("/s/") || sp.has("q"),
     profile: "search",
   },
-  // PDP — VTEX convention: URL ends with /p
   {
     test: (p) => p.endsWith("/p") || /\/p[?#]/.test(p),
     profile: "product",
   },
-  // Home page
   {
     test: (p) => p === "/" || p === "",
     profile: "static",
@@ -250,14 +290,6 @@ const customPatterns: CachePattern[] = [];
 /**
  * Register additional URL-to-profile patterns. Custom patterns are evaluated
  * before built-in ones, so they can override defaults.
- *
- * @example
- * ```ts
- * registerCachePattern({
- *   test: (p) => p.startsWith("/institucional"),
- *   profile: "static",
- * });
- * ```
  */
 export function registerCachePattern(pattern: CachePattern): void {
   customPatterns.push(pattern);
@@ -266,9 +298,9 @@ export function registerCachePattern(pattern: CachePattern): void {
 /**
  * Detect the appropriate cache profile based on a URL.
  * Evaluates custom patterns first, then built-in patterns.
- * Falls back to "listing" (conservative public cache) for unmatched paths.
+ * Falls back to "listing" for unmatched paths.
  */
-export function detectCacheProfile(pathnameOrUrl: string | URL): CacheProfile {
+export function detectCacheProfile(pathnameOrUrl: string | URL): CacheProfileName {
   let pathname: string;
   let searchParams: URLSearchParams;
 
@@ -289,6 +321,5 @@ export function detectCacheProfile(pathnameOrUrl: string | URL): CacheProfile {
     if (pattern.test(pathname, searchParams)) return pattern.profile;
   }
 
-  // Default: listing (conservative, short edge TTL)
   return "listing";
 }

package/src/sdk/cachedLoader.ts

@@ -1,36 +1,30 @@
 /**
- * Server-side loader caching with stale-while-revalidate semantics.
+ * Server-side loader caching with stale-while-revalidate + stale-if-error.
  *
- * This provides a lightweight in-memory cache layer for commerce loaders
- * that runs on the server during SSR, without requiring TanStack Query
- * (which is optional and operates at the client/route level).
+ * Provides an in-memory cache layer for commerce loaders during SSR.
+ * Supports:
+ * - Single-flight dedup (identical concurrent requests share one fetch)
+ * - SWR: serve stale immediately, refresh in background
+ * - SIE: on origin error, fall back to stale entry within a configurable window
  *
- * For client-side SWR, use TanStack Query's `staleTime` / `gcTime`.
+ * Can be configured with explicit options or by passing a cache profile name
+ * (e.g. "product") which derives timing from the unified profile system.
  */
 
+import type { CacheProfileName } from "./cacheHeaders";
+
 export type CachePolicy = "no-store" | "no-cache" | "stale-while-revalidate";
 
 export interface CachedLoaderOptions {
   policy: CachePolicy;
   /** Max age in milliseconds before an entry is considered stale. Default: 60_000 (1 min). */
   maxAge?: number;
+  /** How long to serve stale on origin error, in ms. Default: 0 (no error fallback). */
+  staleIfError?: number;
   /** Key function to generate a cache key from loader props. Default: JSON.stringify. */
   keyFn?: (props: unknown) => string;
 }
 
-/**
- * Loader module interface for modules that export cache configuration alongside
- * their default loader function. Mirrors deco-cx/apps pattern where loaders
- * can declare their own caching policy.
- *
- * @example
- * ```ts
- * // In a loader file:
- * export const cache = "stale-while-revalidate";
- * export const cacheKey = (props: any) => `myLoader:${props.slug}`;
- * export default async function myLoader(props: Props) { ... }
- * ```
- */
 export interface LoaderModule<TProps = any, TResult = any> {
   default: (props: TProps) => Promise<TResult>;
   cache?: CachePolicy | { maxAge: number };
@@ -57,24 +51,49 @@ function evictIfNeeded() {
 
 const inflightRequests = new Map<string, Promise<unknown>>();
 
+function resolveOptions(
+  optionsOrProfile: CachedLoaderOptions | CacheProfileName,
+): CachedLoaderOptions {
+  if (typeof optionsOrProfile === "string") {
+    // Lazy import to avoid circular dependency at module load time.
+    // loaderCacheOptions() reads from the PROFILES map in cacheHeaders.ts.
+    const { loaderCacheOptions } = require("./cacheHeaders") as typeof import("./cacheHeaders");
+    return loaderCacheOptions(optionsOrProfile);
+  }
+  return optionsOrProfile;
+}
+
 /**
- * Wraps a loader function with server-side caching and single-flight dedup.
+ * Wraps a loader function with server-side caching, single-flight dedup,
+ * and stale-if-error resilience.
+ *
+ * Accepts either explicit options or a cache profile name:
  *
  * @example
  * ```ts
- * const cachedProductList = createCachedLoader(
- *   "vtex/loaders/productList",
- *   vtexProductList,
- *   { policy: "stale-while-revalidate", maxAge: 30_000 }
- * );
+ * // Profile-driven (recommended):
+ * const cachedPDP = createCachedLoader("vtex/productDetailsPage", pdpLoader, "product");
+ *
+ * // Explicit options (when loader needs different timing than its profile):
+ * const cachedSuggestions = createCachedLoader("vtex/suggestions", suggestionsLoader, {
+ *   policy: "stale-while-revalidate",
+ *   maxAge: 120_000,
+ *   staleIfError: 300_000,
+ * });
  * ```
  */
 export function createCachedLoader<TProps, TResult>(
   name: string,
   loaderFn: (props: TProps) => Promise<TResult>,
-  options: CachedLoaderOptions,
+  optionsOrProfile: CachedLoaderOptions | CacheProfileName,
 ): (props: TProps) => Promise<TResult> {
-  const { policy, maxAge = DEFAULT_MAX_AGE, keyFn = JSON.stringify } = options;
+  const resolved = resolveOptions(optionsOrProfile);
+  const {
+    policy,
+    maxAge = DEFAULT_MAX_AGE,
+    staleIfError = 0,
+    keyFn = JSON.stringify,
+  } = resolved;
 
   const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
   const isDev = env?.DECO_CACHE_DISABLE === "true" || env?.NODE_ENV === "development";
@@ -84,11 +103,9 @@ export function createCachedLoader<TProps, TResult>(
   return async (props: TProps): Promise<TResult> => {
     const cacheKey = `${name}::${keyFn(props)}`;
 
-    // Single-flight dedup: if an identical request is already in-flight, reuse it
     const inflight = inflightRequests.get(cacheKey);
     if (inflight) return inflight as Promise<TResult>;
 
-    // In dev mode, skip SWR cache but keep inflight dedup
     if (isDev) {
       const promise = loaderFn(props).finally(() => inflightRequests.delete(cacheKey));
       inflightRequests.set(cacheKey, promise);
@@ -101,7 +118,6 @@ export function createCachedLoader<TProps, TResult>(
 
     if (policy === "no-cache") {
       if (entry && !isStale) return entry.value;
-      // Stale or missing — fetch fresh
     }
 
     if (policy === "stale-while-revalidate") {
@@ -109,7 +125,6 @@ export function createCachedLoader<TProps, TResult>(
 
       if (entry && isStale && !entry.refreshing) {
         entry.refreshing = true;
-        // Fire-and-forget background refresh
         loaderFn(props)
           .then((result) => {
             cache.set(cacheKey, {
@@ -119,7 +134,12 @@ export function createCachedLoader<TProps, TResult>(
             });
           })
           .catch(() => {
+            // Background refresh failed — entry stays stale.
+            // If past the SIE window, evict so we don't serve indefinitely stale data.
             entry.refreshing = false;
+            if (staleIfError > 0 && now - entry.createdAt > maxAge + staleIfError) {
+              cache.delete(cacheKey);
+            }
           });
         return entry.value;
       }
@@ -140,6 +160,16 @@ export function createCachedLoader<TProps, TResult>(
       })
       .catch((err) => {
         inflightRequests.delete(cacheKey);
+        // SIE fallback: if we have a stale entry within the error window, return it
+        if (staleIfError > 0 && entry) {
+          const age = now - entry.createdAt;
+          if (age < maxAge + staleIfError) {
+            console.warn(
+              `[cachedLoader] ${name}: origin error, serving stale entry (age=${Math.round(age / 1000)}s, sie=${Math.round(staleIfError / 1000)}s)`,
+            );
+            return entry.value;
+          }
+        }
         throw err;
       });
 
@@ -151,15 +181,6 @@ export function createCachedLoader<TProps, TResult>(
 /**
  * Create a cached loader from a module that exports `cache` and/or `cacheKey`.
  * Falls back to the provided defaults if the module doesn't declare them.
- *
- * @example
- * ```ts
- * import * as myLoaderModule from "./loaders/myLoader";
- * const cached = createCachedLoaderFromModule("myLoader", myLoaderModule, {
- *   policy: "stale-while-revalidate",
- *   maxAge: 60_000,
- * });
- * ```
  */
 export function createCachedLoaderFromModule<TProps, TResult>(
   name: string,
@@ -188,7 +209,12 @@ export function createCachedLoaderFromModule<TProps, TResult>(
       }
     : defaults?.keyFn;
 
-  return createCachedLoader(name, mod.default, { policy, maxAge, keyFn });
+  return createCachedLoader(name, mod.default, {
+    policy,
+    maxAge,
+    staleIfError: defaults?.staleIfError,
+    keyFn,
+  });
 }
 
 /** Clear all cached entries. Useful for decofile hot-reload. */

package/src/sdk/index.ts

@@ -7,15 +7,20 @@ export {
   getLoaderCacheStats,
 } from "./cachedLoader";
 export {
-  type CacheHeadersConfig,
-  type CacheProfile,
+  type CacheProfileConfig,
+  type CacheProfileName,
+  type CacheProfileOverrides,
+  type CacheTimingWindow,
+  type EdgeCacheConfig,
+  type LoaderCacheOptions,
   cacheHeaders,
   detectCacheProfile,
-  getCacheProfileConfig,
+  edgeCacheConfig,
+  getCacheProfile,
+  loaderCacheOptions,
   registerCachePattern,
   routeCacheDefaults,
-  setCacheProfileConfig,
-  setRouteCacheDefaults,
+  setCacheProfile,
 } from "./cacheHeaders";
 export { clx } from "./clx";
 export { decodeCookie, deleteCookie, getCookie, getServerSideCookie, setCookie } from "./cookie";

package/src/sdk/workerEntry.ts

@@ -26,10 +26,11 @@
  */
 
 import {
-  type CacheProfile,
+  type CacheProfileName,
   cacheHeaders,
   detectCacheProfile,
-  getCacheProfileConfig,
+  edgeCacheConfig,
+  getCacheProfile,
 } from "./cacheHeaders";
 import { buildHtmlShell } from "./htmlShell";
 import { cleanPathForCacheKey } from "./urlUtils";
@@ -122,7 +123,7 @@ export interface DecoWorkerEntryOptions {
    * Override the default cache profile detection.
    * Return `null` to fall through to the built-in detector.
    */
-  detectProfile?: (url: URL) => CacheProfile | null;
+  detectProfile?: (url: URL) => CacheProfileName | null;
 
   /**
    * Whether to create device-specific cache keys (mobile vs desktop).
@@ -382,7 +383,7 @@ export function createDecoWorkerEntry(
     return true;
   }
 
-  function getProfile(url: URL): CacheProfile {
+  function getProfile(url: URL): CacheProfileName {
     if (customDetect) {
       const custom = customDetect(url);
       if (custom !== null) return custom;
@@ -728,43 +729,120 @@ export function createDecoWorkerEntry(
           ? ((caches as unknown as { default?: Cache }).default ?? null)
           : null;
 
-      if (cache) {
+      const profile = getProfile(url);
+      const edgeConfig = edgeCacheConfig(profile);
+
+      // Helper: dress a response with proper client-facing headers
+      function dressResponse(resp: Response, xCache: string, extra?: Record<string, string>): Response {
+        const out = new Response(resp.body, resp);
+        const hdrs = cacheHeaders(profile);
+        for (const [k, v] of Object.entries(hdrs)) out.headers.set(k, v);
+        out.headers.set("CDN-Cache-Control", "no-store");
+        out.headers.set("X-Cache", xCache);
+        out.headers.set("X-Cache-Profile", profile);
+        if (segment) out.headers.set("X-Cache-Segment", hashSegment(segment));
+        if (cacheVersionEnv !== false) {
+          const v = (env[cacheVersionEnv] as string) || "";
+          if (v) out.headers.set("X-Cache-Version", v);
+        }
+        if (extra) for (const [k, v] of Object.entries(extra)) out.headers.set(k, v);
+        appendResourceHints(out);
+        return out;
+      }
+
+      // Helper: store a response in Cache API with the full retention window
+      function storeInCache(resp: Response) {
+        if (!cache) return;
         try {
-          const cached = await cache.match(cacheKey);
-          if (cached) {
-            const hit = new Response(cached.body, cached);
-            hit.headers.set("X-Cache", "HIT");
-            if (segment) hit.headers.set("X-Cache-Segment", hashSegment(segment));
-            if (cacheVersionEnv !== false) {
-              const v = (env[cacheVersionEnv] as string) || "";
-              if (v) hit.headers.set("X-Cache-Version", v);
-            }
-            // Restore client-facing Cache-Control (the stored version uses sMaxAge
-            // as max-age for Cache API TTL, which would leak to the CDN auto-cache
-            // and cause stale HTML after deploys — the CDN caches under the raw URL,
-            // bypassing BUILD_HASH versioned keys).
-            const hitProfile = getProfile(url);
-            const hitHeaders = cacheHeaders(hitProfile);
-            for (const [k, v] of Object.entries(hitHeaders)) {
-              hit.headers.set(k, v);
+          const storageTtl = edgeConfig.fresh + Math.max(edgeConfig.swr, edgeConfig.sie);
+          const toStore = resp.clone();
+          toStore.headers.set("Cache-Control", `public, max-age=${storageTtl}`);
+          toStore.headers.set("X-Deco-Stored-At", String(Date.now()));
+          toStore.headers.delete("CDN-Cache-Control");
+          ctx.waitUntil(cache.put(cacheKey, toStore));
+        } catch {
+          // Cache API unavailable
+        }
+      }
+
+      // Helper: background revalidation (fetch origin, store result)
+      function revalidateInBackground() {
+        ctx.waitUntil(
+          Promise.resolve(serverEntry.fetch(request, env, ctx)).then((origin) => {
+            if (origin.status === 200 && !origin.headers.has("set-cookie")) {
+              storeInCache(origin);
             }
-            // Prevent CDN from auto-caching this response under the raw URL.
-            // The Worker manages edge caching via caches.default with versioned keys;
-            // CDN auto-caching would bypass that versioning and serve stale HTML
-            // after deploys (referencing old CSS/JS fingerprinted filenames).
-            hit.headers.set("CDN-Cache-Control", "no-store");
-            appendResourceHints(hit);
-            return hit;
-          }
+          }).catch(() => {
+            // Background revalidation failed — stale entry stays until SIE expires
+          }),
+        );
+      }
+
+      // --- Edge cache check with SWR + SIE ---
+      let cached: Response | undefined;
+      if (cache) {
+        try {
+          cached = await cache.match(cacheKey) ?? undefined;
         } catch {
-          // Cache API unavailable in this environment — proceed without cache
+          // Cache API unavailable
         }
       }
 
-      // Cache MISS — fetch from origin
-      const origin = await serverEntry.fetch(request, env, ctx);
+      if (cached && edgeConfig.isPublic && edgeConfig.fresh > 0) {
+        const storedAtStr = cached.headers.get("X-Deco-Stored-At");
+        const storedAt = storedAtStr ? Number(storedAtStr) : 0;
+        const ageMs = storedAt > 0 ? Date.now() - storedAt : Infinity;
+        const ageSec = ageMs / 1000;
+
+        if (ageSec < edgeConfig.fresh) {
+          // FRESH HIT — serve immediately
+          return dressResponse(cached, "HIT");
+        }
+
+        if (ageSec < edgeConfig.fresh + edgeConfig.swr) {
+          // STALE-HIT within SWR window — serve stale, revalidate in background
+          revalidateInBackground();
+          return dressResponse(cached, "STALE-HIT", { "X-Cache-Age": String(Math.round(ageSec)) });
+        }
+
+        // Past SWR window but still in cache (within SIE window) — keep reference
+        // for potential error fallback below
+      }
+
+      // Cache MISS or past SWR window — fetch from origin
+      let origin: Response;
+      try {
+        origin = await serverEntry.fetch(request, env, ctx);
+      } catch (err) {
+        // Origin fetch threw — SIE fallback if we have a stale entry
+        if (cached && edgeConfig.sie > 0) {
+          const storedAtStr = cached.headers.get("X-Deco-Stored-At");
+          const storedAt = storedAtStr ? Number(storedAtStr) : 0;
+          const ageSec = storedAt > 0 ? (Date.now() - storedAt) / 1000 : Infinity;
+          if (ageSec < edgeConfig.fresh + edgeConfig.sie) {
+            console.warn(`[edge-cache] Origin threw, serving stale (age=${Math.round(ageSec)}s, sie=${edgeConfig.sie}s)`);
+            return dressResponse(cached, "STALE-ERROR", { "X-Cache-Age": String(Math.round(ageSec)) });
+          }
+        }
+        throw err;
+      }
 
       if (origin.status !== 200) {
+        // Non-200 origin — SIE fallback on 5xx/429
+        if (origin.status >= 500 || origin.status === 429) {
+          if (cached && edgeConfig.sie > 0) {
+            const storedAtStr = cached.headers.get("X-Deco-Stored-At");
+            const storedAt = storedAtStr ? Number(storedAtStr) : 0;
+            const ageSec = storedAt > 0 ? (Date.now() - storedAt) / 1000 : Infinity;
+            if (ageSec < edgeConfig.fresh + edgeConfig.sie) {
+              console.warn(`[edge-cache] Origin ${origin.status}, serving stale (age=${Math.round(ageSec)}s)`);
+              return dressResponse(cached, "STALE-ERROR", {
+                "X-Cache-Age": String(Math.round(ageSec)),
+                "X-Cache-Origin-Status": String(origin.status),
+              });
+            }
+          }
+        }
         const resp = new Response(origin.body, origin);
         resp.headers.set("X-Cache", "BYPASS");
         resp.headers.set("X-Cache-Reason", `status:${origin.status}`);
@@ -774,12 +852,9 @@ export function createDecoWorkerEntry(
 
       // Responses with Set-Cookie must never be cached — they carry
       // per-user session/auth tokens that would leak to other users.
-      const hasSetCookie = origin.headers.has("set-cookie");
-      if (hasSetCookie) {
+      if (origin.headers.has("set-cookie")) {
         const resp = new Response(origin.body, origin);
         resp.headers.set("Cache-Control", "private, no-cache, no-store, must-revalidate");
-        // CDN-Cache-Control takes precedence over Cache-Control on Cloudflare.
-        // If the origin set it, Cloudflare would ignore our private directive.
         resp.headers.delete("CDN-Cache-Control");
         resp.headers.set("X-Cache", "BYPASS");
         resp.headers.set("X-Cache-Reason", "set-cookie");
@@ -787,11 +862,9 @@ export function createDecoWorkerEntry(
         return resp;
       }
 
-      // Determine the right cache profile for this URL
-      const profile = getProfile(url);
-      const profileConfig = getCacheProfileConfig(profile);
+      const profileConfig = getCacheProfile(profile);
 
-      if (!profileConfig.isPublic || profileConfig.sMaxAge === 0) {
+      if (!profileConfig.isPublic || profileConfig.edge.fresh === 0) {
         const resp = new Response(origin.body, origin);
         resp.headers.set("Cache-Control", "private, no-cache, no-store, must-revalidate");
         resp.headers.set("X-Cache", "BYPASS");
@@ -800,48 +873,9 @@ export function createDecoWorkerEntry(
         return resp;
       }
 
-      const headers = cacheHeaders(profile);
-
-      const toReturn = new Response(origin.body, {
-        status: origin.status,
-        statusText: origin.statusText,
-        headers: new Headers(origin.headers),
-      });
-
-      // Apply profile-specific cache headers for the client response
-      for (const [k, v] of Object.entries(headers)) {
-        toReturn.headers.set(k, v);
-      }
-      toReturn.headers.set("X-Cache", "MISS");
-      toReturn.headers.set("X-Cache-Profile", profile);
-      if (segment) toReturn.headers.set("X-Cache-Segment", hashSegment(segment));
-      if (cacheVersionEnv !== false) {
-        const v = (env[cacheVersionEnv] as string) || "";
-        if (v) toReturn.headers.set("X-Cache-Version", v);
-      }
-
-      // Prevent CDN from auto-caching this response under the raw URL.
-      // Edge caching is managed by the Worker via caches.default with
-      // BUILD_HASH-versioned keys; CDN auto-caching would bypass versioning
-      // and serve stale HTML after deploys.
-      toReturn.headers.set("CDN-Cache-Control", "no-store");
-      appendResourceHints(toReturn);
-
-      // For Cache API storage, use sMaxAge as max-age since the Cache API
-      // ignores s-maxage and only respects max-age for TTL decisions.
-      if (cache) {
-        try {
-          const toStore = toReturn.clone();
-          toStore.headers.set("Cache-Control", `public, max-age=${profileConfig.sMaxAge}`);
-          // Remove CDN-Cache-Control from stored version — it's only needed
-          // on the response to the client to prevent CDN auto-caching.
-          toStore.headers.delete("CDN-Cache-Control");
-          ctx.waitUntil(cache.put(cacheKey, toStore));
-        } catch {
-          // Cache API unavailable — skip storing
-        }
-      }
-
+      // Store in Cache API and return
+      const toReturn = dressResponse(origin, "MISS");
+      storeInCache(origin);
       return toReturn;
     },
   };