@decocms/start 2.1.3 → 2.3.0

package/package.json

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

package/scripts/generate-schema.ts

@@ -19,7 +19,14 @@ import path from "node:path";
  *   --out         Output file        (default: "src/server/admin/meta.gen.json")
  *   --platform    Platform name      (default: "cloudflare")
  */
-import { type Symbol as MorphSymbol, Node, Project, SyntaxKind, type Type } from "ts-morph";
+import {
+  type Symbol as MorphSymbol,
+  Node,
+  Project,
+  type SourceFile,
+  SyntaxKind,
+  type Type,
+} from "ts-morph";
 
 // ---------------------------------------------------------------------------
 // CLI arg parsing
@@ -448,6 +455,39 @@ function resolveModulePath(
   return fs.existsSync(target) ? target : null;
 }
 
+type SourceFileCache = Map<string, SourceFile>;
+type ModuleResolutionCache = Map<string, string | null>;
+type PropsSchemaCache = Map<string, any>;
+
+function getSourceFile(
+  project: import("ts-morph").Project,
+  filePath: string,
+  cache: SourceFileCache,
+): SourceFile {
+  const normalizedPath = path.resolve(filePath);
+  const cached = cache.get(normalizedPath);
+  if (cached) return cached;
+
+  const sourceFile =
+    project.getSourceFile(normalizedPath) ?? project.addSourceFileAtPath(normalizedPath);
+  cache.set(normalizedPath, sourceFile);
+  return sourceFile;
+}
+
+function resolveModulePathCached(
+  moduleSpec: string,
+  fromFile: string,
+  projectRoot: string,
+  cache: ModuleResolutionCache,
+): string | null {
+  const key = `${fromFile}\0${moduleSpec}`;
+  if (cache.has(key)) return cache.get(key) ?? null;
+
+  const resolved = resolveModulePath(moduleSpec, fromFile, projectRoot);
+  cache.set(key, resolved);
+  return resolved;
+}
+
 /**
  * Recursively follow `export { default } from "..."` chains (up to maxDepth hops)
  * and try to extract Props from each target file.
@@ -458,6 +498,9 @@ function resolvePropsViaReExport(
   filePath: string,
   projectRoot: string,
   maxDepth: number,
+  sourceFileCache: SourceFileCache,
+  moduleResolutionCache: ModuleResolutionCache,
+  propsSchemaCache: PropsSchemaCache,
 ): any | null {
   if (maxDepth <= 0) return null;
 
@@ -471,21 +514,41 @@ function resolvePropsViaReExport(
     });
     if (!hasDefault) continue;
 
-    const targetPath = resolveModulePath(moduleSpec, filePath, projectRoot);
+    const targetPath = resolveModulePathCached(
+      moduleSpec,
+      filePath,
+      projectRoot,
+      moduleResolutionCache,
+    );
     if (!targetPath) continue;
 
+    const cachedProps = propsSchemaCache.get(targetPath);
+    if (cachedProps) return cachedProps;
+
     try {
-      const targetFile = project.addSourceFileAtPath(targetPath);
+      const targetFile = getSourceFile(project, targetPath, sourceFileCache);
 
       const targetProps = targetFile.getInterface("Props");
-      if (targetProps) return typeToJsonSchema(targetProps.getType());
+      if (targetProps) {
+        const schema = typeToJsonSchema(targetProps.getType());
+        propsSchemaCache.set(targetPath, schema);
+        return schema;
+      }
 
       const targetAlias = targetFile.getTypeAlias("Props");
-      if (targetAlias) return typeToJsonSchema(targetAlias.getType());
+      if (targetAlias) {
+        const schema = typeToJsonSchema(targetAlias.getType());
+        propsSchemaCache.set(targetPath, schema);
+        return schema;
+      }
 
       // Type-checker approach: extract from default export call signature
       const propsType = extractDefaultExportPropsType(targetFile);
-      if (propsType) return typeToJsonSchema(propsType);
+      if (propsType) {
+        const schema = typeToJsonSchema(propsType);
+        propsSchemaCache.set(targetPath, schema);
+        return schema;
+      }
 
       // Recurse: target might also re-export from another file
       const deeper = resolvePropsViaReExport(
@@ -494,8 +557,14 @@ function resolvePropsViaReExport(
         targetPath,
         projectRoot,
         maxDepth - 1,
+        sourceFileCache,
+        moduleResolutionCache,
+        propsSchemaCache,
       );
-      if (deeper) return deeper;
+      if (deeper) {
+        propsSchemaCache.set(targetPath, deeper);
+        return deeper;
+      }
     } catch {
       // Target file couldn't be parsed
     }
@@ -530,6 +599,9 @@ function generateMeta(): MetaResponse {
   const definitions: Record<string, any> = {};
   const sectionBlocks: Record<string, any> = {};
   const sectionRootAnyOf: any[] = [];
+  const sourceFileCache: SourceFileCache = new Map();
+  const moduleResolutionCache: ModuleResolutionCache = new Map();
+  const propsSchemaCache: PropsSchemaCache = new Map();
 
   // Resolvable: the admin's deRefUntil expects the LITERAL key "Resolvable",
   // not a base64-encoded version. We store both for compatibility.
@@ -553,13 +625,16 @@ function generateMeta(): MetaResponse {
 
   const sectionFiles = findTsxFiles(sectionsDir);
   console.log(`Found ${sectionFiles.length} section files`);
+  for (const filePath of sectionFiles) {
+    getSourceFile(project, filePath, sourceFileCache);
+  }
 
   for (const filePath of sectionFiles) {
     const relativePath = path.relative(srcDir, filePath);
     const blockKey = `${SITE_NAMESPACE}/${relativePath}`;
 
     try {
-      const sourceFile = project.addSourceFileAtPath(filePath);
+      const sourceFile = getSourceFile(project, filePath, sourceFileCache);
 
       let propsSchema: any = null;
 
@@ -573,7 +648,16 @@ function generateMeta(): MetaResponse {
       // Strategy 2: Follow re-exports recursively (up to 3 hops)
       // Handles: section → island → component chains
       if (!propsSchema) {
-        propsSchema = resolvePropsViaReExport(project, sourceFile, filePath, root, 3);
+        propsSchema = resolvePropsViaReExport(
+          project,
+          sourceFile,
+          filePath,
+          root,
+          3,
+          sourceFileCache,
+          moduleResolutionCache,
+          propsSchemaCache,
+        );
       }
 
       // Strategy 4: Default export call signature in the section file via type checker

package/scripts/migrate/transforms/imports.ts

@@ -46,10 +46,36 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   [/^"apps\/vtex\/hooks\/useWishlist(?:\.ts)?"$/, `"~/hooks/useWishlist"`],
   [/^"apps\/vtex\/hooks\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/hooks/$1"`],
   // Specific VTEX utils that moved to different paths in @decocms/apps
-  [/^"apps\/vtex\/utils\/fetchVTEX(?:\.ts)?"$/, `"@decocms/apps/vtex/client"`],
+  // fetchVTEX (generic fetchSafe + QS sanitization) lives at vtex/utils/fetch in apps-start.
+  [/^"apps\/vtex\/utils\/fetchVTEX(?:\.ts)?"$/, `"@decocms/apps/vtex/utils/fetch"`],
   [/^"apps\/vtex\/utils\/client(?:\.ts)?"$/, `"@decocms/apps/vtex/client"`],
   [/^"apps\/vtex\/utils\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/utils/$1"`],
   [/^"apps\/vtex\/actions\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/actions/$1"`],
+  // Tier B loader path rewrites (apps-start has no `intelligentSearch/`, `legacy/<file>`, or `paths/` subdirs).
+  // Intelligent Search loaders moved to inline-loaders/.
+  [
+    /^"apps\/vtex\/loaders\/intelligentSearch\/productList(?:\.ts)?"$/,
+    `"@decocms/apps/vtex/inline-loaders/productList"`,
+  ],
+  [
+    /^"apps\/vtex\/loaders\/intelligentSearch\/productListingPage(?:\.ts)?"$/,
+    `"@decocms/apps/vtex/inline-loaders/productListingPage"`,
+  ],
+  [
+    /^"apps\/vtex\/loaders\/intelligentSearch\/productDetailsPage(?:\.ts)?"$/,
+    `"@decocms/apps/vtex/inline-loaders/productDetailsPage"`,
+  ],
+  [
+    /^"apps\/vtex\/loaders\/intelligentSearch\/suggestions(?:\.ts)?"$/,
+    `"@decocms/apps/vtex/inline-loaders/suggestions"`,
+  ],
+  // Legacy product loaders are consolidated into a single file (named exports).
+  [
+    /^"apps\/vtex\/loaders\/legacy\/(?:productList|productListingPage|productDetailsPage|search|category)(?:\.ts)?"$/,
+    `"@decocms/apps/vtex/loaders/legacy"`,
+  ],
+  // Path-default loaders (sitemap seeds) don't exist in TanStack Start — paths resolve at request time.
+  [/^"apps\/vtex\/loaders\/paths\/(?:[^"]+)(?:\.ts)?"$/, null],
   [/^"apps\/vtex\/loaders\/([^"]+?)(?:\.ts)?"$/, `"@decocms/apps/vtex/loaders/$1"`],
   [/^"apps\/vtex\/types(?:\.ts)?"$/, `"@decocms/apps/vtex/types"`],
   [/^"apps\/vtex\/mod(?:\.ts)?"$/, `"~/types/vtex-app"`],

package/src/routes/index.ts

@@ -1,3 +1,5 @@
+export type { PageSeo } from "../cms/resolve";
+export type { Device } from "../sdk/useDevice";
 export {
   decoInvokeRoute,
   decoMetaRoute,
@@ -15,5 +17,8 @@ export {
   setSectionChunkMap,
 } from "./cmsRoute";
 export { CmsPage, NotFoundPage } from "./components";
-export type { PageSeo } from "../cms/resolve";
-export type { Device } from "../sdk/useDevice";
+export {
+  resolveSiteGlobals,
+  type SiteGlobalsLoaderData,
+  withSiteGlobals,
+} from "./withSiteGlobals";

package/src/routes/withSiteGlobals.test.ts

@@ -0,0 +1,272 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { onChangeListeners } = vi.hoisted(() => ({
+  onChangeListeners: [] as Array<() => void>,
+}));
+
+vi.mock("../cms", () => ({
+  loadBlocks: vi.fn(),
+  onChange: vi.fn((listener: () => void) => {
+    onChangeListeners.push(listener);
+  }),
+  resolvePageSections: vi.fn(),
+}));
+
+import { loadBlocks, resolvePageSections } from "../cms";
+import { __resetSiteGlobalsCache, resolveSiteGlobals, withSiteGlobals } from "./withSiteGlobals";
+
+const mockedLoadBlocks = loadBlocks as unknown as ReturnType<typeof vi.fn>;
+const mockedResolvePageSections = resolvePageSections as unknown as ReturnType<typeof vi.fn>;
+
+describe("withSiteGlobals", () => {
+  beforeEach(() => {
+    __resetSiteGlobalsCache();
+    mockedLoadBlocks.mockReset();
+    mockedResolvePageSections.mockReset();
+  });
+
+  describe("resolveSiteGlobals", () => {
+    it("returns empty when there is no Site block", async () => {
+      mockedLoadBlocks.mockReturnValue({});
+      const result = await resolveSiteGlobals();
+      expect(result.resolvedSections).toEqual([]);
+      expect(result.rawRefs).toEqual([]);
+      expect(mockedResolvePageSections).not.toHaveBeenCalled();
+    });
+
+    it("returns empty when Site block has no globals", async () => {
+      mockedLoadBlocks.mockReturnValue({ site: { seo: { title: "x" } } });
+      const result = await resolveSiteGlobals();
+      expect(result.resolvedSections).toEqual([]);
+      expect(result.rawRefs).toEqual([]);
+      expect(mockedResolvePageSections).not.toHaveBeenCalled();
+    });
+
+    it("gathers theme + global + pageSections in order", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: {
+          theme: { __resolveType: "Theme" },
+          global: [{ __resolveType: "Analytics" }, { __resolveType: "WishlistProvider" }],
+          pageSections: [{ __resolveType: "Session" }],
+        },
+      });
+      const resolved = [
+        { component: "Theme.tsx", props: {}, key: "k0" },
+        { component: "Analytics.tsx", props: {}, key: "k1" },
+        { component: "Wishlist.tsx", props: {}, key: "k2" },
+        { component: "Session.tsx", props: {}, key: "k3" },
+      ];
+      mockedResolvePageSections.mockResolvedValue(resolved);
+
+      const result = await resolveSiteGlobals();
+
+      expect(result.rawRefs).toEqual([
+        { __resolveType: "Theme" },
+        { __resolveType: "Analytics" },
+        { __resolveType: "WishlistProvider" },
+        { __resolveType: "Session" },
+      ]);
+      expect(result.resolvedSections).toEqual(resolved);
+      expect(mockedResolvePageSections).toHaveBeenCalledTimes(1);
+    });
+
+    it("accepts both `site` (lowercase) and `Site` (PascalCase) block keys", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        Site: { theme: { __resolveType: "Theme" } },
+      });
+      mockedResolvePageSections.mockResolvedValue([
+        { component: "Theme.tsx", props: {}, key: "k0" },
+      ]);
+      const result = await resolveSiteGlobals();
+      expect(result.rawRefs).toEqual([{ __resolveType: "Theme" }]);
+      expect(result.resolvedSections).toHaveLength(1);
+    });
+
+    it("dedupes inflight requests (single resolvePageSections call for parallel callers)", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: { global: [{ __resolveType: "Analytics" }] },
+      });
+      let resolveFn!: (v: unknown[]) => void;
+      mockedResolvePageSections.mockImplementation(
+        () =>
+          new Promise((res) => {
+            resolveFn = res as any;
+          }),
+      );
+
+      const a = resolveSiteGlobals();
+      const b = resolveSiteGlobals();
+      resolveFn([{ component: "A.tsx", props: {}, key: "k0" }]);
+      const [ra, rb] = await Promise.all([a, b]);
+
+      expect(ra).toEqual(rb);
+      expect(mockedResolvePageSections).toHaveBeenCalledTimes(1);
+    });
+
+    it("caches across calls within TTL", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: { global: [{ __resolveType: "Analytics" }] },
+      });
+      mockedResolvePageSections.mockResolvedValue([{ component: "A.tsx", props: {}, key: "k0" }]);
+
+      await resolveSiteGlobals();
+      await resolveSiteGlobals();
+      await resolveSiteGlobals();
+
+      expect(mockedResolvePageSections).toHaveBeenCalledTimes(1);
+    });
+
+    it("invalidates cache when onChange fires", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: { global: [{ __resolveType: "Analytics" }] },
+      });
+      mockedResolvePageSections.mockResolvedValue([{ component: "A.tsx", props: {}, key: "k0" }]);
+
+      await resolveSiteGlobals();
+      expect(mockedResolvePageSections).toHaveBeenCalledTimes(1);
+
+      // Simulate a CMS reload
+      for (const listener of onChangeListeners) listener();
+
+      await resolveSiteGlobals();
+      expect(mockedResolvePageSections).toHaveBeenCalledTimes(2);
+    });
+
+    it("does not cache failures (next call retries)", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: { global: [{ __resolveType: "Analytics" }] },
+      });
+      mockedResolvePageSections
+        .mockRejectedValueOnce(new Error("boom"))
+        .mockResolvedValueOnce([{ component: "A.tsx", props: {}, key: "k0" }]);
+
+      const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      const first = await resolveSiteGlobals();
+      expect(first.resolvedSections).toEqual([]);
+
+      const second = await resolveSiteGlobals();
+      expect(second.resolvedSections).toHaveLength(1);
+      expect(mockedResolvePageSections).toHaveBeenCalledTimes(2);
+      errSpy.mockRestore();
+    });
+  });
+
+  describe("withSiteGlobals wrapper", () => {
+    it("passes through null page (404) without merging globals", async () => {
+      mockedLoadBlocks.mockReturnValue({});
+      const baseLoader = vi.fn().mockResolvedValue(null);
+      const cfg = withSiteGlobals({ loader: baseLoader });
+      const result = await cfg.loader();
+      expect(result).toBeNull();
+    });
+
+    it("merges resolved globals BEFORE page sections", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: { theme: { __resolveType: "Theme" } },
+      });
+      mockedResolvePageSections.mockResolvedValue([
+        { component: "Theme.tsx", props: {}, key: "g0" },
+      ]);
+      const baseLoader = vi.fn().mockResolvedValue({
+        resolvedSections: [
+          { component: "Header.tsx", props: {}, key: "p0" },
+          { component: "Hero.tsx", props: {}, key: "p1" },
+        ],
+        // arbitrary other route fields preserved
+        cacheProfile: "static",
+      });
+
+      const cfg = withSiteGlobals({ loader: baseLoader });
+      const result = await cfg.loader();
+
+      expect(result.resolvedSections.map((s: any) => s.component)).toEqual([
+        "Theme.tsx",
+        "Header.tsx",
+        "Hero.tsx",
+      ]);
+      expect(result.cacheProfile).toBe("static");
+    });
+
+    it("dedupes globals whose component already appears on the page", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: {
+          global: [{ __resolveType: "Session" }, { __resolveType: "Theme" }],
+        },
+      });
+      mockedResolvePageSections.mockResolvedValue([
+        { component: "Session.tsx", props: {}, key: "g0" },
+        { component: "Theme.tsx", props: {}, key: "g1" },
+      ]);
+      const baseLoader = vi.fn().mockResolvedValue({
+        // Page already mounts Session — global Session should NOT duplicate.
+        resolvedSections: [{ component: "Session.tsx", props: { fromPage: true }, key: "p0" }],
+      });
+
+      const cfg = withSiteGlobals({ loader: baseLoader });
+      const result = await cfg.loader();
+
+      const components = result.resolvedSections.map((s: any) => s.component);
+      // Only one Session, taken from the page (page-level wins).
+      expect(components).toEqual(["Theme.tsx", "Session.tsx"]);
+      const session = result.resolvedSections.find((s: any) => s.component === "Session.tsx");
+      expect(session.props.fromPage).toBe(true);
+    });
+
+    it("dedupes within globals (Session in both site.global AND site.pageSections)", async () => {
+      mockedLoadBlocks.mockReturnValue({
+        site: {
+          global: [{ __resolveType: "Session" }],
+          pageSections: [{ __resolveType: "Session" }],
+        },
+      });
+      mockedResolvePageSections.mockResolvedValue([
+        { component: "Session.tsx", props: { from: "global" }, key: "g0" },
+        { component: "Session.tsx", props: { from: "pageSections" }, key: "g1" },
+      ]);
+      const baseLoader = vi.fn().mockResolvedValue({ resolvedSections: [] });
+
+      const cfg = withSiteGlobals({ loader: baseLoader });
+      const result = await cfg.loader();
+
+      // Only one Session ends up in the final tree (first-wins within globals).
+      expect(result.resolvedSections).toHaveLength(1);
+      expect(result.resolvedSections[0].props.from).toBe("global");
+    });
+
+    it("attaches siteGlobals.rawRefs for site to read head-injection data", async () => {
+      const analyticsRef = {
+        __resolveType: "website/sections/Analytics/Analytics.tsx",
+        trackingIds: ["GTM-ABC"],
+      };
+      mockedLoadBlocks.mockReturnValue({
+        site: { global: [analyticsRef] },
+      });
+      mockedResolvePageSections.mockResolvedValue([]);
+      const baseLoader = vi.fn().mockResolvedValue({ resolvedSections: [] });
+
+      const cfg = withSiteGlobals({ loader: baseLoader });
+      const result = await cfg.loader();
+
+      expect(result.siteGlobals).toEqual({ rawRefs: [analyticsRef] });
+    });
+
+    it("preserves wrapped loader's other return fields", async () => {
+      mockedLoadBlocks.mockReturnValue({});
+      const baseLoader = vi.fn().mockResolvedValue({
+        resolvedSections: [],
+        seo: { title: "Hello" },
+        cacheProfile: "product",
+        device: "mobile",
+        pageUrl: "https://store.com/x",
+      });
+
+      const cfg = withSiteGlobals({ loader: baseLoader });
+      const result = await cfg.loader();
+
+      expect(result.seo).toEqual({ title: "Hello" });
+      expect(result.cacheProfile).toBe("product");
+      expect(result.device).toBe("mobile");
+      expect(result.pageUrl).toBe("https://store.com/x");
+    });
+  });
+});

package/src/routes/withSiteGlobals.ts

@@ -0,0 +1,228 @@
+/**
+ * Site Globals Wrapper
+ *
+ * Opt-in helper that merges sections declared in the CMS `Site` block
+ * (`site.theme + site.global + site.pageSections`) into every page's
+ * `resolvedSections` array.
+ *
+ * Without this wrapper, only `site.seo` is consumed by `cmsRouteConfig` —
+ * the rest of the Site block is dormant CMS data. Sites that declare
+ * theme/analytics/wishlist/help-button blocks at the site level (rather
+ * than per-page) can opt in here to have them rendered automatically.
+ *
+ * @example Site's `src/routes/$.tsx`:
+ * ```ts
+ * import { createFileRoute, notFound } from "@tanstack/react-router";
+ * import { cmsRouteConfig, withSiteGlobals } from "@decocms/start/routes";
+ *
+ * export const Route = createFileRoute("/$")({
+ *   ...withSiteGlobals(cmsRouteConfig({
+ *     siteName: "Bagaggio",
+ *     defaultTitle: "Bagaggio",
+ *   })),
+ *   component: ...,
+ * });
+ * ```
+ */
+
+import type { ResolvedSection } from "../cms";
+import { loadBlocks, onChange, resolvePageSections } from "../cms";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Loader output additions when `withSiteGlobals` is applied. */
+export interface SiteGlobalsLoaderData {
+  /**
+   * Raw refs (before resolution) declared in `site.theme`, `site.global`, and
+   * `site.pageSections`. Includes refs for sections that don't resolve into
+   * the section tree (`SKIP_RESOLVE_TYPES`) — useful for sites that need to
+   * read site-level data (analytics IDs, manifest config, etc.) outside the
+   * normal section render path.
+   *
+   * Ordering: `theme`, then `global`, then `pageSections`.
+   */
+  rawRefs: unknown[];
+}
+
+interface SiteBlock {
+  theme?: unknown;
+  global?: unknown[];
+  pageSections?: unknown[];
+}
+
+interface CacheEntry {
+  resolvedSections: ResolvedSection[];
+  rawRefs: unknown[];
+  expiresAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Globals resolution (cached, with onChange invalidation)
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CACHE_TTL_MS = 5 * 60_000;
+const cacheTtlMs = DEFAULT_CACHE_TTL_MS;
+
+let cache: CacheEntry | null = null;
+let inflight: Promise<CacheEntry> | null = null;
+
+onChange(() => {
+  cache = null;
+  inflight = null;
+});
+
+function readSiteBlock(): SiteBlock | null {
+  const blocks = loadBlocks();
+  // Block keys vary by site convention — try both common cases.
+  const site = (blocks.site ?? blocks.Site) as SiteBlock | undefined;
+  return site ?? null;
+}
+
+function gatherSectionRefs(site: SiteBlock): unknown[] {
+  const refs: unknown[] = [];
+  if (site.theme) refs.push(site.theme);
+  if (Array.isArray(site.global)) refs.push(...site.global);
+  if (Array.isArray(site.pageSections)) refs.push(...site.pageSections);
+  return refs;
+}
+
+const EMPTY_ENTRY: CacheEntry = {
+  resolvedSections: [],
+  rawRefs: [],
+  expiresAt: Number.POSITIVE_INFINITY, // empty entries don't need refresh
+};
+
+/**
+ * Resolve `site.theme + site.global + site.pageSections` into a list of
+ * `ResolvedSection`s, with in-flight dedup and 5-minute SWR caching.
+ *
+ * Cache is invalidated by `onChange()` from the CMS loader, so admin edits
+ * and decofile reloads are reflected on the next request.
+ *
+ * Exposed as a util so sites can call it directly if they need globals
+ * outside the route loader path (rare).
+ */
+export async function resolveSiteGlobals(): Promise<{
+  resolvedSections: ResolvedSection[];
+  rawRefs: unknown[];
+}> {
+  const now = Date.now();
+  if (cache && cache.expiresAt > now) return cache;
+  if (inflight) return inflight;
+
+  const site = readSiteBlock();
+  if (!site) return EMPTY_ENTRY;
+
+  const rawRefs = gatherSectionRefs(site);
+  if (rawRefs.length === 0) return EMPTY_ENTRY;
+
+  inflight = (async () => {
+    try {
+      const resolvedSections = await resolvePageSections(rawRefs);
+      const entry: CacheEntry = {
+        resolvedSections,
+        rawRefs,
+        expiresAt: Date.now() + cacheTtlMs,
+      };
+      cache = entry;
+      return entry;
+    } catch (err) {
+      console.error("[site-globals] failed to resolve:", err);
+      // Don't cache failures — let the next request retry.
+      return { resolvedSections: [], rawRefs, expiresAt: 0 };
+    } finally {
+      inflight = null;
+    }
+  })();
+
+  return inflight;
+}
+
+// ---------------------------------------------------------------------------
+// Dedupe — collapse global/pageSection components that also exist on the page
+// ---------------------------------------------------------------------------
+
+/**
+ * Filter `globals` to remove sections whose `component` already appears in
+ * `existing` (page-level sections). Page sections take precedence — globals
+ * that conflict are dropped.
+ *
+ * This collapses the common case where a section like `Session` is declared
+ * both in `site.global` and in a page's section list, which would otherwise
+ * render twice.
+ */
+function dedupeGlobals(globals: ResolvedSection[], existing: ResolvedSection[]): ResolvedSection[] {
+  if (globals.length === 0) return [];
+  const seenComponents = new Set<string>();
+  for (const s of existing) {
+    if (typeof s.component === "string") seenComponents.add(s.component);
+  }
+  const result: ResolvedSection[] = [];
+  for (const s of globals) {
+    if (typeof s.component === "string") {
+      if (seenComponents.has(s.component)) continue;
+      seenComponents.add(s.component); // also dedupe within globals (e.g. Session in both site.global AND site.pageSections)
+    }
+    result.push(s);
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Loader wrapper
+// ---------------------------------------------------------------------------
+
+type AnyLoader = (...args: any[]) => Promise<any>;
+
+function wrapLoader<L extends AnyLoader>(loader: L): L {
+  const wrapped: AnyLoader = async (...args: Parameters<L>) => {
+    const [page, globals] = await Promise.all([loader(...args), resolveSiteGlobals()]);
+    if (!page) return page;
+
+    const existing: ResolvedSection[] =
+      (page as { resolvedSections?: ResolvedSection[] }).resolvedSections ?? [];
+    const merged = [...dedupeGlobals(globals.resolvedSections, existing), ...existing];
+
+    return {
+      ...page,
+      resolvedSections: merged,
+      siteGlobals: { rawRefs: globals.rawRefs } satisfies SiteGlobalsLoaderData,
+    };
+  };
+  return wrapped as L;
+}
+
+// ---------------------------------------------------------------------------
+// Public wrapper API
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a route config (from `cmsRouteConfig` or `cmsHomeRouteConfig`) so
+ * that its loader merges site globals into `resolvedSections` and exposes
+ * the raw site-block refs as `loaderData.siteGlobals.rawRefs`.
+ *
+ * Sites that don't declare `site.theme/site.global/site.pageSections` in
+ * the CMS see no behavior change (the wrapper short-circuits).
+ *
+ * Ordering: globals render BEFORE page sections (theme injects CSS first,
+ * fixed-position helpers mount as asides, etc.). Within globals, ordering
+ * is `theme → global → pageSections`.
+ */
+export function withSiteGlobals<T extends { loader: AnyLoader }>(routeConfig: T): T {
+  return {
+    ...routeConfig,
+    loader: wrapLoader(routeConfig.loader),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Test-only resets (not exported in public types — used by withSiteGlobals.test.ts)
+// ---------------------------------------------------------------------------
+
+/** @internal */
+export function __resetSiteGlobalsCache() {
+  cache = null;
+  inflight = null;
+}