@decocms/start 0.19.0

package/src/admin/setup.ts

@@ -0,0 +1,44 @@
+/**
+ * Client-safe admin setup functions.
+ *
+ * These functions only set module-level state (no node: imports,
+ * no AsyncLocalStorage). Safe to import in both client and SSR builds.
+ *
+ * For server-only handlers (handleMeta, handleRender, etc.),
+ * import from "@decocms/start/admin" instead.
+ */
+
+export { type InvokeAction, type InvokeLoader, setInvokeActions, setInvokeLoaders } from "./invoke";
+export { setMetaData } from "./meta";
+export {
+  type LoaderConfig,
+  type MatcherConfig,
+  registerLoaderSchema,
+  registerLoaderSchemas,
+  registerMatcherSchema,
+  registerMatcherSchemas,
+} from "./schema";
+
+let cssHref: string | null = null;
+let fontHrefs: string[] = [];
+let themeName = "light";
+let bodyClass = "bg-base-100 text-base-content";
+let htmlLang = "pt-BR";
+
+export function setRenderShell(opts: {
+  css?: string;
+  fonts?: string[];
+  theme?: string;
+  bodyClass?: string;
+  lang?: string;
+}) {
+  if (opts.css) cssHref = opts.css;
+  if (opts.fonts) fontHrefs = opts.fonts;
+  if (opts.theme !== undefined) themeName = opts.theme;
+  if (opts.bodyClass !== undefined) bodyClass = opts.bodyClass;
+  if (opts.lang !== undefined) htmlLang = opts.lang;
+}
+
+export function getRenderShellConfig() {
+  return { cssHref, fontHrefs, themeName, bodyClass, htmlLang };
+}

package/src/cms/index.ts

@@ -0,0 +1,59 @@
+export type { DecoPage, Resolvable } from "./loader";
+export {
+  findPageByPath,
+  getAllPages,
+  getRevision,
+  loadBlocks,
+  onChange,
+  setBlocks,
+  withBlocksOverride,
+} from "./loader";
+export type { SectionModule, SectionOptions } from "./registry";
+export {
+  getResolvedComponent,
+  getSection,
+  getSectionOptions,
+  getSectionRegistry,
+  getSyncComponent,
+  listRegisteredSections,
+  preloadSectionComponents,
+  preloadSectionModule,
+  registerSection,
+  registerSections,
+  registerSectionsSync,
+  setResolvedComponent,
+} from "./registry";
+export type {
+  AsyncRenderingConfig,
+  CommerceLoader,
+  DanglingReferenceHandler,
+  DecoPageResult,
+  DeferredSection,
+  MatcherContext,
+  ResolvedSection,
+  ResolveErrorHandler,
+} from "./resolve";
+export {
+  addSkipResolveType,
+  getAsyncRenderingConfig,
+  onBeforeResolve,
+  registerCommerceLoader,
+  registerCommerceLoaders,
+  registerMatcher,
+  resolveDecoPage,
+  resolveDeferredSection,
+  resolveValue,
+  setAsyncRenderingConfig,
+  setDanglingReferenceHandler,
+  setResolveErrorHandler,
+} from "./resolve";
+export type { SectionLoaderFn } from "./sectionLoaders";
+export {
+  isLayoutSection,
+  registerCacheableSections,
+  registerLayoutSections,
+  registerSectionLoader,
+  registerSectionLoaders,
+  runSectionLoaders,
+  runSingleSectionLoader,
+} from "./sectionLoaders";

package/src/cms/loader.ts

