@decocms/start 0.28.3 → 0.29.1

package/src/routes/cmsRoute.ts

@@ -36,6 +36,7 @@ import {
   extractSeoFromSections,
   resolveDecoPage,
   resolveDeferredSection,
+  resolveDeferredSectionFull,
 } from "../cms/resolve";
 import { getSiteSeo } from "../cms/loader";
 import { runSectionLoaders, runSingleSectionLoader } from "../cms/sectionLoaders";
@@ -122,6 +123,7 @@ async function loadCmsPageInternal(fullPath: string) {
     deferredSections: normalizeUrlsInObject(page.deferredSections),
     cacheProfile,
     pageUrl: urlWithSearch,
+    pagePath: basePath,
     seo,
     device,
   };
@@ -148,9 +150,10 @@ export const loadCmsPage = createServerFn({ method: "GET" })
 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: getRequestUrl().toString(),
+    url: serverUrl.toString(),
     path: "/",
     cookies: getCookies(),
     request,
@@ -171,6 +174,8 @@ export const loadCmsHomePage = createServerFn({ method: "GET" }).handler(async (
     ...pageData,
     resolvedSections: normalizeUrlsInObject(enrichedSections),
     deferredSections: normalizeUrlsInObject(page.deferredSections),
+    pagePath: "/",
+    pageUrl: serverUrl.toString(),
     seo,
     device,
   };
@@ -180,13 +185,25 @@ export const loadCmsHomePage = createServerFn({ method: "GET" }).handler(async (
 // 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; rawProps: Record<string, any>; pagePath: string; pageUrl?: string },
+      data as {
+        component: string;
+        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, pagePath, pageUrl } = ctx.data;
+    const { component, rawProps, pagePath, pageUrl, index } = ctx.data;
 
     const originRequest = getRequest();
     const serverUrl = getRequestUrl().toString();
@@ -201,6 +218,9 @@ export const loadDeferredSection = createServerFn({ method: "POST" })
     const section = await resolveDeferredSection(component, rawProps, pagePath, matcherCtx);
     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,
     });
@@ -257,6 +277,26 @@ export interface CmsRouteOptions {
   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 = {
@@ -441,6 +481,9 @@ export function cmsRouteConfig(options: CmsRouteOptions) {
     defaultDescription,
     ignoreSearchParams = ["skuId"],
     pendingComponent,
+    pendingMs = 200,
+    pendingMinMs = 300,
+    ssr: ssrMode,
   } = options;
 
   const ignoreSet = new Set(ignoreSearchParams);
@@ -467,15 +510,80 @@ export function cmsRouteConfig(options: CmsRouteOptions) {
         ? "?" + new URLSearchParams(deps.search as Record<string, string>).toString()
         : "";
       const page = await loadCmsPage({ data: basePath + searchStr });
+      if (!page) return page;
 
-      if (!isServer && page?.resolvedSections) {
+      if (!isServer && page.resolvedSections) {
         const keys = page.resolvedSections.map((s: ResolvedSection) => s.component);
         await preloadSectionComponents(keys);
       }
+
+      // SSR: create unawaited promises for TanStack native streaming.
+      // Each deferred section becomes a promise that TanStack streams
+      // via SSR chunked transfer — all resolved in the SAME request.
+      //
+      // IMPORTANT: We call resolveDeferredSectionFull directly instead of
+      // loadDeferredSection (server function). Server functions serialize
+      // their return via JSON-RPC — TanStack only streams promises that
+      // are directly in the loader return, not serialized server fn results.
+      if (isServer && page.deferredSections?.length) {
+        const originRequest = getRequest();
+        const serverUrl = getRequestUrl();
+        const matcherCtx: MatcherContext = {
+          userAgent: getRequestHeader("user-agent") ?? "",
+          url: page.pageUrl ?? serverUrl.toString(),
+          path: page.pagePath ?? basePath,
+          cookies: getCookies(),
+          request: originRequest,
+        };
+        const deferredRequest = new Request(page.pageUrl ?? serverUrl.toString(), {
+          headers: originRequest.headers,
+        });
+
+        const deferredPromises: Record<string, Promise<ResolvedSection | null>> = {};
+        for (const ds of page.deferredSections) {
+          deferredPromises[`d_${ds.index}`] = resolveDeferredSectionFull(
+            ds,
+            page.pagePath ?? basePath,
+            deferredRequest,
+            matcherCtx,
+          ).catch((e) => {
+            console.error(`[CMS] Deferred section "${ds.component}" failed:`, e);
+            return null;
+          });
+        }
+        return { ...page, deferredPromises };
+      }
+
+      // Client SPA navigation: resolve all deferred sections via server
+      // function batch and merge into resolvedSections for immediate render.
+      if (!isServer && page.deferredSections?.length) {
+        const resolved = await Promise.all(
+          page.deferredSections.map((ds: DeferredSection) =>
+            loadDeferredSection({
+              data: {
+                component: ds.component,
+                rawProps: ds.rawProps,
+                pagePath: page.pagePath ?? basePath,
+                pageUrl: page.pageUrl,
+                index: ds.index,
+              },
+            }).catch(() => null),
+          ),
+        );
+        const all = [
+          ...page.resolvedSections,
+          ...resolved.filter((s): s is ResolvedSection => s != null),
+        ].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+        return { ...page, resolvedSections: all, deferredSections: [] };
+      }
+
       return page;
     },
 
     ...(pendingComponent ? { pendingComponent } : {}),
+    pendingMs,
+    pendingMinMs,
+    ...(ssrMode !== undefined ? { ssr: ssrMode } : {}),
 
     ...routeCacheDefaults("product"),
 
@@ -501,19 +609,77 @@ export function cmsHomeRouteConfig(options: {
   /** 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 } = options;
+  const { defaultTitle, defaultDescription, siteName, pendingMs = 200, pendingMinMs = 300 } = options;
 
   return {
     loader: async () => {
       const page = await loadCmsHomePage();
-      if (!isServer && page?.resolvedSections) {
+      if (!page) return page;
+
+      if (!isServer && page.resolvedSections) {
         const keys = page.resolvedSections.map((s: ResolvedSection) => s.component);
         await preloadSectionComponents(keys);
       }
+
+      // SSR: create unawaited promises for TanStack native streaming
+      if (isServer && page.deferredSections?.length) {
+        const originRequest = getRequest();
+        const serverUrl = getRequestUrl();
+        const matcherCtx: MatcherContext = {
+          userAgent: getRequestHeader("user-agent") ?? "",
+          url: page.pageUrl ?? serverUrl.toString(),
+          path: "/",
+          cookies: getCookies(),
+          request: originRequest,
+        };
+        const deferredRequest = new Request(page.pageUrl ?? serverUrl.toString(), {
+          headers: originRequest.headers,
+        });
+
+        const deferredPromises: Record<string, Promise<ResolvedSection | null>> = {};
+        for (const ds of page.deferredSections) {
+          deferredPromises[`d_${ds.index}`] = resolveDeferredSectionFull(
+            ds, "/", deferredRequest, matcherCtx,
+          ).catch((e) => {
+            console.error(`[CMS] Deferred section "${ds.component}" failed:`, e);
+            return null;
+          });
+        }
+        return { ...page, deferredPromises };
+      }
+
+      // Client SPA navigation: resolve all deferred via server function batch
+      if (!isServer && page.deferredSections?.length) {
+        const resolved = await Promise.all(
+          page.deferredSections.map((ds: DeferredSection) =>
+            loadDeferredSection({
+              data: {
+                component: ds.component,
+                rawProps: ds.rawProps,
+                pagePath: "/",
+                pageUrl: page.pageUrl,
+                index: ds.index,
+              },
+            }).catch(() => null),
+          ),
+        );
+        const all = [
+          ...page.resolvedSections,
+          ...resolved.filter((s): s is ResolvedSection => s != null),
+        ].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+        return { ...page, resolvedSections: all, deferredSections: [] };
+      }
+
       return page;
     },
     ...(options.pendingComponent ? { pendingComponent: options.pendingComponent } : {}),
+    pendingMs,
+    pendingMinMs,
     ...routeCacheDefaults("static"),
     headers: () => cacheHeaders("static"),
     head: ({ loaderData }: { loaderData?: CmsPageLoaderData }) =>

package/src/routes/components.tsx

@@ -1,15 +1,33 @@
 import { Link } from "@tanstack/react-router";
-import type { ResolvedSection } from "../cms/resolve";
+import type { DeferredSection, ResolvedSection } from "../cms/resolve";
 import { DecoPageRenderer } from "../hooks/DecoPageRenderer";
 
 /**
  * Default CMS page component. Renders all resolved sections.
  * Sites can use this directly or build their own.
  */
-export function CmsPage({ sections }: { sections: ResolvedSection[] }) {
+export function CmsPage({
+  sections,
+  deferredSections,
+  deferredPromises,
+  pagePath,
+  pageUrl,
+}: {
+  sections: ResolvedSection[];
+  deferredSections?: DeferredSection[];
+  deferredPromises?: Record<string, Promise<ResolvedSection | null>>;
+  pagePath?: string;
+  pageUrl?: string;
+}) {
   return (
     <div>
-      <DecoPageRenderer sections={sections} />
+      <DecoPageRenderer
+        sections={sections}
+        deferredSections={deferredSections}
+        deferredPromises={deferredPromises}
+        pagePath={pagePath}
+        pageUrl={pageUrl}
+      />
     </div>
   );
 }

package/src/sdk/index.ts

@@ -67,8 +67,9 @@ export {
   TABLET_RE,
   useDevice,
 } from "./useDevice";
+export { useHydrated } from "./useHydrated";
 export { useId } from "./useId";
-export { usePartialSection, useScript, useScriptAsDataURI, useSection } from "./useScript";
+export { inlineScript, usePartialSection, useScript, useScriptAsDataURI, useSection } from "./useScript";
 export { createDecoWorkerEntry, type DecoWorkerEntryOptions } from "./workerEntry";
 export { forwardResponseCookies, getRequestCookieHeader } from "./cookiePassthrough";
 export {

package/src/sdk/useDevice.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import { detectDevice, isMobileUA, useDevice } from "./useDevice";
+
+describe("detectDevice", () => {
+  it("detects iPhone as mobile", () => {
+    expect(
+      detectDevice(
+        "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1",
+      ),
+    ).toBe("mobile");
+  });
+
+  it("detects Android phone as mobile", () => {
+    expect(
+      detectDevice(
+        "Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36",
+      ),
+    ).toBe("mobile");
+  });
+
+  it("detects iPad as tablet", () => {
+    expect(
+      detectDevice(
+        "Mozilla/5.0 (iPad; CPU OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1",
+      ),
+    ).toBe("tablet");
+  });
+
+  it("detects Android tablet as tablet", () => {
+    expect(
+      detectDevice(
+        "Mozilla/5.0 (Linux; Android 14; SM-X200) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+      ),
+    ).toBe("tablet");
+  });
+
+  it("detects Chrome desktop as desktop", () => {
+    expect(
+      detectDevice(
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+      ),
+    ).toBe("desktop");
+  });
+
+  it("returns desktop for empty UA", () => {
+    expect(detectDevice("")).toBe("desktop");
+  });
+
+  it("detects Googlebot as desktop", () => {
+    expect(
+      detectDevice(
+        "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
+      ),
+    ).toBe("desktop");
+  });
+
+  it("detects Googlebot mobile as mobile", () => {
+    expect(
+      detectDevice(
+        "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36 (compatible; Googlebot/2.1)",
+      ),
+    ).toBe("mobile");
+  });
+});
+
+describe("isMobileUA", () => {
+  it("returns true for mobile UAs", () => {
+    expect(isMobileUA("iPhone")).toBe(true);
+  });
+
+  it("returns true for tablet UAs", () => {
+    expect(isMobileUA("iPad")).toBe(true);
+  });
+
+  it("returns false for desktop UAs", () => {
+    expect(
+      isMobileUA(
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("useDevice (isomorphic)", () => {
+  it("uses navigator.userAgent on client, not viewport width", () => {
+    // In jsdom, document exists → useDevice takes the client path.
+    // It should use navigator.userAgent (same mechanism as server-side)
+    // to ensure consistent values between SSR and hydration.
+    // jsdom's navigator.userAgent is a desktop-like string.
+    const device = useDevice();
+    const expected = detectDevice(navigator.userAgent);
+    expect(device).toBe(expected);
+  });
+
+  it("returns consistent result with detectDevice(navigator.userAgent)", () => {
+    // This is the key SSR/hydration consistency check:
+    // server calls detectDevice(req.headers["user-agent"])
+    // client calls detectDevice(navigator.userAgent)
+    // Both use the same detectDevice() function → same result for same UA.
+    const clientResult = useDevice();
+    const directResult = detectDevice(navigator.userAgent);
+    expect(clientResult).toBe(directResult);
+  });
+});

package/src/sdk/useDevice.ts

@@ -51,15 +51,36 @@ export function detectDevice(userAgent: string): Device {
 }
 
 /**
- * Get the current device type via RequestContext.
+ * Get the current device type. Works everywhere:
+ * - Server (loader, middleware, server function): reads User-Agent from RequestContext.
+ * - Client (component, event handler): uses `window.innerWidth` breakpoints.
  *
- * Must be called within a `RequestContext.run()` scope (i.e., during
- * request handling). Falls back to "desktop" outside request scope.
+ * @example
+ * ```tsx
+ * import { useDevice } from "@decocms/start/sdk/useDevice";
+ *
+ * // In a component:
+ * const device = useDevice(); // "mobile" | "tablet" | "desktop"
+ *
+ * // In a loader:
+ * export function loader(props: Props) {
+ *   const device = useDevice();
+ *   return { ...props, isMobile: device === "mobile" };
+ * }
+ * ```
  */
 export function useDevice(): Device {
-  const ctx = RequestContext.current;
-  if (!ctx) return "desktop";
-  const ua = ctx.request.headers.get("user-agent") ?? "";
+  // Server: use RequestContext UA header
+  if (typeof document === "undefined") {
+    const ctx = RequestContext.current;
+    if (!ctx) return "desktop";
+    const ua = ctx.request.headers.get("user-agent") ?? "";
+    return detectDevice(ua);
+  }
+  // Client: use navigator.userAgent for consistency with server-side UA detection.
+  // Using viewport width would produce different results between SSR and
+  // hydration (server sees UA, client sees pixels), causing hydration mismatch.
+  const ua = typeof navigator !== "undefined" ? navigator.userAgent : "";
   return detectDevice(ua);
 }
 
@@ -89,3 +110,4 @@ export function checkDesktop(): boolean {
   if (!ctx) return true;
   return detectDevice(ctx.request.headers.get("user-agent") ?? "") === "desktop";
 }
+

package/src/sdk/useHydrated.ts

@@ -0,0 +1,19 @@
+/**
+ * Re-export of TanStack Router's `useHydrated` hook.
+ *
+ * Returns `false` during SSR and on the first client render (before hydration),
+ * then `true` for all subsequent renders. Use this instead of
+ * `typeof document === "undefined"` checks for conditional rendering.
+ *
+ * @example
+ * ```tsx
+ * import { useHydrated } from "@decocms/start/sdk/useHydrated";
+ *
+ * function CartButton() {
+ *   const hydrated = useHydrated();
+ *   if (!hydrated) return <CartSkeleton />;
+ *   return <InteractiveCart />;
+ * }
+ * ```
+ */
+export { useHydrated } from "@tanstack/react-router";

package/src/sdk/useScript.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { inlineScript, useScript } from "./useScript";
+
+describe("inlineScript", () => {
+  it("returns dangerouslySetInnerHTML with the provided string", () => {
+    const result = inlineScript('alert("hello")');
+    expect(result).toEqual({
+      dangerouslySetInnerHTML: { __html: 'alert("hello")' },
+    });
+  });
+
+  it("handles empty string", () => {
+    const result = inlineScript("");
+    expect(result).toEqual({
+      dangerouslySetInnerHTML: { __html: "" },
+    });
+  });
+
+  it("handles multiline scripts", () => {
+    const js = `
+      const el = document.getElementById("btn");
+      el.addEventListener("click", () => { console.log("clicked"); });
+    `;
+    const result = inlineScript(js);
+    expect(result.dangerouslySetInnerHTML.__html).toBe(js);
+  });
+});
+
+describe("useScript", () => {
+  it("serializes a function into an IIFE string", () => {
+    function greet(name: string) {
+      console.log(name);
+    }
+    const result = useScript(greet, "world");
+    expect(result).toContain("(");
+    expect(result).toContain('"world"');
+    expect(result).toContain("console.log");
+  });
+
+  it("serializes multiple arguments", () => {
+    function add(a: number, b: number) {
+      return a + b;
+    }
+    const result = useScript(add, 1, 2);
+    expect(result).toContain("1,2");
+  });
+
+  it("handles functions with no arguments", () => {
+    function noop() {}
+    const result = useScript(noop);
+    expect(result).toMatch(/^\(.*\)\(\)$/);
+  });
+});

package/src/sdk/useScript.ts

@@ -57,15 +57,42 @@ function minifyJs(code: string): string {
 /**
  * Serializes a function and its arguments into a self-executing inline script.
  *
+ * @deprecated `fn.toString()` produces different output in SSR vs client Vite
+ * builds (React Compiler transforms differ), causing hydration mismatches on
+ * `dangerouslySetInnerHTML.__html`. Use {@link inlineScript} with a plain
+ * string constant instead.
+ *
  * @example
  * ```tsx
- * <script dangerouslySetInnerHTML={{ __html: useScript(onLoad, elementId, config) }} />
+ * // BEFORE (causes hydration mismatch):
+ * <script dangerouslySetInnerHTML={{ __html: useScript(onLoad, elementId) }} />
+ *
+ * // AFTER (safe):
+ * <script {...inlineScript(`(${MY_SCRIPT_STRING})("${elementId}")`)} />
  * ```
  */
 export function useScript<T extends (...args: any[]) => void>(
   fn: T,
   ...args: Parameters<T>
 ): string {
+  if (typeof (globalThis as any).__DECO_USE_SCRIPT_WARNED === "undefined") {
+    (globalThis as any).__DECO_USE_SCRIPT_WARNED = new Set<string>();
+  }
+  const warnedSet = (globalThis as any).__DECO_USE_SCRIPT_WARNED as Set<string>;
+  const fnName = fn.name || "anonymous";
+  if (
+    typeof process !== "undefined" &&
+    process.env?.NODE_ENV !== "production" &&
+    !warnedSet.has(fnName)
+  ) {
+    warnedSet.add(fnName);
+    console.warn(
+      `[useScript] Using fn.toString() for "${fnName}". ` +
+        `This may produce different output in SSR vs client builds, causing hydration mismatch. ` +
+        `Consider using inlineScript() with a plain string constant instead.`,
+    );
+  }
+
   const fnStr = fn.toString();
   let minified = cacheGet(fnStr);
   if (minified === undefined) {
@@ -79,6 +106,8 @@ export function useScript<T extends (...args: any[]) => void>(
 
 /**
  * Like useScript, but returns a data: URI suitable for `<script src="...">`.
+ *
+ * @deprecated Same hydration issues as {@link useScript}. Use {@link inlineScript} instead.
  */
 export function useScriptAsDataURI<T extends (...args: any[]) => void>(
   fn: T,
@@ -88,6 +117,25 @@ export function useScriptAsDataURI<T extends (...args: any[]) => void>(
   return `data:text/javascript;charset=utf-8,${encodeURIComponent(code)}`;
 }
 
+/**
+ * Returns props for a `<script>` element with safe inline JavaScript.
+ * Unlike {@link useScript}, this accepts a plain string — no `fn.toString()`
+ * means no SSR/client divergence and no hydration mismatch.
+ *
+ * @example
+ * ```tsx
+ * const SCROLL_SCRIPT = `document.getElementById("btn").addEventListener("click", () => { ... })`;
+ * <script {...inlineScript(SCROLL_SCRIPT)} />
+ *
+ * // With arguments:
+ * const INIT_SCRIPT = (id: string) => `document.getElementById("${id}").dataset.ready = "true"`;
+ * <script {...inlineScript(INIT_SCRIPT("my-element"))} />
+ * ```
+ */
+export function inlineScript(js: string) {
+  return { dangerouslySetInnerHTML: { __html: js } } as const;
+}
+
 /**
  * Stub -- Deco partial sections don't apply in TanStack Start.
  * Returns the provided props as-is.

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "jsdom",
+    include: ["src/**/*.test.{ts,tsx}"],
+    globals: true,
+  },
+});