@decocms/blocks-admin 7.16.5 → 7.16.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-admin",
-  "version": "7.16.5",
+  "version": "7.16.7",
   "type": "module",
   "description": "Deco admin protocol: /live/_meta, /.decofile, /deco/invoke, /deco/render, plus admin-facing site setup and commerce-app auto-configuration",
   "repository": {
@@ -25,7 +25,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.16.5"
+    "@decocms/blocks": "7.16.7"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/admin/index.ts

@@ -1,3 +1,18 @@
+export {
+  type ActionConfig,
+  composeMeta,
+  getRegisteredLoaders,
+  getRegisteredMatchers,
+  type LoaderConfig,
+  type MatcherConfig,
+  type MetaResponse,
+  registerActionSchema,
+  registerActionSchemas,
+  registerLoaderSchema,
+  registerLoaderSchemas,
+  registerMatcherSchema,
+  registerMatcherSchemas,
+} from "@decocms/blocks/cms";
 export { corsHeaders, isAdminOrLocalhost, registerAdminOrigin, registerAdminOrigins } from "./cors";
 export { handleDecofileRead, handleDecofileReload, setFastDeployKVGetter } from "./decofile";
 export {
@@ -13,17 +28,6 @@ export { LIVE_CONTROLS_SCRIPT } from "./liveControls";
 export { handleMeta, setMetaData } from "./meta";
 export { handleRender, setPreviewWrapper, setRenderShell } from "./render";
 export {
-  composeMeta,
-  getRegisteredLoaders,
-  getRegisteredMatchers,
-  type ActionConfig,
-  type LoaderConfig,
-  type MatcherConfig,
-  type MetaResponse,
-  registerActionSchema,
-  registerActionSchemas,
-  registerLoaderSchema,
-  registerLoaderSchemas,
-  registerMatcherSchema,
-  registerMatcherSchemas,
-} from "@decocms/blocks/cms";
+  type PreviewResolution,
+  resolvePreviewRequest,
+} from "./resolvePreview";

package/src/admin/render.ts

@@ -1,20 +1,11 @@
+import { getSection, type ResolvedSection } from "@decocms/blocks/cms";
 import { createElement } from "react";
-import {
-  loadBlocks,
-  withBlocksOverride,
-  getSection,
-  type MatcherContext,
-  type ResolvedSection,
-  resolvePageSections,
-  resolveValue,
-  WELL_KNOWN_TYPES,
-  runSingleSectionLoader,
-} from "@decocms/blocks/cms";
 import { buildHtmlShell } from "../sdk/htmlShell";
 import { LIVE_CONTROLS_SCRIPT } from "./liveControls";
+import { resolvePreviewRequest } from "./resolvePreview";
 import { getPreviewWrapper } from "./setup";
 
-export { setRenderShell, setPreviewWrapper } from "./setup";
+export { setPreviewWrapper, setRenderShell } from "./setup";
 
 /** Escape user-controlled strings before interpolating into HTML. */
 function escapeHtml(str: string): string {
@@ -50,74 +41,12 @@ async function renderResolvedSection(section: ResolvedSection): Promise<string>
     return `<div style="padding:8px;color:orange;font-size:12px;border:1px dashed orange;margin:4px 0;">Unsupported: ${escapeHtml(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 ${escapeHtml(section.component)}: ${escapeHtml((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;
-  if (!resolveType) return "";
-
-  const sectionLoader = getSection(resolveType);
-  if (!sectionLoader) {
-    return `<div style="padding:8px;color:orange;font-size:12px;border:1px dashed orange;margin:4px 0;">Unsupported: ${escapeHtml(resolveType)}</div>`;
-  }
-
-  try {
-    const { __resolveType: _, ...sectionProps } = section;
-    const renderToString = await getRenderToString();
-    const mod = await sectionLoader();
-    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 ${escapeHtml(resolveType)}: ${escapeHtml((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,
-  };
+  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);
 }
 
 /**
@@ -129,127 +58,11 @@ function buildPreviewMatcherCtx(request: Request): MatcherContext {
  * - Per-request decofile override via AsyncLocalStorage
  */
 export async function handleRender(request: Request): Promise<Response> {
-  const url = new URL(request.url);
-  const resolveChain = url.searchParams.get("resolveChain");
-  const propsParam = url.searchParams.get("props");
-
-  const pathPrefix = "/live/previews/";
-  const rawPathComponent = url.pathname.startsWith(pathPrefix)
-    ? url.pathname.slice(pathPrefix.length)
-    : "";
-  // Admin sends double-encoded path segments (e.g. space → %20 → %2520).
-  // Decode until stable so the block key matches the decofile.
-  const pathComponent = (() => {
-    try {
-      const once = decodeURIComponent(rawPathComponent);
-      try { return decodeURIComponent(once); } catch { return once; }
-    } catch { return rawPathComponent; }
-  })();
-  let component = resolveChain || pathComponent || "";
-  let props: Record<string, unknown> = {};
-  let decofileOverride: Record<string, unknown> | null = null;
-
-  if (request.method === "POST") {
-    try {
-      const body = await request.json();
-      if (body && typeof body === "object") {
-        if (body.__decofile && typeof body.__decofile === "object") {
-          decofileOverride = body.__decofile;
-        }
-        if (body.__props && typeof body.__props === "object") {
-          props = body.__props;
-          if (body.__props.__resolveType) {
-            component = body.__props.__resolveType as string;
-          }
-        } else if (body.props && typeof body.props === "object") {
-          props = body.props;
-        } else if (body.__resolveType) {
-          component = body.__resolveType as string;
-          const { __decofile: _, __resolveType: __, ...rest } = body;
-          props = rest;
-        } else if (!body.__decofile) {
-          props = body;
-        }
-      }
-    } catch {
-      // fall through to query-param handling
-    }
-  }
-
-  if (!decofileOverride) {
-    const decofileParam = url.searchParams.get("__decofile");
-    if (decofileParam) {
-      try {
-        decofileOverride = JSON.parse(decodeURIComponent(decofileParam));
-      } catch {
-        // invalid __decofile param, ignore
-      }
-    }
-  }
-
-  if (propsParam && Object.keys(props).length === 0) {
-    try {
-      props = JSON.parse(decodeURIComponent(propsParam));
-    } catch {
-      // Try base64-encoded props (admin uses btoa(encodeURIComponent(json)))
-      try {
-        props = JSON.parse(decodeURIComponent(atob(propsParam)));
-      } catch {
-        // props parsing failed
-      }
-    }
-  }
-
-  if (props.__resolveType && !component) {
-    component = props.__resolveType as string;
-  }
-
-  const renderFn = async () => {
-    const blocks = loadBlocks();
-
-    // Resolve named block at the component level
-    if (blocks[component]) {
-      const block = blocks[component] as Record<string, unknown>;
-      if (block.__resolveType) {
-        component = block.__resolveType as string;
-        props = { ...block, ...props };
-      }
-    }
-
-    // Page compositor: resolve + render all child sections in parallel
-    if (component === WELL_KNOWN_TYPES.PAGE) {
-      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.filter(Boolean).join("\n")), {
-        status: 200,
-        headers: { "Content-Type": "text/html; charset=utf-8" },
-      });
-    }
-
-    // Single section render
-    const sectionLoader = getSection(component);
-    if (!sectionLoader) {
+  try {
+    const resolution = await resolvePreviewRequest(request);
+    if (resolution.type === "unknown") {
       const unknownHtml = wrapInHtmlShell(
-        `<div style="padding:20px;color:red;">Unknown section: ${escapeHtml(component)}</div>`,
+        `<div style="padding:20px;color:red;">Unknown section: ${escapeHtml(resolution.component)}</div>`,
       );
       return new Response(unknownHtml, {
         status: 200,
@@ -257,32 +70,34 @@ 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 getRenderToString();
-      const mod = await sectionLoader();
-      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" },
-      });
-    } catch (error) {
-      const errorHtml = wrapInHtmlShell(
-        `<div style="padding:20px;color:red;">Render error: ${escapeHtml((error as Error).message)}</div>`,
+    if (resolution.previewType === "page") {
+      const htmlParts = await Promise.all(
+        resolution.sections.map(async (section) => {
+          try {
+            return await renderResolvedSection(section);
+          } catch (error) {
+            return `<div style="padding:8px;color:red;font-size:12px;">Error rendering ${escapeHtml(section.component)}: ${escapeHtml((error as Error).message)}</div>`;
+          }
+        }),
       );
-      return new Response(errorHtml, {
+      return new Response(wrapInHtmlShell(htmlParts.filter(Boolean).join("\n")), {
         status: 200,
-        headers: { "Content-Type": "text/html" },
+        headers: { "Content-Type": "text/html; charset=utf-8" },
       });
     }
-  };
 
-  if (decofileOverride) {
-    return withBlocksOverride(decofileOverride, renderFn);
+    const sectionHtml = await renderResolvedSection(resolution.sections[0]);
+    return new Response(wrapInHtmlShell(sectionHtml), {
+      status: 200,
+      headers: { "Content-Type": "text/html; charset=utf-8" },
+    });
+  } catch (error) {
+    const errorHtml = wrapInHtmlShell(
+      `<div style="padding:20px;color:red;">Render error: ${escapeHtml((error as Error).message)}</div>`,
+    );
+    return new Response(errorHtml, {
+      status: 200,
+      headers: { "Content-Type": "text/html" },
+    });
   }
-  return renderFn();
 }

package/src/admin/resolvePreview.test.ts

@@ -0,0 +1,129 @@
+// @vitest-environment node
+
+import { registerSection, setBlocks, WELL_KNOWN_TYPES } from "@decocms/blocks/cms";
+import { createElement } from "react";
+import { beforeEach, describe, expect, it } from "vitest";
+import * as admin from "./index";
+import { handleRender } from "./render";
+import { resolvePreviewRequest } from "./resolvePreview";
+
+const HERO = "site/sections/Hero.tsx";
+
+beforeEach(() => {
+  setBlocks({});
+  registerSection(HERO, async () => ({
+    default: ({ label }: { label?: string }) => createElement("h1", null, `hero-${label}`),
+  }));
+});
+
+describe("resolvePreviewRequest", () => {
+  it("is exposed by the blocks-admin protocol package", () => {
+    expect((admin as Record<string, unknown>).resolvePreviewRequest).toBeTypeOf("function");
+  });
+
+  it("resolves a direct section and query-string props", async () => {
+    const props = encodeURIComponent(JSON.stringify({ label: "query" }));
+    const result = await resolvePreviewRequest(
+      new Request(`http://localhost/live/previews/${encodeURIComponent(HERO)}?props=${props}`),
+    );
+
+    expect(result).toEqual({
+      type: "sections",
+      previewType: "section",
+      component: HERO,
+      sections: [{ component: HERO, key: HERO, props: { label: "query" } }],
+    });
+  });
+
+  it("resolves a direct section and props from a POST body", async () => {
+    const result = await resolvePreviewRequest(
+      new Request("http://localhost/live/previews/ignored", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ __resolveType: HERO, label: "post" }),
+      }),
+    );
+
+    expect(result).toMatchObject({
+      type: "sections",
+      previewType: "section",
+      component: HERO,
+      sections: [{ component: HERO, props: { label: "post" } }],
+    });
+  });
+
+  it("resolves a double-encoded named block", async () => {
+    setBlocks({
+      "Hero Block": { __resolveType: HERO, label: "named" },
+    });
+
+    const result = await resolvePreviewRequest(
+      new Request("http://localhost/live/previews/Hero%2520Block"),
+    );
+
+    expect(result).toMatchObject({
+      type: "sections",
+      component: HERO,
+      sections: [{ component: HERO, props: { label: "named" } }],
+    });
+  });
+
+  it("resolves and enriches every section in a page preview", async () => {
+    const props = encodeURIComponent(
+      JSON.stringify({
+        sections: [{ __resolveType: HERO, label: "page" }],
+      }),
+    );
+    const result = await resolvePreviewRequest(
+      new Request(
+        `http://localhost/live/previews/page?resolveChain=${encodeURIComponent(WELL_KNOWN_TYPES.PAGE)}&props=${props}`,
+      ),
+    );
+
+    expect(result).toMatchObject({
+      type: "sections",
+      component: WELL_KNOWN_TYPES.PAGE,
+      sections: [{ component: HERO, props: { label: "page" } }],
+    });
+  });
+
+  it("applies POST decofile overrides only for the current preview", async () => {
+    setBlocks({
+      "Hero Block": { __resolveType: HERO, label: "base" },
+    });
+    const request = new Request("http://localhost/live/previews/Hero%2520Block", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        __decofile: {
+          "Hero Block": { __resolveType: HERO, label: "override" },
+        },
+      }),
+    });
+
+    const result = await resolvePreviewRequest(request);
+
+    expect(result).toMatchObject({
+      type: "sections",
+      component: HERO,
+      sections: [{ component: HERO, props: { label: "override" } }],
+    });
+    expect(
+      await resolvePreviewRequest(new Request("http://localhost/live/previews/Hero%2520Block")),
+    ).toMatchObject({ sections: [{ props: { label: "base" } }] });
+  });
+
+  it("keeps handleRender's complete HTML response contract", async () => {
+    const props = encodeURIComponent(JSON.stringify({ label: "html" }));
+    const response = await handleRender(
+      new Request(`http://localhost/live/previews/${encodeURIComponent(HERO)}?props=${props}`),
+    );
+    const html = await response.text();
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("content-type")).toContain("text/html");
+    expect(html).toContain("<!DOCTYPE html>");
+    expect(html).toContain("hero-html");
+    expect(html).toContain("editor::inject");
+  });
+});