@@ -0,0 +1,180 @@
+import * as asyncHooks from "node:async_hooks";
+
+export type Resolvable = {
+  __resolveType?: string;
+  [key: string]: unknown;
+};
+
+export type DecoPage = {
+  name: string;
+  path?: string;
+  sections: Resolvable[] | Resolvable;
+  seo?: Record<string, unknown>;
+};
+
+// globalThis-backed storage: TanStack Start server function split modules
+// may get isolated module instances. globalThis ensures shared state.
+const G = globalThis as any;
+if (!G.__deco) G.__deco = {};
+
+let blockData: Record<string, unknown> = G.__deco.blockData ?? {};
+let revision: string | null = G.__deco.revision ?? null;
+
+interface ALSLike<T> {
+  getStore(): T | undefined;
+  run<R>(store: T, fn: () => R): R;
+}
+
+// AsyncLocalStorage might not be available in client builds (Vite replaces
+// node:async_hooks with an empty shim). The namespace import avoids Rollup's
+// named-export validation, and the runtime check prevents construction errors.
+const ALS = (asyncHooks as any).AsyncLocalStorage;
+const blocksOverrideStorage: ALSLike<Record<string, unknown>> = ALS
+  ? new ALS()
+  : { getStore: () => undefined, run: (_s: any, fn: any) => fn() };
+
+// ---------------------------------------------------------------------------
+// Change listeners
+// ---------------------------------------------------------------------------
+
+type ChangeListener = (blocks: Record<string, unknown>, revision: string) => void;
+const changeListeners: ChangeListener[] = [];
+
+/** Register a callback invoked whenever setBlocks() changes the decofile. */
+export function onChange(listener: ChangeListener) {
+  changeListeners.push(listener);
+  return () => {
+    const idx = changeListeners.indexOf(listener);
+    if (idx >= 0) changeListeners.splice(idx, 1);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Revision hashing
+// ---------------------------------------------------------------------------
+
+function computeRevision(blocks: Record<string, unknown>): string {
+  const str = JSON.stringify(blocks);
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash + str.charCodeAt(i)) >>> 0;
+  }
+  return hash.toString(36);
+}
+
+// ---------------------------------------------------------------------------
+// Block management
+// ---------------------------------------------------------------------------
+
+/**
+ * Set the blocks data. Called at startup with generated blocks,
+ * and by the admin on hot-reload.
+ * Notifies all onChange listeners and updates the revision.
+ */
+export function setBlocks(blocks: Record<string, unknown>) {
+  blockData = blocks;
+  revision = computeRevision(blocks);
+
+  // Persist to globalThis so other module instances see them
+  G.__deco.blockData = blockData;
+  G.__deco.revision = revision;
+
+  for (const listener of [...changeListeners]) {
+    try {
+      listener(blocks, revision);
+    } catch (e) {
+      console.error("[CMS] onChange listener error:", e);
+    }
+  }
+}
+
+/**
+ * Load the current blocks. If running inside a `withBlocksOverride` scope
+ * (admin preview), the override is merged on top of the base blocks.
+ */
+export function loadBlocks(): Record<string, unknown> {
+  // Re-sync from globalThis in case setBlocks was called in another module instance
+  if (G.__deco.blockData && G.__deco.blockData !== blockData) {
+    blockData = G.__deco.blockData;
+    revision = G.__deco.revision ?? null;
+  }
+
+  const override = blocksOverrideStorage.getStore();
+  if (override) {
+    return { ...blockData, ...override };
+  }
+  return blockData;
+}
+
+/** Get the current decofile revision hash. Changes on each setBlocks(). */
+export function getRevision(): string | null {
+  return revision;
+}
+
+/**
+ * Run a function with a temporary blocks overlay.
+ *
+ * Used by admin preview: the admin sends a partial decofile (only the
+ * blocks that changed), and `loadBlocks()` returns the merged result
+ * for the duration of the render. Other concurrent requests are not
+ * affected (AsyncLocalStorage is per-request scoped).
+ */
+export function withBlocksOverride<T>(override: Record<string, unknown>, fn: () => T): T {
+  return blocksOverrideStorage.run(override, fn);
+}
+
+export function getAllPages(): Array<{ key: string; page: DecoPage }> {
+  const blocks = loadBlocks();
+  const pages: Array<{ key: string; page: DecoPage; specificity: number }> = [];
+
+  for (const [key, block] of Object.entries(blocks)) {
+    if (!key.startsWith("pages-")) continue;
+    const page = block as DecoPage;
+    if (!page.sections) continue;
+    if (!page.path) continue;
+
+    let specificity = 0;
+    if (page.path === "/*") specificity = 0;
+    else if (page.path.includes(":") || page.path.includes("$")) specificity = 1;
+    else specificity = 2;
+
+    pages.push({ key, page, specificity });
+  }
+
+  return pages
+    .sort((a, b) => b.specificity - a.specificity)
+    .map(({ key, page }) => ({ key, page }));
+}
+
+function matchPath(pattern: string, urlPath: string): Record<string, string> | null {
+  if (pattern === "/*") return { _splat: urlPath };
+
+  const patternParts = pattern.split("/").filter(Boolean);
+  const urlParts = urlPath.split("/").filter(Boolean);
+
+  if (patternParts.length !== urlParts.length) return null;
+
+  const params: Record<string, string> = {};
+  for (let i = 0; i < patternParts.length; i++) {
+    const pp = patternParts[i];
+    const up = urlParts[i];
+    if (pp.startsWith(":")) params[pp.slice(1)] = up;
+    else if (pp !== up) return null;
+  }
+
+  return params;
+}
+
+export function findPageByPath(
+  targetPath: string,
+): { page: DecoPage; params: Record<string, string> } | null {
+  const allPages = getAllPages();
+
+  for (const { page } of allPages) {
+    if (!page.path) continue;
+    const params = matchPath(page.path, targetPath);
+    if (params !== null) return { page, params };
+  }
+
+  return null;
+}

