@decocms/start 0.19.0

package/src/admin/decofile.ts

@@ -0,0 +1,72 @@
+import { getRevision, loadBlocks, setBlocks } from "../cms/loader";
+import { clearLoaderCache } from "../sdk/cachedLoader";
+import { invalidateMetaCache } from "./meta";
+
+export function handleDecofileRead(): Response {
+  const blocks = loadBlocks();
+  const revision = getRevision();
+
+  return new Response(JSON.stringify({ blocks, revision }), {
+    status: 200,
+    headers: {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-cache",
+      ...(revision ? { ETag: `"${revision}"` } : {}),
+    },
+  });
+}
+
+export async function handleDecofileReload(
+  request: Request,
+  env?: Record<string, unknown>,
+): Promise<Response> {
+  const authHeader = request.headers.get("authorization") || "";
+  const expectedToken =
+    (env?.DECO_RELOAD_TOKEN as string | undefined) ??
+    (typeof globalThis.process !== "undefined"
+      ? globalThis.process.env?.DECO_RELOAD_TOKEN
+      : undefined);
+
+  if (expectedToken && !authHeader.includes(expectedToken)) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  let newBlocks: Record<string, unknown>;
+  try {
+    newBlocks = await request.json();
+  } catch {
+    return new Response(JSON.stringify({ error: "Invalid JSON body" }), {
+      status: 400,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  if (!newBlocks || typeof newBlocks !== "object") {
+    return new Response(JSON.stringify({ error: "Body must be a JSON object" }), {
+      status: 400,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  const previousBlockCount = Object.keys(loadBlocks()).length;
+
+  setBlocks(newBlocks);
+  // Invalidate the meta ETag so the admin re-fetches the schema on next poll.
+  invalidateMetaCache();
+  // Clear stale loader cache entries after decofile update
+  clearLoaderCache();
+
+  const newBlockCount = Object.keys(newBlocks).length;
+  const revision = getRevision();
+
+  return new Response(
+    JSON.stringify({
+      ok: true,
+      previousBlockCount,
+      newBlockCount,
+      revision,
+      timestamp: Date.now(),
+    }),
+    { status: 200, headers: { "Content-Type": "application/json" } },
+  );
+}

package/src/admin/index.ts

@@ -0,0 +1,24 @@
+export { corsHeaders, isAdminOrLocalhost } from "./cors";
+export { handleDecofileRead, handleDecofileReload } from "./decofile";
+export {
+  handleInvoke,
+  type InvokeAction,
+  type InvokeLoader,
+  setInvokeActions,
+  setInvokeLoaders,
+} from "./invoke";
+export { LIVE_CONTROLS_SCRIPT } from "./liveControls";
+export { handleMeta, setMetaData } from "./meta";
+export { handleRender, setRenderShell } from "./render";
+export {
+  composeMeta,
+  getRegisteredLoaders,
+  getRegisteredMatchers,
+  type LoaderConfig,
+  type MatcherConfig,
+  type MetaResponse,
+  registerLoaderSchema,
+  registerLoaderSchemas,
+  registerMatcherSchema,
+  registerMatcherSchemas,
+} from "./schema";

package/src/admin/invoke.ts

@@ -0,0 +1,163 @@
+/**
+ * Handles /deco/invoke -- executes loaders and actions by key.
+ *
+ * Supports:
+ * - Single invoke by key: POST /deco/invoke/some/loader.ts
+ * - Batch invoke: POST /deco/invoke with { key: payload } body
+ * - FormData parsing for file uploads and form submissions
+ * - `?select=field1,field2` to pick fields from the result
+ * - Resolves __resolveType in batch payloads
+ */
+
+export type InvokeLoader = (props: any, request: Request) => Promise<any>;
+export type InvokeAction = (props: any, request: Request) => Promise<any>;
+
+let getRegisteredLoaders: () => Record<string, InvokeLoader> = () => ({});
+let getRegisteredActions: () => Record<string, InvokeAction> = () => ({});
+
+export function setInvokeLoaders(getter: () => Record<string, InvokeLoader>) {
+  getRegisteredLoaders = getter;
+}
+
+export function setInvokeActions(getter: () => Record<string, InvokeAction>) {
+  getRegisteredActions = getter;
+}
+
+const JSON_HEADERS = { "Content-Type": "application/json" } as const;
+
+const isDev =
+  typeof globalThis.process !== "undefined" && globalThis.process.env?.NODE_ENV === "development";
+
+function selectFields(data: unknown, select?: string[]): unknown {
+  if (!select?.length || !data || typeof data !== "object") return data;
+  if (Array.isArray(data)) return data.map((item) => selectFields(item, select));
+  const result: Record<string, unknown> = {};
+  for (const key of select) {
+    if (key in (data as Record<string, unknown>)) {
+      result[key] = (data as Record<string, unknown>)[key];
+    }
+  }
+  return result;
+}
+
+function errorResponse(message: string, status: number, error?: unknown) {
+  const body: Record<string, unknown> = { error: message };
+  if (isDev && error instanceof Error && error.stack) {
+    body.stack = error.stack;
+  }
+  return new Response(JSON.stringify(body), { status, headers: JSON_HEADERS });
+}
+
+async function parseBody(request: Request): Promise<any> {
+  const contentType = request.headers.get("content-type") ?? "";
+
+  // FormData
+  if (
+    contentType.includes("multipart/form-data") ||
+    contentType.includes("application/x-www-form-urlencoded")
+  ) {
+    try {
+      const formData = await request.formData();
+      const obj: Record<string, unknown> = {};
+      for (const [key, value] of formData.entries()) {
+        if (obj[key] !== undefined) {
+          // Multiple values → array
+          const existing = Array.isArray(obj[key]) ? (obj[key] as unknown[]) : [obj[key]];
+          existing.push(value);
+          obj[key] = existing;
+        } else {
+          obj[key] = value;
+        }
+      }
+      return obj;
+    } catch {
+      return {};
+    }
+  }
+
+  // URL-encoded search params (for GET fallback)
+  if (request.method === "GET") {
+    const url = new URL(request.url);
+    const propsParam = url.searchParams.get("props");
+    if (propsParam) {
+      try {
+        return JSON.parse(decodeURIComponent(propsParam));
+      } catch {
+        return {};
+      }
+    }
+    return {};
+  }
+
+  // JSON (default for POST)
+  try {
+    return await request.json();
+  } catch {
+    return {};
+  }
+}
+
+function findHandler(
+  key: string,
+): { handler: InvokeLoader | InvokeAction; type: "loader" | "action" } | null {
+  const loaders = getRegisteredLoaders();
+  if (loaders[key]) return { handler: loaders[key], type: "loader" };
+
+  const actions = getRegisteredActions();
+  if (actions[key]) return { handler: actions[key], type: "action" };
+
+  return null;
+}
+
+export async function handleInvoke(request: Request): Promise<Response> {
+  const url = new URL(request.url);
+  const pathParts = url.pathname.split("/deco/invoke/");
+  const invokeKey = pathParts[1] || "";
+  const select = url.searchParams.get("select")?.split(",").filter(Boolean);
+
+  const body = await parseBody(request);
+
+  // Single invoke by key
+  if (invokeKey) {
+    const found = findHandler(invokeKey);
+    if (!found) {
+      return errorResponse(`Unknown handler: ${invokeKey}`, 404);
+    }
+
+    try {
+      const result = await found.handler(body, request);
+      const filtered = selectFields(result, select);
+      return new Response(JSON.stringify(filtered), { status: 200, headers: JSON_HEADERS });
+    } catch (error) {
+      return errorResponse((error as Error).message, 500, error);
+    }
+  }
+
+  // Batch invoke
+  if (request.method === "POST" && body && typeof body === "object" && !Array.isArray(body)) {
+    const results: Record<string, unknown> = {};
+
+    const entries = Object.entries(body as Record<string, unknown>);
+    await Promise.all(
+      entries.map(async ([key, payload]) => {
+        const resolveType = (payload as any)?.__resolveType || key;
+        const found = findHandler(resolveType);
+
+        if (found) {
+          try {
+            const result = await found.handler(payload, request);
+            results[key] = selectFields(result, select);
+          } catch (error) {
+            results[key] = { error: (error as Error).message };
+          }
+        } else {
+          results[key] = { error: `Unknown handler: ${resolveType}` };
+        }
+      }),
+    );
+
+    return new Response(JSON.stringify(results), { status: 200, headers: JSON_HEADERS });
+  }
+
+  return errorResponse("No invoke key specified", 400);
+}

package/src/admin/liveControls.ts

@@ -0,0 +1,29 @@
+/**
+ * Admin Live Controls - Inline script for storefront pages.
+ *
+ * When the storefront is embedded in the admin's iframe, the admin sends
+ * `editor::inject` postMessage events containing a script that handles
+ * the preview navigation loop. This listener receives that script and
+ * evaluates it in the page context.
+ *
+ * Include this script in the root layout (e.g., via a <script> tag) so
+ * the admin can communicate with the storefront.
+ */
+export const LIVE_CONTROLS_SCRIPT = `
+(function() {
+  if (window.__DECO_LIVE_CONTROLS__) return;
+  window.__DECO_LIVE_CONTROLS__ = true;
+
+  addEventListener("message", function(event) {
+    var data = event.data;
+    if (!data || typeof data !== "object") return;
+    switch (data.type) {
+      case "editor::inject":
+        if (data.args && data.args.script) {
+          try { eval(data.args.script); } catch(e) { console.error("[deco] inject error:", e); }
+        }
+        break;
+    }
+  });
+})();
+`;

package/src/admin/meta.ts

@@ -0,0 +1,70 @@
+import { composeMeta, type MetaResponse } from "./schema";
+
+let metaData: MetaResponse | null = null;
+let cachedEtag: string | null = null;
+
+/**
+ * Invalidate the cached ETag so the admin re-fetches meta after a
+ * hot-reload or decofile change.
+ *
+ * Called by decofile.ts after setBlocks() — no server-side loader import
+ * needed here, keeping this module safe for client-side bundles.
+ */
+export function invalidateMetaCache() {
+  cachedEtag = null;
+}
+
+/**
+ * Set the schema metadata that /deco/meta will return.
+ * Runs composeMeta() to inject framework-level schemas (pages, etc.)
+ * on top of the site-generated section schemas.
+ */
+export function setMetaData(data: MetaResponse) {
+  metaData = composeMeta(data);
+  cachedEtag = null;
+}
+
+/**
+ * Content-based hash for ETag.
+ * Uses a simple DJB2-style hash over the serialised JSON so any
+ * definition change results in a different ETag, forcing admin to
+ * re-fetch rather than use stale cached meta.
+ */
+function getEtag(): string {
+  if (!cachedEtag) {
+    const str = JSON.stringify(metaData || {});
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+      hash = ((hash << 5) + hash + str.charCodeAt(i)) >>> 0;
+    }
+    cachedEtag = `"meta-${hash.toString(36)}"`;
+  }
+  return cachedEtag;
+}
+
+export function handleMeta(request: Request): Response {
+  if (!metaData) {
+    return new Response(JSON.stringify({ error: "Schema not initialized" }), {
+      status: 503,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  const ifNoneMatch = request.headers.get("if-none-match");
+  const etag = getEtag();
+
+  if (ifNoneMatch === etag) {
+    return new Response(null, { status: 304, headers: { ETag: etag } });
+  }
+
+  const body = JSON.stringify({ ...metaData, etag });
+
+  return new Response(body, {
+    status: 200,
+    headers: {
+      "Content-Type": "application/json",
+      ETag: etag,
+      "Cache-Control": "must-revalidate",
+    },
+  });
+}

package/src/admin/render.ts

@@ -0,0 +1,205 @@
+import { createElement } from "react";
+import { loadBlocks, withBlocksOverride } from "../cms/loader";
+import { getSection } from "../cms/registry";
+import { resolveValue } from "../cms/resolve";
+import { LIVE_CONTROLS_SCRIPT } from "./liveControls";
+import { getRenderShellConfig } from "./setup";
+
+export { setRenderShell } from "./setup";
+
+function wrapInHtmlShell(sectionHtml: string): string {
+  const { cssHref, fontHrefs, themeName, bodyClass, htmlLang } = getRenderShellConfig();
+  const stylesheets = [
+    ...fontHrefs.map((href) => `<link rel="stylesheet" href="${href}" />`),
+    cssHref ? `<link rel="stylesheet" href="${cssHref}" />` : "",
+  ].join("\n    ");
+
+  const themeAttr = themeName ? ` data-theme="${themeName}"` : "";
+  const langAttr = htmlLang ? ` lang="${htmlLang}"` : "";
+  const bodyAttr = bodyClass ? ` class="${bodyClass}"` : "";
+
+  return `<!DOCTYPE html>
+<html${langAttr}${themeAttr}>
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    ${stylesheets}
+    <script>${LIVE_CONTROLS_SCRIPT}</script>
+</head>
+<body${bodyAttr}>
+${sectionHtml}
+</body>
+</html>`;
+}
+
+/**
+ * Render a single resolved section object to an HTML string.
+ * Returns empty string for unknown or SEO-only sections.
+ */
+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: ${resolveType}</div>`;
+  }
+
+  try {
+    const { __resolveType: _, ...sectionProps } = section;
+    const { renderToString } = await import("react-dom/server");
+    const mod = await sectionLoader();
+    return renderToString(createElement(mod.default, sectionProps));
+  } catch (error) {
+    return `<div style="padding:8px;color:red;font-size:12px;">Error rendering ${resolveType}: ${(error as Error).message}</div>`;
+  }
+}
+
+/**
+ * Handles /live/previews/* -- renders sections to HTML for the admin preview.
+ *
+ * Supports:
+ * - Page compositor (website/pages/Page.tsx): resolves + renders all child sections
+ * - Single section render with full __resolveType resolution
+ * - 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 pathComponent = url.pathname.startsWith(pathPrefix)
+    ? url.pathname.slice(pathPrefix.length)
+    : "";
+  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 {
+      // 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
+    if (component === "website/pages/Page.tsx") {
+      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);
+      }
+
+      return new Response(wrapInHtmlShell(htmlParts.join("\n")), {
+        status: 200,
+        headers: { "Content-Type": "text/html; charset=utf-8" },
+      });
+    }
+
+    // Single section render
+    const sectionLoader = getSection(component);
+    if (!sectionLoader) {
+      const unknownHtml = wrapInHtmlShell(
+        `<div style="padding:20px;color:red;">Unknown section: ${component}</div>`,
+      );
+      return new Response(unknownHtml, {
+        status: 200,
+        headers: { "Content-Type": "text/html" },
+      });
+    }
+
+    try {
+      const resolvedProps = (await resolveValue(props)) as Record<string, unknown>;
+      const { __resolveType: _, ...cleanProps } = resolvedProps;
+      const { renderToString } = await import("react-dom/server");
+      const mod = await sectionLoader();
+      const sectionHtml = renderToString(createElement(mod.default, cleanProps));
+      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: ${(error as Error).message}</div>`,
+      );
+      return new Response(errorHtml, {
+        status: 200,
+        headers: { "Content-Type": "text/html" },
+      });
+    }
+  };
+
+  if (decofileOverride) {
+    return withBlocksOverride(decofileOverride, renderFn);
+  }
+  return renderFn();
+}