package/src/admin/resolvePreview.ts

@@ -0,0 +1,176 @@
+import {
+  getSection,
+  loadBlocks,
+  type MatcherContext,
+  type ResolvedSection,
+  resolvePageSections,
+  resolveValue,
+  runSingleSectionLoader,
+  WELL_KNOWN_TYPES,
+  withBlocksOverride,
+} from "@decocms/blocks/cms";
+
+export type PreviewResolution =
+  | {
+      type: "sections";
+      previewType: "page" | "section";
+      component: string;
+      sections: ResolvedSection[];
+    }
+  | { type: "unknown"; component: string };
+
+type PreviewInput = {
+  component: string;
+  props: Record<string, unknown>;
+  decofileOverride: Record<string, unknown> | null;
+};
+
+function decodePreviewPath(value: string): string {
+  try {
+    const once = decodeURIComponent(value);
+    try {
+      return decodeURIComponent(once);
+    } catch {
+      return once;
+    }
+  } catch {
+    return value;
+  }
+}
+
+function parseJsonRecord(value: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+async function parsePreviewInput(request: Request): Promise<PreviewInput> {
+  const url = new URL(request.url);
+  const resolveChain = url.searchParams.get("resolveChain");
+  const propsParam = url.searchParams.get("props");
+  const pathPrefix = "/live/previews/";
+  const rawPathComponent = url.pathname.startsWith(pathPrefix)
+    ? url.pathname.slice(pathPrefix.length)
+    : "";
+
+  let component = resolveChain || decodePreviewPath(rawPathComponent) || "";
+  let props: Record<string, unknown> = {};
+  let decofileOverride: Record<string, unknown> | null = null;
+
+  if (request.method === "POST") {
+    try {
+      const body = (await request.json()) as Record<string, unknown> | null;
+      if (body && typeof body === "object") {
+        if (body.__decofile && typeof body.__decofile === "object") {
+          decofileOverride = body.__decofile as Record<string, unknown>;
+        }
+        if (body.__props && typeof body.__props === "object") {
+          props = body.__props as Record<string, unknown>;
+          if (typeof props.__resolveType === "string") {
+            component = props.__resolveType;
+          }
+        } else if (body.props && typeof body.props === "object") {
+          props = body.props as Record<string, unknown>;
+        } else if (typeof body.__resolveType === "string") {
+          component = body.__resolveType;
+          const { __decofile: _, __resolveType: __, ...rest } = body;
+          props = rest;
+        } else if (!body.__decofile) {
+          props = body;
+        }
+      }
+    } catch {
+      // Fall through to query-param parsing.
+    }
+  }
+
+  if (!decofileOverride) {
+    const decofileParam = url.searchParams.get("__decofile");
+    if (decofileParam) {
+      decofileOverride = parseJsonRecord(decodeURIComponent(decofileParam));
+    }
+  }
+
+  if (propsParam && Object.keys(props).length === 0) {
+    props = parseJsonRecord(decodeURIComponent(propsParam)) ?? {};
+    if (Object.keys(props).length === 0) {
+      try {
+        props = parseJsonRecord(decodeURIComponent(atob(propsParam))) ?? {};
+      } catch {
+        // Invalid props remain an empty object.
+      }
+    }
+  }
+
+  if (typeof props.__resolveType === "string" && !component) {
+    component = props.__resolveType;
+  }
+
+  return { component, props, decofileOverride };
+}
+
+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 cookies: Record<string, string> = {};
+  for (const part of (request.headers.get("cookie") ?? "").split(";")) {
+    const [key, ...value] = part.trim().split("=");
+    if (key) cookies[key] = value.join("=").trim();
+  }
+
+  return {
+    userAgent,
+    url: url.toString(),
+    path,
+    cookies,
+    request,
+  };
+}
+
+export async function resolvePreviewRequest(request: Request): Promise<PreviewResolution> {
+  const input = await parsePreviewInput(request);
+
+  const resolve = async (): Promise<PreviewResolution> => {
+    let { component, props } = input;
+    const block = loadBlocks()[component] as Record<string, unknown> | undefined;
+    if (block && typeof block.__resolveType === "string") {
+      component = block.__resolveType;
+      props = { ...block, ...props };
+    }
+
+    if (component === WELL_KNOWN_TYPES.PAGE) {
+      const resolved = await resolvePageSections(props.sections, buildPreviewMatcherCtx(request));
+      const sections = await Promise.all(
+        resolved.map((section) => runSingleSectionLoader(section, request).catch(() => section)),
+      );
+      return { type: "sections", previewType: "page", component, sections };
+    }
+
+    if (!getSection(component)) {
+      return { type: "unknown", component };
+    }
+
+    const resolvedProps = (await resolveValue(props)) as Record<string, unknown>;
+    const { __resolveType: _, ...cleanProps } = resolvedProps;
+    return {
+      type: "sections",
+      previewType: "section",
+      component,
+      sections: [{ component, key: component, props: cleanProps }],
+    };
+  };
+
+  return input.decofileOverride ? withBlocksOverride(input.decofileOverride, resolve) : resolve();
+}