package/src/cms/registry.ts

@@ -0,0 +1,162 @@
+import type { ComponentType } from "react";
+
+export type SectionModule = {
+  default: ComponentType<any>;
+  loader?: (props: any) => Promise<any> | any;
+  LoadingFallback?: ComponentType<any>;
+  ErrorFallback?: ComponentType<{ error: Error }>;
+};
+
+type RegistryEntry = () => Promise<SectionModule>;
+
+export interface SectionOptions {
+  /** Custom loading fallback component for this section. */
+  loadingFallback?: ComponentType<any>;
+  /** Custom error fallback component for this section. */
+  errorFallback?: ComponentType<{ error: Error }>;
+}
+
+// globalThis-backed: server function split modules need access to the registry
+const G = globalThis as any;
+if (!G.__deco) G.__deco = {};
+if (!G.__deco.sectionRegistry) G.__deco.sectionRegistry = {};
+if (!G.__deco.sectionOptions) G.__deco.sectionOptions = {};
+if (!G.__deco.resolvedComponents) G.__deco.resolvedComponents = {};
+if (!G.__deco.syncComponents) G.__deco.syncComponents = {};
+
+const registry: Record<string, RegistryEntry> = G.__deco.sectionRegistry;
+const sectionOptions: Record<string, SectionOptions> = G.__deco.sectionOptions;
+
+// Cache of already-resolved component references.
+// When a module is loaded (server-side or after first client import),
+// the default export is stored here so subsequent renders can use
+// the component directly WITHOUT React.lazy/Suspense — preventing
+// hydration flash on SSR'd content.
+const resolvedComponents: Record<string, ComponentType<any>> = G.__deco.resolvedComponents;
+
+// Static sync registry — components that were statically imported and
+// are guaranteed available on BOTH server and client without any async import.
+// These never need React.lazy/Suspense and render identically on SSR and hydration.
+const syncComponents: Record<string, ComponentType<any>> = G.__deco.syncComponents;
+
+export function registerSection(key: string, loader: RegistryEntry, options?: SectionOptions) {
+  registry[key] = loader;
+  if (options) sectionOptions[key] = options;
+}
+
+export function registerSections(
+  sections: Record<string, RegistryEntry>,
+  defaultOptions?: SectionOptions,
+) {
+  for (const [key, loader] of Object.entries(sections)) {
+    registry[key] = loader;
+    if (defaultOptions) sectionOptions[key] = { ...defaultOptions };
+  }
+}
+
+export function getSection(resolveType: string): RegistryEntry | undefined {
+  return registry[resolveType];
+}
+
+export function getSectionOptions(resolveType: string): SectionOptions | undefined {
+  return sectionOptions[resolveType];
+}
+
+/**
+ * Load a section module eagerly to extract LoadingFallback/ErrorFallback.
+ * Used by DeferredSectionWrapper to show custom skeletons before the section
+ * scrolls into view and its full props are fetched.
+ */
+export async function preloadSectionModule(
+  resolveType: string,
+): Promise<SectionOptions | undefined> {
+  const existing = sectionOptions[resolveType];
+  if (existing?.loadingFallback) return existing;
+
+  const loader = registry[resolveType];
+  if (!loader) return undefined;
+
+  try {
+    const mod = await loader();
+    const opts: SectionOptions = { ...existing };
+    if (mod.LoadingFallback) opts.loadingFallback = mod.LoadingFallback;
+    if (mod.ErrorFallback) opts.errorFallback = mod.ErrorFallback;
+    sectionOptions[resolveType] = opts;
+    return opts;
+  } catch {
+    return existing;
+  }
+}
+
+/**
+ * Get a previously resolved component. Returns undefined if the module
+ * hasn't been imported yet. Use this to render WITHOUT React.lazy/Suspense
+ * for sections whose JS is already loaded — avoids hydration flash.
+ */
+export function getResolvedComponent(key: string): ComponentType<any> | undefined {
+  return resolvedComponents[key];
+}
+
+/**
+ * Store a resolved component reference. Called after a successful import()
+ * so future renders can skip React.lazy entirely.
+ */
+export function setResolvedComponent(key: string, component: ComponentType<any>): void {
+  resolvedComponents[key] = component;
+}
+
+/**
+ * Pre-import section modules and cache their default exports.
+ * Called server-side after resolving eager sections so that
+ * the SSR render tree uses direct component refs instead of React.lazy.
+ */
+export async function preloadSectionComponents(keys: string[]): Promise<void> {
+  await Promise.all(
+    keys.map(async (key) => {
+      if (resolvedComponents[key]) return;
+      const loader = registry[key];
+      if (!loader) return;
+      try {
+        const mod = await loader();
+        if (mod?.default) {
+          resolvedComponents[key] = mod.default;
+        }
+        const opts: SectionOptions = { ...sectionOptions[key] };
+        if (mod.LoadingFallback) opts.loadingFallback = mod.LoadingFallback;
+        if (mod.ErrorFallback) opts.errorFallback = mod.ErrorFallback;
+        sectionOptions[key] = opts;
+      } catch {
+        /* ignore — will fall back to React.lazy */
+      }
+    }),
+  );
+}
+
+/**
+ * Register sections with their already-imported component references.
+ * These are available synchronously on both server and client — no dynamic
+ * import, no React.lazy, no Suspense. Use for critical above-the-fold
+ * sections that must never flash during hydration.
+ */
+export function registerSectionsSync(sections: Record<string, ComponentType<any>>): void {
+  for (const [key, component] of Object.entries(sections)) {
+    syncComponents[key] = component;
+    resolvedComponents[key] = component;
+  }
+}
+
+/**
+ * Get a synchronously-registered component. Returns undefined if the
+ * section was only registered with a lazy loader (registerSections).
+ */
+export function getSyncComponent(key: string): ComponentType<any> | undefined {
+  return syncComponents[key];
+}
+
+export function listRegisteredSections(): string[] {
+  return Object.keys(registry);
+}
+
+export function getSectionRegistry(): Record<string, RegistryEntry> {
+  return registry;
+}