@decocms/start 0.29.0 → 0.29.2

package/package.json

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

package/src/cms/sectionLoaders.ts

@@ -239,6 +239,22 @@ export async function runSectionLoaders(
   sections: ResolvedSection[],
   request: Request,
 ): Promise<ResolvedSection[]> {
+  // Dev warning: detect likely layout sections not registered via registerLayoutSections.
+  // Without registration, Header/Footer won't be cached across navigations.
+  if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+    for (const s of sections) {
+      const key = s.component.toLowerCase();
+      if (
+        (key.includes("header") || key.includes("footer")) &&
+        !layoutSections.has(s.component)
+      ) {
+        console.warn(
+          `[SectionLoaders] "${s.component}" looks like a layout section but is not in registerLayoutSections(). ` +
+            `Add it to registerLayoutSections() in setup.ts for consistent caching across navigations.`,
+        );
+      }
+    }
+  }
   return Promise.all(sections.map((section) => runSingleSectionLoader(section, request)));
 }
 

package/src/hooks/DecoPageRenderer.tsx

@@ -172,21 +172,34 @@ export function SectionRenderer({ section }: { section: Section | null | undefin
     return <Comp {...(section.props ?? {})} />;
   }
 
+  // Sync path: render directly if available — avoids React.lazy SSR streaming issue
+  const options = getSectionOptions(section.Component);
+  const isClientOnly = options?.clientOnly === true;
+  const SyncComp = getSyncComponent(section.Component);
+  if (SyncComp && !isClientOnly) {
+    return createElement(SyncComp, section.props ?? {});
+  }
+
   const Lazy = getLazyComponent(section.Component);
   if (!Lazy) {
     console.warn(`[SectionRenderer] No component registered for: ${section.Component}`);
     return null;
   }
 
-  // Use the section's registered loadingFallback (if available) instead of
-  // the generic NestedSectionFallback. This lets parent sections (e.g.
-  // NotFoundChallenge) show a meaningful skeleton for nested children
-  // (e.g. MountedPDP) while the lazy chunk loads.
-  const options = getSectionOptions(section.Component);
   const fallback = options?.loadingFallback
     ? createElement(options.loadingFallback, section.props ?? {})
     : <NestedSectionFallback />;
 
+  if (isClientOnly) {
+    return (
+      <ClientOnly fallback={fallback}>
+        <Suspense fallback={null}>
+          <Lazy {...(section.props ?? {})} />
+        </Suspense>
+      </ClientOnly>
+    );
+  }
+
   return (
     <Suspense fallback={fallback}>
       <Lazy {...(section.props ?? {})} />
@@ -501,20 +514,39 @@ export function DecoPageRenderer({
                   <Await promise={promise}>
                     {(resolved) => {
                       if (!resolved) return null;
-                      const LazyComponent = getLazyComponent(resolved.component);
-                      if (!LazyComponent) return null;
                       const resolvedOptions = getSectionOptions(resolved.component);
                       const isClientOnly = resolvedOptions?.clientOnly === true;
+                      const SyncComp = getSyncComponent(resolved.component);
                       const sectionId = resolved.key
                         .replace(/\//g, "-")
                         .replace(/\.tsx$/, "")
                         .replace(/^site-sections-/, "");
 
-                      const inner = (
-                        <Suspense fallback={null}>
-                          <LazyComponent {...resolved.props} />
-                        </Suspense>
-                      );
+                      let inner: ReactNode;
+
+                      if (SyncComp && !isClientOnly) {
+                        // Sync path: direct render, no lazy/Suspense.
+                        inner = createElement(SyncComp, resolved.props);
+                      } else {
+                        const LazyComponent = getLazyComponent(resolved.component);
+                        if (!LazyComponent) return null;
+
+                        const fallbackEl = resolvedOptions?.loadingFallback
+                          ? createElement(resolvedOptions.loadingFallback, resolved.props)
+                          : null;
+
+                        inner = isClientOnly ? (
+                          <ClientOnly fallback={fallbackEl}>
+                            <Suspense fallback={null}>
+                              <LazyComponent {...resolved.props} />
+                            </Suspense>
+                          </ClientOnly>
+                        ) : (
+                          <Suspense fallback={null}>
+                            <LazyComponent {...resolved.props} />
+                          </Suspense>
+                        );
+                      }
 
                       return (
                         <section
@@ -522,11 +554,7 @@ export function DecoPageRenderer({
                           data-manifest-key={resolved.key}
                           style={{ animation: "decoFadeIn 0.3s ease-out" }}
                         >
-                          {isClientOnly ? (
-                            <ClientOnly fallback={null}>{inner}</ClientOnly>
-                          ) : (
-                            inner
-                          )}
+                          {inner}
                         </section>
                       );
                     }}
@@ -565,34 +593,36 @@ export function DecoPageRenderer({
           .replace(/\.tsx$/, "")
           .replace(/^site-sections-/, "");
 
-        // Unified render path: always use React.lazy + Suspense.
-        // For sync-registered components, getLazyComponent wraps them in a
-        // pre-fulfilled lazy (via syncThenable) so React renders them
-        // synchronously — same behavior as the old sync path, but with an
-        // identical tree structure on both server and client (always has
-        // <Suspense>). This prevents hydration mismatches when sites remove
-        // registerSectionsSync.
-        const LazyComponent = getLazyComponent(section.component);
-        if (!LazyComponent) return null;
-
-        // ClientOnly sections: render only on client, no SSR, no hydration mismatch.
-        // Used for analytics scripts, GTM, third-party widgets.
         const isClientOnly = options?.clientOnly === true;
-        const fallbackEl = options?.loadingFallback
-          ? createElement(options.loadingFallback, section.props)
-          : null;
-
-        const content = isClientOnly ? (
-          <ClientOnly fallback={fallbackEl}>
+        const SyncComponent = getSyncComponent(section.component);
+
+        let content: ReactNode;
+
+        if (SyncComponent && !isClientOnly) {
+          // Sync path: render directly — no Suspense, no lazy.
+          // React SSR streaming ignores syncThenable's pre-fulfilled status
+          // and creates empty <template> placeholders. Direct createElement avoids this.
+          content = createElement(SyncComponent, section.props);
+        } else {
+          const LazyComponent = getLazyComponent(section.component);
+          if (!LazyComponent) return null;
+
+          const fallbackEl = options?.loadingFallback
+            ? createElement(options.loadingFallback, section.props)
+            : null;
+
+          content = isClientOnly ? (
+            <ClientOnly fallback={fallbackEl}>
+              <Suspense fallback={null}>
+                <LazyComponent {...section.props} />
+              </Suspense>
+            </ClientOnly>
+          ) : (
             <Suspense fallback={null}>
               <LazyComponent {...section.props} />
             </Suspense>
-          </ClientOnly>
-        ) : (
-          <Suspense fallback={null}>
-            <LazyComponent {...section.props} />
-          </Suspense>
-        );
+          );
+        }
 
         // Dev warning: eager section not sync-registered may blank during hydration
         if (isDev && !isClientOnly && !getSyncComponent(section.component)) {

package/src/middleware/validateSection.test.ts

@@ -27,6 +27,25 @@ describe("validateDeferredSectionInput", () => {
     expect(result.pageUrl).toBe("https://store.com/home?ref=nav");
   });
 
+  it("accepts input with index for SPA navigation ordering", () => {
+    const result = validateDeferredSectionInput({
+      component: "site/sections/Shelf.tsx",
+      rawProps: {},
+      pagePath: "/",
+      index: 5,
+    });
+    expect(result.index).toBe(5);
+  });
+
+  it("index is undefined when not provided", () => {
+    const result = validateDeferredSectionInput({
+      component: "site/sections/Shelf.tsx",
+      rawProps: {},
+      pagePath: "/",
+    });
+    expect(result.index).toBeUndefined();
+  });
+
   it("throws on null input", () => {
     expect(() => validateDeferredSectionInput(null)).toThrow("Expected an object");
   });
@@ -85,6 +104,17 @@ describe("validateDeferredSectionInput", () => {
       }),
     ).toThrow("pageUrl");
   });
+
+  it("throws when index is not a number", () => {
+    expect(() =>
+      validateDeferredSectionInput({
+        component: "X",
+        rawProps: {},
+        pagePath: "/",
+        index: "three" as any,
+      }),
+    ).toThrow("index");
+  });
 });
 
 describe("createSectionValidator", () => {

package/src/middleware/validateSection.ts

@@ -21,6 +21,8 @@ export interface DeferredSectionInput {
   rawProps: Record<string, unknown>;
   pagePath: string;
   pageUrl?: string;
+  /** Original position in the page section list — for correct ordering after resolution. */
+  index?: number;
 }
 
 /**
@@ -57,11 +59,18 @@ export function validateDeferredSectionInput(data: unknown): DeferredSectionInpu
     );
   }
 
+  if (obj.index !== undefined && typeof obj.index !== "number") {
+    throw new Error(
+      "[validateDeferredSectionInput] Invalid 'index' field (expected number or undefined)",
+    );
+  }
+
   return {
     component: obj.component as string,
     rawProps: obj.rawProps as Record<string, unknown>,
     pagePath: obj.pagePath as string,
     pageUrl: obj.pageUrl as string | undefined,
+    index: obj.index as number | undefined,
   };
 }
 

package/src/routes/cmsRoute.ts

@@ -193,10 +193,17 @@ 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; 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();
@@ -211,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,
     });
@@ -510,17 +520,33 @@ export function cmsRouteConfig(options: CmsRouteOptions) {
       // 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}`] = loadDeferredSection({
-            data: {
-              component: ds.component,
-              rawProps: ds.rawProps,
-              pagePath: page.pagePath ?? basePath,
-              pageUrl: page.pageUrl,
-            },
-          }).catch((e) => {
+          deferredPromises[`d_${ds.index}`] = resolveDeferredSectionFull(
+            ds,
+            page.pagePath ?? basePath,
+            deferredRequest,
+            matcherCtx,
+          ).catch((e) => {
             console.error(`[CMS] Deferred section "${ds.component}" failed:`, e);
             return null;
           });
@@ -539,6 +565,7 @@ export function cmsRouteConfig(options: CmsRouteOptions) {
                 rawProps: ds.rawProps,
                 pagePath: page.pagePath ?? basePath,
                 pageUrl: page.pageUrl,
+                index: ds.index,
               },
             }).catch(() => null),
           ),
@@ -601,16 +628,24 @@ export function cmsHomeRouteConfig(options: {
 
       // 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}`] = loadDeferredSection({
-            data: {
-              component: ds.component,
-              rawProps: ds.rawProps,
-              pagePath: "/",
-              pageUrl: page.pageUrl,
-            },
-          }).catch((e) => {
+          deferredPromises[`d_${ds.index}`] = resolveDeferredSectionFull(
+            ds, "/", deferredRequest, matcherCtx,
+          ).catch((e) => {
             console.error(`[CMS] Deferred section "${ds.component}" failed:`, e);
             return null;
           });
@@ -628,6 +663,7 @@ export function cmsHomeRouteConfig(options: {
                 rawProps: ds.rawProps,
                 pagePath: "/",
                 pageUrl: page.pageUrl,
+                index: ds.index,
               },
             }).catch(() => null),
           ),