@decocms/start 0.25.5 → 0.26.1

package/package.json

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

package/src/admin/index.ts

@@ -9,7 +9,7 @@ export {
 } from "./invoke";
 export { LIVE_CONTROLS_SCRIPT } from "./liveControls";
 export { handleMeta, setMetaData } from "./meta";
-export { handleRender, setRenderShell } from "./render";
+export { handleRender, setPreviewWrapper, setRenderShell } from "./render";
 export {
   composeMeta,
   getRegisteredLoaders,

package/src/admin/render.ts

@@ -1,19 +1,60 @@
 import { createElement } from "react";
 import { loadBlocks, withBlocksOverride } from "../cms/loader";
 import { getSection } from "../cms/registry";
-import { resolveValue, WELL_KNOWN_TYPES } from "../cms/resolve";
+import {
+  type MatcherContext,
+  type ResolvedSection,
+  resolvePageSections,
+  resolveValue,
+  WELL_KNOWN_TYPES,
+} from "../cms/resolve";
+import { runSingleSectionLoader } from "../cms/sectionLoaders";
 import { buildHtmlShell } from "../sdk/htmlShell";
 import { LIVE_CONTROLS_SCRIPT } from "./liveControls";
+import { getPreviewWrapper } from "./setup";
 
-export { setRenderShell } from "./setup";
+export { setRenderShell, setPreviewWrapper } from "./setup";
+
+// Cache the dynamic import — avoids re-importing per section render
+let _renderToString: ((element: any) => string) | null = null;
+async function getRenderToString() {
+  if (!_renderToString) {
+    const mod = await import("react-dom/server");
+    _renderToString = mod.renderToString;
+  }
+  return _renderToString;
+}
 
 function wrapInHtmlShell(sectionHtml: string): string {
   return buildHtmlShell({ body: sectionHtml, script: LIVE_CONTROLS_SCRIPT });
 }
 
 /**
- * Render a single resolved section object to an HTML string.
- * Returns empty string for unknown or SEO-only sections.
+ * Render a single ResolvedSection to an HTML string.
+ * Uses the pre-cached renderToString and the preview wrapper.
+ */
+async function renderResolvedSection(section: ResolvedSection): Promise<string> {
+  const sectionLoader = getSection(section.component);
+  if (!sectionLoader) {
+    return `<div style="padding:8px;color:orange;font-size:12px;border:1px dashed orange;margin:4px 0;">Unsupported: ${section.component}</div>`;
+  }
+
+  try {
+    const renderToString = await getRenderToString();
+    const mod = await sectionLoader();
+    const element = createElement(mod.default, section.props);
+    const Wrapper = getPreviewWrapper();
+    const wrapped = Wrapper ? createElement(Wrapper, null, element) : element;
+    return renderToString(wrapped);
+  } catch (error) {
+    return `<div style="padding:8px;color:red;font-size:12px;">Error rendering ${section.component}: ${(error as Error).message}</div>`;
+  }
+}
+
+/**
+ * Render a single raw section object (with __resolveType) to HTML.
+ * Kept for the single-section preview path where we don't go through
+ * resolvePageSections.
  */
 async function renderOneSection(section: Record<string, unknown>): Promise<string> {
   const resolveType = section.__resolveType as string | undefined;
@@ -26,14 +67,48 @@ async function renderOneSection(section: Record<string, unknown>): Promise<strin
 
   try {
     const { __resolveType: _, ...sectionProps } = section;
-    const { renderToString } = await import("react-dom/server");
+    const renderToString = await getRenderToString();
     const mod = await sectionLoader();
-    return renderToString(createElement(mod.default, sectionProps));
+    const element = createElement(mod.default, sectionProps);
+    const Wrapper = getPreviewWrapper();
+    const wrapped = Wrapper ? createElement(Wrapper, null, element) : element;
+    return renderToString(wrapped);
   } catch (error) {
     return `<div style="padding:8px;color:red;font-size:12px;">Error rendering ${resolveType}: ${(error as Error).message}</div>`;
   }
 }
 
+/**
+ * Build a MatcherContext from the preview request.
+ * Enables matchers (device, date, cookie, etc.) to evaluate correctly
+ * during preview resolution.
+ */
+function buildPreviewMatcherCtx(request: Request): MatcherContext {
+  const url = new URL(request.url);
+  const deviceHint = url.searchParams.get("deviceHint");
+  const path = url.searchParams.get("path") || "/";
+
+  let userAgent = request.headers.get("user-agent") ?? "";
+  if (deviceHint === "mobile" && !/mobile/i.test(userAgent)) {
+    userAgent += " Mobile";
+  }
+
+  const cookieHeader = request.headers.get("cookie") ?? "";
+  const cookies: Record<string, string> = {};
+  for (const part of cookieHeader.split(";")) {
+    const [k, ...v] = part.trim().split("=");
+    if (k) cookies[k.trim()] = v.join("=").trim();
+  }
+
+  return {
+    userAgent,
+    url: url.toString(),
+    path,
+    cookies,
+    request,
+  };
+}
+
 /**
  * Handles /live/previews/* -- renders sections to HTML for the admin preview.
  *
@@ -117,28 +192,30 @@ export async function handleRender(request: Request): Promise<Response> {
       }
     }
 
-    // Page compositor: resolve + render all child sections
+    // Page compositor: resolve + render all child sections in parallel
     if (component === WELL_KNOWN_TYPES.PAGE) {
-      const rawSections = props.sections;
-      const resolvedSections = await resolveValue(rawSections);
-      const sectionsList = Array.isArray(resolvedSections)
-        ? resolvedSections
-        : resolvedSections
-          ? [resolvedSections]
-          : [];
-
-      const htmlParts: string[] = [];
-      for (const section of sectionsList) {
-        if (!section || typeof section !== "object" || Array.isArray(section)) {
-          continue;
-        }
-        const sectionObj = section as Record<string, unknown>;
-        if (!sectionObj.__resolveType) continue;
-        const html = await renderOneSection(sectionObj);
-        if (html) htmlParts.push(html);
-      }
+      const matcherCtx = buildPreviewMatcherCtx(request);
+
+      // resolvePageSections uses the same strategy as resolveDecoPage:
+      // parallel section resolution, layout caching, in-flight dedup, memoization
+      const resolvedSections = await resolvePageSections(
+        props.sections,
+        matcherCtx,
+      );
+
+      // Run section loaders in parallel — benefits from layout and cacheable caches
+      const enrichedSections = await Promise.all(
+        resolvedSections.map((section) =>
+          runSingleSectionLoader(section, request).catch(() => section),
+        ),
+      );
+
+      // Render all sections in parallel
+      const htmlParts = await Promise.all(
+        enrichedSections.map((section) => renderResolvedSection(section)),
+      );
 
-      return new Response(wrapInHtmlShell(htmlParts.join("\n")), {
+      return new Response(wrapInHtmlShell(htmlParts.filter(Boolean).join("\n")), {
         status: 200,
         headers: { "Content-Type": "text/html; charset=utf-8" },
       });
@@ -159,9 +236,12 @@ export async function handleRender(request: Request): Promise<Response> {
     try {
       const resolvedProps = (await resolveValue(props)) as Record<string, unknown>;
       const { __resolveType: _, ...cleanProps } = resolvedProps;
-      const { renderToString } = await import("react-dom/server");
+      const renderToString = await getRenderToString();
       const mod = await sectionLoader();
-      const sectionHtml = renderToString(createElement(mod.default, cleanProps));
+      const element = createElement(mod.default, cleanProps);
+      const Wrapper = getPreviewWrapper();
+      const wrapped = Wrapper ? createElement(Wrapper, null, element) : element;
+      const sectionHtml = renderToString(wrapped);
       return new Response(wrapInHtmlShell(sectionHtml), {
         status: 200,
         headers: { "Content-Type": "text/html; charset=utf-8" },

package/src/admin/setup.ts

@@ -25,6 +25,38 @@ let themeName = "";
 let bodyClass = "";
 let htmlLang = "en";
 
+/**
+ * Optional React component that wraps section renders in admin previews.
+ * Use this to provide context that sections depend on (Router, QueryClient, etc.)
+ * without which renderToString would crash.
+ *
+ * The wrapper receives `{ children }` and should render them inside the
+ * necessary providers.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let previewWrapperComponent: any = null;
+
+/**
+ * Register a wrapper component for admin preview renders.
+ *
+ * @example
+ * ```ts
+ * // In site's setup.ts:
+ * import { setPreviewWrapper } from "@decocms/start/admin/setup";
+ * import { PreviewProviders } from "./components/PreviewProviders";
+ * setPreviewWrapper(PreviewProviders);
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function setPreviewWrapper(wrapper: any) {
+  previewWrapperComponent = wrapper;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getPreviewWrapper(): any {
+  return previewWrapperComponent;
+}
+
 export function setRenderShell(opts: {
   css?: string;
   fonts?: string[];

package/src/cms/index.ts

@@ -49,6 +49,7 @@ export {
   registerMatcher,
   registerSeoSections,
   resolveDecoPage,
+  resolvePageSections,
   resolvePageSeoBlock,
   resolveDeferredSection,
   resolveValue,

package/src/cms/resolve.ts

@@ -1276,6 +1276,71 @@ export async function resolveDecoPage(
   };
 }
 
+/**
+ * Resolve a raw sections array into ResolvedSection[] with the same
+ * optimizations as resolveDecoPage: parallel resolution, layout caching,
+ * in-flight dedup, and memoization.
+ *
+ * Unlike resolveDecoPage, this does NOT look up a page by path — the
+ * caller provides the raw section array directly. Used by the admin
+ * preview renderer where page data comes from the POST body.
+ *
+ * All sections are resolved eagerly (no deferred/async split) since
+ * admin previews need the full rendered output.
+ */
+export async function resolvePageSections(
+  rawSectionsInput: unknown,
+  matcherCtx?: MatcherContext,
+): Promise<ResolvedSection[]> {
+  ensureInitialized();
+
+  const ctx: MatcherContext = matcherCtx ?? {};
+  const rctx: ResolveContext = { matcherCtx: ctx, memo: new Map(), depth: 0 };
+
+  let rawSections: unknown[];
+  if (Array.isArray(rawSectionsInput)) {
+    rawSections = rawSectionsInput;
+  } else {
+    rawSections = await resolveSectionsList(rawSectionsInput, rctx);
+  }
+
+  const eagerResults: Promise<ResolvedSection[]>[] = [];
+
+  for (const section of rawSections) {
+    const promise = (async (): Promise<ResolvedSection[]> => {
+      try {
+        const layoutKey = isRawSectionLayout(section);
+
+        if (layoutKey) {
+          const cached = getCachedResolvedLayout(layoutKey);
+          if (cached) return cached;
+
+          const inflight = resolvedLayoutInflight.get(layoutKey);
+          if (inflight) return inflight;
+
+          const p = resolveRawSection(section, rctx).then((results) => {
+            setCachedResolvedLayout(layoutKey, results);
+            return results;
+          });
+          resolvedLayoutInflight.set(layoutKey, p);
+          p.finally(() => resolvedLayoutInflight.delete(layoutKey));
+          return p;
+        }
+
+        return resolveRawSection(section, rctx);
+      } catch (e) {
+        onResolveError(e, "section", "Preview section resolution");
+        return [];
+      }
+    })();
+
+    eagerResults.push(promise);
+  }
+
+  const allResults = await Promise.all(eagerResults);
+  return allResults.flat();
+}
+
 /**
  * Resolve a single deferred section's raw props into a fully resolved section.
  * Called by the loadDeferredSection server function when a section scrolls into view.