@decocms/tanstack 7.0.0

package/src/routes/cmsRoute.ts

@@ -0,0 +1,706 @@
+/**
+ * CMS Route Helpers
+ *
+ * Reusable building blocks for CMS catch-all and homepage routes.
+ * Since TanStack Router requires routes to be file-based in the site repo,
+ * we export helper functions and config that sites use in their route files.
+ *
+ * @example Site's `src/routes/$.tsx`:
+ * ```ts
+ * import { createFileRoute, notFound } from "@tanstack/react-router";
+ * import { loadCmsPage, cmsRouteConfig } from "@decocms/start/routes";
+ * import { DecoPageRenderer } from "@decocms/start/hooks";
+ *
+ * export const Route = createFileRoute("/$")({
+ *   ...cmsRouteConfig({
+ *     siteName: "My Store",
+ *     defaultTitle: "My Store - Best products",
+ *     ignoreSearchParams: ["skuId"],
+ *   }),
+ * });
+ * ```
+ */
+
+import { createServerFn } from "@tanstack/react-start";
+import {
+  getCookies,
+  getRequest,
+  getRequestHeader,
+  getRequestUrl,
+  setResponseHeader,
+} from "@tanstack/react-start/server";
+import { createElement } from "react";
+import {
+  extractSeoFromProps,
+  extractSeoFromSections,
+  getDeferredRawProps,
+  getSiteSeo,
+  preloadSectionComponents,
+  reExtractRawProps,
+  resolveDecoPage,
+  resolveDeferredSection,
+  resolveDeferredSectionFull,
+  runSectionLoaders,
+  runSingleSectionLoader,
+} from "@decocms/blocks/cms";
+import type { DeferredSection, MatcherContext, PageSeo, ResolvedSection } from "@decocms/blocks/cms";
+import { withTracing } from "@decocms/blocks/middleware/observability";
+import {
+  type CacheProfileName,
+  cacheHeaders,
+  detectCacheProfile,
+  routeCacheDefaults,
+} from "@decocms/blocks/sdk/cacheHeaders";
+import { normalizeUrlsInObject } from "@decocms/blocks/sdk/normalizeUrls";
+import { type Device, detectDevice } from "@decocms/blocks/sdk/useDevice";
+import { derivePageUrl, isClientNavigation } from "./pageUrl";
+import { dedupeGlobals, resolveSiteGlobals } from "./withSiteGlobals";
+
+const isServer = typeof document === "undefined";
+
+// Section chunk manifest — maps section keys to chunk filenames.
+// Generated by decoVitePlugin's generateBundle hook. Used to emit
+// <link rel="modulepreload"> hints for eager sections.
+let sectionChunkMap: Record<string, string> = {};
+
+/**
+ * Set the section chunk manifest. Called by the site's worker entry
+ * or setup after loading the manifest.
+ */
+export function setSectionChunkMap(map: Record<string, string>): void {
+  sectionChunkMap = map;
+}
+
+// ---------------------------------------------------------------------------
+// Server function — loads a CMS page, runs section loaders, detects cache
+// ---------------------------------------------------------------------------
+
+type PageResult = Awaited<ReturnType<typeof loadCmsPageInternal>>;
+const pageInflight = new Map<string, Promise<PageResult>>();
+
+async function loadCmsPageInternal(fullPath: string) {
+  const [basePath] = fullPath.split("?");
+  // On client-side navigation getRequestUrl() is the /_serverFn/... endpoint,
+  // not the page being loaded — derivePageUrl rebuilds the real page URL so
+  // matcherCtx.url / __pageUrl stay consistent with __pagePath (#280).
+  const serverUrl = getRequestUrl();
+  const urlWithSearch = derivePageUrl(fullPath, serverUrl);
+
+  const originRequest = getRequest();
+  const matcherCtx: MatcherContext = {
+    userAgent: getRequestHeader("user-agent") ?? "",
+    url: urlWithSearch,
+    path: basePath,
+    cookies: getCookies(),
+    request: originRequest,
+    isClientNavigation: isClientNavigation(fullPath, serverUrl),
+  };
+  const page = await resolveDecoPage(basePath, matcherCtx);
+  if (!page) return null;
+
+  const request = new Request(urlWithSearch, {
+    headers: originRequest.headers,
+  });
+
+  // Resolve page sections and site globals in parallel. Globals are merged
+  // into the same `resolvedSections` array so the path through this server
+  // function is identical for SSR (F5) and SPA (<Link>) navigations — see
+  // #233 for the previous SPA-breakage when `withSiteGlobals` ran client-side
+  // and saw an empty client-bundled `blocks.gen.ts`.
+  const [enrichedSections, globals] = await Promise.all([
+    runSectionLoaders(page.resolvedSections, request),
+    resolveSiteGlobals(),
+  ]);
+
+  // Page sections take precedence over globals — dedupe drops any global
+  // whose component is already rendered by the page.
+  const mergedSections: ResolvedSection[] = [
+    ...dedupeGlobals(globals.resolvedSections, enrichedSections),
+    ...enrichedSections,
+  ];
+
+  // Pre-import eager section modules so their default exports are cached
+  // in resolvedComponents. This ensures SSR renders with direct component
+  // refs, and the client hydration can skip React.lazy/Suspense.
+  const eagerKeys = mergedSections.map((s) => s.component);
+  await preloadSectionComponents(eagerKeys);
+
+  const cacheProfile = detectCacheProfile(basePath);
+  const ua = getRequestHeader("user-agent") ?? "";
+  const device = detectDevice(ua);
+
+  // Build SEO: merge page-level seo block (primary) with section-contributed SEO (secondary)
+  const seo = await buildPageSeo(page.seoSection, mergedSections, request);
+
+  // Destructure seoSection out — it's an internal artifact, not serialized to client
+  const { seoSection: _seo, ...pageData } = page;
+
+  return {
+    ...pageData,
+    resolvedSections: normalizeUrlsInObject(mergedSections),
+    deferredSections: normalizeUrlsInObject(page.deferredSections),
+    cacheProfile,
+    pageUrl: urlWithSearch,
+    pagePath: basePath,
+    seo,
+    device,
+    siteGlobals: { rawRefs: globals.rawRefs },
+  };
+}
+
+export const loadCmsPage = createServerFn({ method: "GET" })
+  .inputValidator((data: unknown) => data as string)
+  .handler(async (ctx) => {
+    const fullPath = ctx.data;
+
+    // Use the full path (including query string) as the dedup key.
+    // Using basePath only caused /s?q=a and /s?q=b to share one promise,
+    // returning wrong/empty results for search and filtered PLPs.
+    const existing = pageInflight.get(fullPath);
+    if (existing) return existing;
+
+    const promise = loadCmsPageInternal(fullPath).finally(() => pageInflight.delete(fullPath));
+    pageInflight.set(fullPath, promise);
+    return promise;
+  });
+
+/**
+ * Same as loadCmsPage but hardcoded to "/" path.
+ * Avoids passing data through the server function for the homepage.
+ */
+export const loadCmsHomePage = createServerFn({ method: "GET" }).handler(async () => {
+  const request = getRequest();
+  const ua = getRequestHeader("user-agent") ?? "";
+  const serverUrl = getRequestUrl();
+  const matcherCtx: MatcherContext = {
+    userAgent: ua,
+    url: serverUrl.toString(),
+    path: "/",
+    cookies: getCookies(),
+    request,
+    isClientNavigation: isClientNavigation("/", serverUrl),
+  };
+  const page = await resolveDecoPage("/", matcherCtx);
+  if (!page) return null;
+  const [enrichedSections, globals] = await Promise.all([
+    runSectionLoaders(page.resolvedSections, request),
+    resolveSiteGlobals(),
+  ]);
+
+  const mergedSections: ResolvedSection[] = [
+    ...dedupeGlobals(globals.resolvedSections, enrichedSections),
+    ...enrichedSections,
+  ];
+
+  const eagerKeys = mergedSections.map((s) => s.component);
+  await preloadSectionComponents(eagerKeys);
+
+  const device = detectDevice(ua);
+  const seo = await buildPageSeo(page.seoSection, mergedSections, request);
+
+  const { seoSection: _seo, ...pageData } = page;
+
+  return {
+    ...pageData,
+    resolvedSections: normalizeUrlsInObject(mergedSections),
+    deferredSections: normalizeUrlsInObject(page.deferredSections),
+    pagePath: "/",
+    pageUrl: serverUrl.toString(),
+    seo,
+    device,
+    siteGlobals: { rawRefs: globals.rawRefs },
+  };
+});
+
+// ---------------------------------------------------------------------------
+// Deferred section loader — resolves + enriches a single section on demand
+// ---------------------------------------------------------------------------
+
+/**
+ * @deprecated Prefer TanStack native streaming via `deferredPromises` in the
+ * route loader. This POST server function is kept for backward compatibility
+ * and as a fallback for SPA navigations.
+ */
+export const loadDeferredSection = createServerFn({ method: "POST" })
+  .inputValidator(
+    (data: unknown) =>
+      data as {
+        component: string;
+        /** @deprecated rawProps are now resolved server-side from the deferred props cache. */
+        rawProps?: Record<string, any>;
+        pagePath: string;
+        pageUrl?: string;
+        /** Original position in the page section list — preserved for correct SPA ordering. */
+        index?: number;
+      },
+  )
+  .handler(async (ctx) => {
+    const { component, rawProps: clientRawProps, pagePath, pageUrl, index } = ctx.data;
+
+    const originRequest = getRequest();
+    const serverUrl = getRequestUrl().toString();
+    const matcherCtx: MatcherContext = {
+      userAgent: getRequestHeader("user-agent") ?? "",
+      url: pageUrl || serverUrl,
+      path: pagePath,
+      cookies: getCookies(),
+      request: originRequest,
+    };
+
+    // Resolve rawProps: prefer client-provided (backward compat), then server cache,
+    // then re-extract from the page as a last resort (handles cross-isolate cache miss
+    // on Cloudflare Workers and TTL expiry for slow-scrolling users).
+    const rawProps = clientRawProps
+      ?? (index !== undefined ? getDeferredRawProps(pagePath, component, index) : null)
+      ?? (index !== undefined
+        ? await reExtractRawProps(pagePath, component, index, matcherCtx)
+        : null);
+
+    if (!rawProps) {
+      console.warn(`[CMS] Deferred section cache miss: ${component} at index ${index} on ${pagePath}`);
+      return null;
+    }
+
+    const section = await withTracing(
+      "deco.section.deferred.load",
+      () => resolveDeferredSection(component, rawProps, pagePath, matcherCtx),
+      {
+        "section.name": component,
+        "page.path": pagePath,
+        ...(typeof index === "number" ? { "section.index": index } : {}),
+      },
+    );
+    if (!section) return null;
+
+    // Preserve original index for correct ordering in SPA navigation merge
+    if (index !== undefined) section.index = index;
+
+    const request = new Request(pageUrl || serverUrl, {
+      headers: originRequest.headers,
+    });
+    const enriched = await runSingleSectionLoader(section, request);
+
+    // Signal to the worker entry that this response is safe to edge-cache.
+    // Without this header, POST _serverFn responses are passed through
+    // without caching (checkout actions, invoke mutations, etc.).
+    setResponseHeader("X-Deco-Cacheable", "true");
+
+    return normalizeUrlsInObject(enriched);
+  });
+
+// ---------------------------------------------------------------------------
+// Pre-wrapped deferred section loader for IntersectionObserver-based rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Convenience wrapper around `loadDeferredSection` that matches the
+ * `loadDeferredSectionFn` prop signature of `DecoPageRenderer`.
+ *
+ * Pass this directly to `<DecoPageRenderer loadDeferredSectionFn={deferredSectionLoader} />`
+ * to enable IntersectionObserver-based lazy loading of deferred sections.
+ */
+export const deferredSectionLoader = async ({
+  component,
+  rawProps,
+  pagePath,
+  pageUrl,
+  index,
+}: {
+  component: string;
+  rawProps?: Record<string, unknown>;
+  pagePath: string;
+  pageUrl?: string;
+  index?: number;
+}): Promise<ResolvedSection | null> => {
+  return loadDeferredSection({
+    data: { component, rawProps, pagePath, pageUrl, index },
+  });
+};
+
+// ---------------------------------------------------------------------------
+// Default pending component — shown during SPA navigation while loader runs
+// ---------------------------------------------------------------------------
+
+export function CmsPagePendingFallback() {
+  return createElement(
+    "div",
+    { className: "w-full min-h-[60vh] flex flex-col gap-6 py-8" },
+    createElement("div", {
+      className: "skeleton animate-pulse w-full rounded",
+      style: { aspectRatio: "1440/400", minHeight: 200 },
+    }),
+    createElement(
+      "div",
+      { className: "px-4 lg:px-8 flex flex-col gap-4" },
+      createElement("div", { className: "skeleton animate-pulse w-48 h-8 rounded" }),
+      createElement(
+        "div",
+        { className: "grid grid-cols-2 lg:grid-cols-4 gap-4" },
+        ...Array.from({ length: 4 }, (_, i) =>
+          createElement("div", {
+            key: i,
+            className: "skeleton animate-pulse w-full h-48 lg:h-64 rounded",
+          }),
+        ),
+      ),
+    ),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Route configuration factory
+// ---------------------------------------------------------------------------
+
+export interface CmsRouteOptions {
+  /** Site name used in page titles (e.g. "Espaço Smart"). */
+  siteName: string;
+  /** Default page title when CMS page has no name. */
+  defaultTitle: string;
+  /** Default description for pages without section-contributed SEO. */
+  defaultDescription?: string;
+  /**
+   * Search params to exclude from loader deps.
+   * These params won't trigger a server re-fetch when they change.
+   * Defaults to `["skuId"]` — variant selection is client-side only.
+   */
+  ignoreSearchParams?: string[];
+  /** Custom pending component shown during SPA navigation. */
+  pendingComponent?: () => any;
+  /**
+   * Delay (ms) before showing the pending component during SPA navigation.
+   * If the loader resolves before this threshold, no pending UI is shown.
+   * Prevents skeleton flash on fast cache-hit navigations. Default: 200.
+   */
+  pendingMs?: number;
+  /**
+   * Minimum display time (ms) for the pending component once shown.
+   * Prevents jarring flash when data arrives shortly after the threshold.
+   * Default: 300.
+   */
+  pendingMinMs?: number;
+  /**
+   * SSR mode for this route.
+   * - `true` (default): Full SSR — loader + component render on server.
+   * - `'data-only'`: Loader runs on server, component renders on client only.
+   *   Use for interactive-heavy pages (PDP with zoom/variant selector).
+   * - `false`: Everything runs on client only.
+   */
+  ssr?: boolean | "data-only";
+}
+
+type CmsPageLoaderData = {
+  name?: string;
+  cacheProfile?: CacheProfileName;
+  seo?: PageSeo;
+  device?: Device;
+  resolvedSections?: Array<{ component: string }>;
+} | null;
+
+// ---------------------------------------------------------------------------
+// Page SEO assembly — merges page.seo block with section-contributed SEO
+// ---------------------------------------------------------------------------
+
+/**
+ * Process the resolved SEO section from page.seo, run its section loader
+ * if registered, apply title/description templates, and merge with
+ * section-contributed SEO.
+ */
+async function buildPageSeo(
+  seoSection: ResolvedSection | null | undefined,
+  enrichedSections: ResolvedSection[],
+  request: Request,
+): Promise<PageSeo> {
+  // Secondary source: SEO sections embedded in the sections array
+  const sectionSeo = extractSeoFromSections(enrichedSections);
+
+  // Site-wide SEO config from the "Site" app block — mirrors ctx.seo in
+  // the original deco-cx/deco framework. Provides fallback title,
+  // description, and templates when page-level seo doesn't supply them.
+  const siteSeo = getSiteSeo();
+
+  if (!seoSection) {
+    // No page.seo block — use site-wide SEO as primary, section-contributed as secondary
+    const merged: PageSeo = { ...sectionSeo };
+    if (siteSeo.title && !merged.title) merged.title = siteSeo.title;
+    if (siteSeo.description && !merged.description) merged.description = siteSeo.description;
+    if (siteSeo.image && !merged.image) merged.image = siteSeo.image;
+
+    // Apply site-level templates even when there is no page-level seo
+    // section. Without this, pages whose title comes from a content
+    // section (e.g. <h1> + sectionSeo) or from the site default would
+    // skip `siteSeo.titleTemplate`, causing prod-vs-worker title drift.
+    const titleTemplate = effectiveTemplate(siteSeo.titleTemplate);
+    const descTemplate = effectiveTemplate(siteSeo.descriptionTemplate);
+    if (titleTemplate && merged.title) {
+      merged.title = titleTemplate.replace("%s", merged.title);
+    }
+    if (descTemplate && merged.description) {
+      merged.description = descTemplate.replace("%s", merged.description);
+    }
+
+    return merged;
+  }
+
+  // Run the section loader on the seo section if one is registered
+  // (e.g., SEOPDP loader transforms {jsonLD: ProductDetailsPage} → {title, description, ...})
+  let enrichedProps = seoSection.props;
+  try {
+    const enriched = await runSingleSectionLoader(seoSection, request);
+    if (enriched) enrichedProps = enriched.props;
+  } catch {
+    // Section loader failed — use the raw resolved props
+  }
+
+  const pageSeo = extractSeoFromProps(enrichedProps);
+
+  // Replicate original SeoV2 loader logic: `_title ?? appTitle`
+  // When the page's seo block doesn't have a title/description,
+  // fall back to the Site app's seo config.
+  if (!pageSeo.title && siteSeo.title) pageSeo.title = siteSeo.title;
+  if (!pageSeo.description && siteSeo.description) pageSeo.description = siteSeo.description;
+  if (!pageSeo.image && siteSeo.image) pageSeo.image = siteSeo.image;
+
+  // Apply title/description templates.
+  // Priority: page-level template → site-level template → no-op.
+  // This mirrors the original: `(titleTemplate ?? "").trim().length === 0 ? "%s" : titleTemplate`
+  const rawProps = seoSection.props;
+  const titleTemplate =
+    effectiveTemplate(rawProps.titleTemplate as string | undefined) ??
+    effectiveTemplate(siteSeo.titleTemplate);
+  const descTemplate =
+    effectiveTemplate(rawProps.descriptionTemplate as string | undefined) ??
+    effectiveTemplate(siteSeo.descriptionTemplate);
+
+  if (titleTemplate && pageSeo.title) {
+    pageSeo.title = titleTemplate.replace("%s", pageSeo.title);
+  }
+  if (descTemplate && pageSeo.description) {
+    pageSeo.description = descTemplate.replace("%s", pageSeo.description);
+  }
+
+  // Primary source (page.seo) overrides secondary (section-contributed).
+  // Only truthy fields in pageSeo override — undefined keys don't clear sectionSeo.
+  return { ...sectionSeo, ...pageSeo };
+}
+
+/** Returns a non-trivial template string, or undefined for "%s" / empty / blank. */
+function effectiveTemplate(tmpl: string | undefined): string | undefined {
+  if (!tmpl || tmpl.trim() === "" || tmpl.trim() === "%s") return undefined;
+  return tmpl;
+}
+
+// ---------------------------------------------------------------------------
+// Head metadata builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build TanStack Router `head()` metadata from page-level and section-contributed SEO.
+ * Emits: title, description, canonical, OG tags, Twitter Card, robots directive.
+ */
+function buildHead(
+  loaderData: CmsPageLoaderData | undefined,
+  siteName: string,
+  defaultTitle: string,
+  defaultDescription?: string,
+) {
+  const seo = loaderData?.seo;
+  const title = seo?.title
+    ? seo.title
+    : loaderData?.name
+      ? `${loaderData.name} | ${siteName}`
+      : defaultTitle;
+  const description = seo?.description || defaultDescription;
+  const image = seo?.image;
+  const canonical = seo?.canonical;
+  const noIndex = seo?.noIndexing;
+
+  const meta: Record<string, string>[] = [{ title }];
+
+  if (description) {
+    meta.push({ name: "description", content: description });
+  }
+
+  // Robots — always emit a directive so crawlers see an explicit signal
+  meta.push({
+    name: "robots",
+    content: noIndex
+      ? "noindex, nofollow"
+      : "index, follow, max-image-preview:large, max-snippet:-1, max-video-preview:-1",
+  });
+
+  // Open Graph
+  meta.push({ property: "og:title", content: title });
+  if (description) meta.push({ property: "og:description", content: description });
+  if (image) meta.push({ property: "og:image", content: image });
+  meta.push({ property: "og:type", content: seo?.type || "website" });
+  if (canonical) meta.push({ property: "og:url", content: canonical });
+
+  // Twitter Card
+  meta.push({ name: "twitter:card", content: image ? "summary_large_image" : "summary" });
+  meta.push({ name: "twitter:title", content: title });
+  if (description) meta.push({ name: "twitter:description", content: description });
+  if (image) meta.push({ name: "twitter:image", content: image });
+
+  const links: Record<string, string>[] = [];
+  if (canonical) {
+    links.push({ rel: "canonical", href: canonical });
+  }
+
+  // Modulepreload hints for eager section chunks
+  if (loaderData?.resolvedSections) {
+    for (const s of loaderData.resolvedSections) {
+      const chunkFile = sectionChunkMap[s.component];
+      if (chunkFile) {
+        links.push({ rel: "modulepreload", href: `/${chunkFile}` });
+      }
+    }
+  }
+
+  // JSON-LD structured data — rendered as <script type="application/ld+json"> in <head>
+  const scripts: Array<{ type: string; children: string }> = [];
+  if (seo?.jsonLDs?.length) {
+    for (const jsonLD of seo.jsonLDs) {
+      scripts.push({
+        type: "application/ld+json",
+        children: JSON.stringify(jsonLD),
+      });
+    }
+  }
+
+  return { meta, links, scripts };
+}
+
+/**
+ * Returns a TanStack Router route config object for a CMS catch-all route.
+ * Spread the result into your `createFileRoute("/$")({...})` call.
+ *
+ * Includes: loaderDeps, loader, headers, head (with full SEO), staleTime/gcTime.
+ * Does NOT include: component, notFoundComponent (site provides these).
+ *
+ * SEO metadata is extracted from sections registered via `registerSeoSections()`.
+ * The `head()` function emits title, description, canonical, OG tags, and robots.
+ */
+export function cmsRouteConfig(options: CmsRouteOptions) {
+  const {
+    siteName,
+    defaultTitle,
+    defaultDescription,
+    ignoreSearchParams = ["skuId"],
+    pendingComponent,
+    pendingMs = 200,
+    pendingMinMs = 300,
+    ssr: ssrMode,
+  } = options;
+
+  const ignoreSet = new Set(ignoreSearchParams);
+
+  return {
+    // Catch-all search validation: preserve all URL search params so they
+    // reach loaderDeps. Without this, TanStack Router may strip unknown
+    // params (e.g. ?q=, filter.*, page, sort) during SPA navigation.
+    validateSearch: (search: Record<string, unknown>) =>
+      search as Record<string, string>,
+
+    loaderDeps: ({ search }: { search: Record<string, string> }) => {
+      const filtered = Object.fromEntries(
+        Object.entries(search ?? {}).filter(([k]) => !ignoreSet.has(k)),
+      );
+      return {
+        search: Object.keys(filtered).length ? filtered : undefined,
+      };
+    },
+
+    loader: async ({
+      params,
+      deps,
+    }: {
+      params: { _splat?: string };
+      deps: { search?: Record<string, string> };
+    }) => {
+      const basePath = "/" + (params._splat || "");
+      const searchStr = deps.search
+        ? "?" + new URLSearchParams(deps.search as Record<string, string>).toString()
+        : "";
+      const page = await loadCmsPage({ data: basePath + searchStr });
+      if (!page) return page;
+
+      if (!isServer && page.resolvedSections) {
+        const keys = page.resolvedSections.map((s: ResolvedSection) => s.component);
+        await preloadSectionComponents(keys);
+      }
+
+      // Deferred sections use client-side IntersectionObserver loading.
+      // DecoPageRenderer renders skeletons (LoadingFallback) during SSR and
+      // loads full section content via _serverFn when scrolled into view.
+      //
+      // Previously, SSR streaming via TanStack <Await> resolved ALL deferred
+      // sections server-side and streamed them in the initial HTML. This caused
+      // the browser to load ALL product shelf images at once (~3x more image
+      // requests than the IntersectionObserver path). Client SPA navigation
+      // also blocked on await Promise.all() for all deferred sections.
+      //
+      // The IO path (DeferredSectionWrapper) only fetches section data when
+      // the skeleton scrolls into view, matching Fresh/Deno partial behavior
+      // and significantly reducing initial image load and TBT.
+      return page;
+    },
+
+    ...(pendingComponent ? { pendingComponent } : {}),
+    pendingMs,
+    pendingMinMs,
+    ...(ssrMode !== undefined ? { ssr: ssrMode } : {}),
+
+    ...routeCacheDefaults("product"),
+
+    headers: ({ loaderData }: { loaderData?: CmsPageLoaderData }) => {
+      const profile = loaderData?.cacheProfile ?? "listing";
+      return cacheHeaders(profile);
+    },
+
+    head: ({ loaderData }: { loaderData?: CmsPageLoaderData }) =>
+      buildHead(loaderData, siteName, defaultTitle, defaultDescription),
+  };
+}
+
+/**
+ * Returns a TanStack Router route config for the CMS homepage route.
+ * Spread into `createFileRoute("/")({...})`.
+ *
+ * Like `cmsRouteConfig`, emits full SEO head metadata from section-contributed data.
+ */
+export function cmsHomeRouteConfig(options: {
+  defaultTitle: string;
+  defaultDescription?: string;
+  /** Site name for OG title composition. Defaults to defaultTitle. */
+  siteName?: string;
+  pendingComponent?: () => any;
+  /** Delay (ms) before showing pending component. Default: 200. */
+  pendingMs?: number;
+  /** Minimum display time (ms) for pending component. Default: 300. */
+  pendingMinMs?: number;
+}) {
+  const { defaultTitle, defaultDescription, siteName, pendingMs = 200, pendingMinMs = 300 } = options;
+
+  return {
+    loader: async () => {
+      const page = await loadCmsHomePage();
+      if (!page) return page;
+
+      if (!isServer && page.resolvedSections) {
+        const keys = page.resolvedSections.map((s: ResolvedSection) => s.component);
+        await preloadSectionComponents(keys);
+      }
+
+      // Deferred sections use client-side IntersectionObserver loading.
+      // See cmsRouteConfig loader for rationale.
+      return page;
+    },
+    ...(options.pendingComponent ? { pendingComponent: options.pendingComponent } : {}),
+    pendingMs,
+    pendingMinMs,
+    ...routeCacheDefaults("static"),
+    headers: () => cacheHeaders("static"),
+    head: ({ loaderData }: { loaderData?: CmsPageLoaderData }) =>
+      buildHead(loaderData, siteName ?? defaultTitle, defaultTitle, defaultDescription),
+  };
+}