@decocms/tanstack 7.0.0

package/src/routes/components.tsx

@@ -0,0 +1,57 @@
+import { Link } from "@tanstack/react-router";
+import type { DeferredSection, ResolvedSection } from "@decocms/blocks/cms";
+import { DecoPageRenderer } from "../hooks/DecoPageRenderer";
+import type { Device } from "@decocms/blocks/sdk/useDevice";
+
+/**
+ * Default CMS page component. Renders all resolved sections.
+ * Sites can use this directly or build their own.
+ */
+export function CmsPage({
+  sections,
+  deferredSections,
+  deferredPromises,
+  pagePath,
+  pageUrl,
+  device,
+}: {
+  sections: ResolvedSection[];
+  deferredSections?: DeferredSection[];
+  deferredPromises?: Record<string, Promise<ResolvedSection | null>>;
+  pagePath?: string;
+  pageUrl?: string;
+  /** Server-resolved device from the page loader — keeps useDevice() hydration-stable. */
+  device?: Device;
+}) {
+  return (
+    <div>
+      <DecoPageRenderer
+        sections={sections}
+        deferredSections={deferredSections}
+        deferredPromises={deferredPromises}
+        pagePath={pagePath}
+        pageUrl={pageUrl}
+        device={device}
+      />
+    </div>
+  );
+}
+
+/**
+ * Default 404 page for CMS routes.
+ * Sites can override with their own branded version.
+ */
+export function NotFoundPage() {
+  return (
+    <div className="min-h-screen flex items-center justify-center">
+      <div className="text-center">
+        <h1 className="text-6xl font-bold text-base-content/20 mb-4">404</h1>
+        <h2 className="text-2xl font-bold mb-2">Page Not Found</h2>
+        <p className="text-base-content/60 mb-6">No CMS page block matches this URL.</p>
+        <Link to="/" className="btn btn-primary">
+          Go Home
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/routes/index.ts

@@ -0,0 +1,24 @@
+export type { PageSeo } from "@decocms/blocks/cms";
+export type { Device } from "@decocms/blocks/sdk/useDevice";
+export {
+  decoInvokeRoute,
+  decoMetaRoute,
+  decoRenderRoute,
+} from "./adminRoutes";
+export {
+  CmsPagePendingFallback,
+  type CmsRouteOptions,
+  cmsHomeRouteConfig,
+  cmsRouteConfig,
+  deferredSectionLoader,
+  loadCmsHomePage,
+  loadCmsPage,
+  loadDeferredSection,
+  setSectionChunkMap,
+} from "./cmsRoute";
+export { CmsPage, NotFoundPage } from "./components";
+export {
+  resolveSiteGlobals,
+  type SiteGlobalsLoaderData,
+  withSiteGlobals,
+} from "./withSiteGlobals";

package/src/routes/pageUrl.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import { derivePageUrl, isClientNavigation } from "./pageUrl";
+
+describe("derivePageUrl (#280 — client-nav request URL)", () => {
+  it("SSR real page without query: rebuilds from fullPath", () => {
+    expect(
+      derivePageUrl("/granado/produto", new URL("https://o.com/granado/produto")),
+    ).toBe("https://o.com/granado/produto");
+  });
+
+  it("SSR real page preserves duplicate query params from the server URL", () => {
+    // The TanStack search record collapses dup params; the server URL keeps them.
+    expect(
+      derivePageUrl(
+        "/c/shoes?filter.category-1=a",
+        new URL("https://o.com/c/shoes?filter.category-1=a&filter.category-1=b"),
+      ),
+    ).toBe("https://o.com/c/shoes?filter.category-1=a&filter.category-1=b");
+  });
+
+  it("client nav without query: rebuilds from fullPath, NOT the /_serverFn URL", () => {
+    // The regression guard: getRequestUrl() is the serverFn endpoint here.
+    const serverUrl = new URL(
+      "https://o.com/_serverFn/loadCmsPage?payload=%2Fgranado%2Fproduto",
+    );
+    expect(derivePageUrl("/granado/produto", serverUrl)).toBe(
+      "https://o.com/granado/produto",
+    );
+  });
+
+  it("client nav with query: rebuilds path+search from fullPath", () => {
+    const serverUrl = new URL("https://o.com/_serverFn/loadCmsPage?payload=x");
+    expect(derivePageUrl("/s?q=foo", serverUrl)).toBe("https://o.com/s?q=foo");
+  });
+
+  it("home '/' on client nav: rebuilds to '/', not the /_serverFn URL", () => {
+    // basePath '/' is a prefix of every path; the old startsWith check would
+    // have returned the serverFn URL here.
+    const serverUrl = new URL("https://o.com/_serverFn/loadCmsPage?payload=x");
+    expect(derivePageUrl("/", serverUrl)).toBe("https://o.com/");
+  });
+});
+
+describe("isClientNavigation (SPA vs SSR detection)", () => {
+  it("SSR real page (path matches): false", () => {
+    expect(
+      isClientNavigation("/c/shoes?q=a", new URL("https://o.com/c/shoes?q=a")),
+    ).toBe(false);
+  });
+
+  it("SSR real page without query (path matches): false", () => {
+    expect(
+      isClientNavigation("/granado/produto", new URL("https://o.com/granado/produto")),
+    ).toBe(false);
+  });
+
+  it("client nav (server fn endpoint): true", () => {
+    const serverUrl = new URL("https://o.com/_serverFn/loadCmsPage?payload=x");
+    expect(isClientNavigation("/c/shoes", serverUrl)).toBe(true);
+  });
+
+  it("home '/' on client nav: true", () => {
+    const serverUrl = new URL("https://o.com/_serverFn/loadCmsPage?payload=x");
+    expect(isClientNavigation("/", serverUrl)).toBe(true);
+  });
+
+  it("home '/' on SSR: false", () => {
+    expect(isClientNavigation("/", new URL("https://o.com/"))).toBe(false);
+  });
+});

package/src/routes/pageUrl.ts

@@ -0,0 +1,54 @@
+/**
+ * Derive the real page URL for a CMS page load.
+ *
+ * On client-side (SPA) navigation the CMS server function runs at a
+ * `/_serverFn/<hash>?payload=...` URL — that's what `getRequestUrl()` returns,
+ * and it is NOT the page the router is navigating to. In that case we rebuild
+ * the URL from `fullPath` (the page's path + search). On a real page request
+ * (SSR / full reload) the server URL's path equals the page path, and we prefer
+ * it because it preserves duplicate query params (e.g.
+ * `filter.category-1=a&filter.category-1=b`) that the TanStack Router search
+ * object — a plain `Record<string,string>` — would collapse.
+ *
+ * Keeping the derived `__pageUrl` consistent with `__pagePath` is what makes
+ * URL/slug-keyed loaders resolve identically on SSR and SPA navigation (#280).
+ * The previous logic compared with `startsWith` and fell back to the serverFn
+ * URL when `fullPath` had no query string, leaking `/_serverFn/...` into
+ * `matcherCtx.url` on client nav.
+ *
+ * @param fullPath  page path + optional search, e.g. `/c/shoes?q=foo`
+ * @param serverUrl URL returned by `getRequestUrl()` (real page URL on SSR,
+ *                  `/_serverFn/...` on client nav)
+ */
+export function derivePageUrl(fullPath: string, serverUrl: URL): string {
+  const [basePath] = fullPath.split("?");
+  // Trust the server URL (to keep duplicate query params) only when its path
+  // IS the page being loaded — i.e. a real page request. On client nav the
+  // path is `/_serverFn/...`, so we rebuild from `fullPath` instead.
+  return serverUrl.pathname === basePath && serverUrl.search
+    ? serverUrl.toString()
+    : new URL(fullPath, serverUrl.origin).toString();
+}
+
+/**
+ * True when the page load came from a client-side (SPA) navigation via
+ * TanStack `<Link>`: the CMS server function runs at `/_serverFn/<hash>`, so
+ * `serverUrl.pathname` is NOT the page path. On a real document request (SSR /
+ * full reload, including bots) `serverUrl.pathname === basePath`.
+ *
+ * Section deferral is a streaming-SSR optimization (shrinks the initial HTML /
+ * TTFB). On a client navigation the server fn returns JSON in one shot — there
+ * is no streaming benefit, so deferral only adds a round-trip and a skeleton.
+ * Callers use this to resolve all sections eagerly on SPA navigation.
+ *
+ * Mirrors the `serverUrl.pathname === basePath` comparison `derivePageUrl`
+ * already relies on, so the two stay consistent and we avoid hardcoding the
+ * internal `/_serverFn` path.
+ *
+ * @param fullPath  page path + optional search, e.g. `/c/shoes?q=foo`
+ * @param serverUrl URL returned by `getRequestUrl()`
+ */
+export function isClientNavigation(fullPath: string, serverUrl: URL): boolean {
+  const [basePath] = fullPath.split("?");
+  return serverUrl.pathname !== basePath;
+}

package/src/routes/withSiteGlobals.test.ts

@@ -0,0 +1,206 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { onChangeListeners } = vi.hoisted(() => ({
+  onChangeListeners: [] as Array<() => void>,
+}));
+
+vi.mock("@decocms/blocks/cms", () => ({
+  loadBlocks: vi.fn(),
+  onChange: vi.fn((listener: () => void) => {
+    onChangeListeners.push(listener);
+  }),
+  resolvePageSections: vi.fn(),
+}));
+
+import { loadBlocks, resolvePageSections } from "@decocms/blocks/cms";
+import {
+  __resetSiteGlobalsCache,
+  dedupeGlobals,
+  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 (deprecated no-op)", () => {
+    // Site globals merging moved into the `loadCmsPage` server function so SSR
+    // and SPA navigations both go through the same server-side path (#233).
+    // The wrapper is now a passthrough kept only for backward compatibility.
+    it("is an identity wrapper — returns the route config unchanged", () => {
+      const baseLoader = vi.fn().mockResolvedValue({ resolvedSections: [] });
+      const input = { loader: baseLoader, otherField: "kept" } as any;
+      const cfg = withSiteGlobals(input);
+      expect(cfg).toBe(input);
+      expect(cfg.loader).toBe(baseLoader);
+    });
+  });
+
+  describe("dedupeGlobals", () => {
+    it("returns empty when globals is empty", () => {
+      expect(
+        dedupeGlobals(
+          [],
+          [{ component: "Header.tsx", props: {}, key: "p0" }],
+        ),
+      ).toEqual([]);
+    });
+
+    it("drops globals whose component already appears in existing", () => {
+      const globals = [
+        { component: "Theme.tsx", props: {}, key: "g0" },
+        { component: "Session.tsx", props: {}, key: "g1" },
+      ];
+      const existing = [
+        { component: "Session.tsx", props: { fromPage: true }, key: "p0" },
+      ];
+
+      const result = dedupeGlobals(globals, existing);
+      // Session dropped (already on page); Theme kept.
+      expect(result.map((s) => s.component)).toEqual(["Theme.tsx"]);
+    });
+
+    it("dedupes within globals (first-wins)", () => {
+      const globals = [
+        { component: "Session.tsx", props: { from: "global" }, key: "g0" },
+        { component: "Session.tsx", props: { from: "pageSections" }, key: "g1" },
+      ];
+      const result = dedupeGlobals(globals, []);
+      expect(result).toHaveLength(1);
+      expect(result[0].props.from).toBe("global");
+    });
+  });
+});

package/src/routes/withSiteGlobals.ts

@@ -0,0 +1,222 @@
+/**
+ * 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 "@decocms/blocks/cms";
+import { loadBlocks, onChange, resolvePageSections } from "@decocms/blocks/cms";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A raw site-block ref — the JSON object pulled from a `.deco/blocks/*.json`
+ * file before block resolution. Always an object with at least
+ * `__resolveType`; concrete props vary by block.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type SiteGlobalRef = Record<string, any>;
+
+/** Loader output additions when site globals are merged into the page. */
+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: SiteGlobalRef[];
+}
+
+interface SiteBlock {
+  theme?: SiteGlobalRef;
+  global?: SiteGlobalRef[];
+  pageSections?: SiteGlobalRef[];
+}
+
+interface CacheEntry {
+  resolvedSections: ResolvedSection[];
+  rawRefs: SiteGlobalRef[];
+  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): SiteGlobalRef[] {
+  const refs: SiteGlobalRef[] = [];
+  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: SiteGlobalRef[];
+}> {
+  const now = Date.now();
+  if (cache && cache.expiresAt > now) return cache;
+  if (inflight) return inflight;
+
+  const site = readSiteBlock();
+  if (!site) {
+    // Cache the empty result so subsequent requests don't re-walk the
+    // block registry. `onChange` invalidation still applies — if a Site
+    // block appears later, the listener nulls `cache` and we re-check.
+    cache = EMPTY_ENTRY;
+    return EMPTY_ENTRY;
+  }
+
+  const rawRefs = gatherSectionRefs(site);
+  if (rawRefs.length === 0) {
+    cache = EMPTY_ENTRY;
+    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.
+ */
+export 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;
+}
+
+// ---------------------------------------------------------------------------
+// Public wrapper API (deprecated — kept for backward compat)
+// ---------------------------------------------------------------------------
+
+type AnyLoader = (...args: any[]) => Promise<any>;
+
+/**
+ * @deprecated Site globals are now resolved automatically inside the
+ * `loadCmsPage` / `loadCmsHomePage` server functions. Wrapping
+ * `cmsRouteConfig` is a no-op — the call is kept for backward compat so
+ * existing sites don't need to change their `routes/$.tsx` immediately.
+ *
+ * Previously, this wrapper called `resolveSiteGlobals()` from the route
+ * loader, which runs **client-side** on SPA navigations. On SPA, the vite
+ * plugin replaces `blocks.gen.ts` with `{}` in the client bundle, so
+ * `loadBlocks()` returned a stub and globals silently dropped — see #233.
+ *
+ * Moving resolution into the server function makes SSR (F5) and SPA
+ * navigations both go through the same server-side path.
+ */
+export function withSiteGlobals<T extends { loader: AnyLoader }>(routeConfig: T): T {
+  return routeConfig;
+}
+
+// ---------------------------------------------------------------------------
+// Test-only resets (not exported in public types — used by withSiteGlobals.test.ts)
+// ---------------------------------------------------------------------------
+
+/** @internal */
+export function __resetSiteGlobalsCache() {
+  cache = null;
+  inflight = null;
+}

package/src/sdk/cookiePassthrough.ts

@@ -0,0 +1,58 @@
+/**
+ * Request / Response cookie passthrough helpers for TanStack Start.
+ *
+ * Provides two framework-bound functions that commerce apps
+ * (VTEX, Shopify, etc.) can plug into their cookie provider hooks
+ * to transparently forward browser cookies to API calls and
+ * Set-Cookie headers back to the browser.
+ *
+ * @example
+ * ```ts
+ * // setup.ts
+ * import { getRequestCookieHeader, forwardResponseCookies } from "@decocms/start/sdk/cookiePassthrough";
+ * import { setRequestCookieProvider, setResponseCookieForwarder } from "@decocms/apps/vtex";
+ *
+ * setRequestCookieProvider(getRequestCookieHeader);
+ * setResponseCookieForwarder(forwardResponseCookies);
+ * ```
+ */
+
+import {
+	getRequestHeader,
+	getResponseHeaders,
+	setResponseHeader,
+} from "@tanstack/react-start/server";
+
+/**
+ * Returns the Cookie header from the current TanStack Start request context.
+ * Safe to call outside a request scope (returns undefined).
+ */
+export function getRequestCookieHeader(): string | undefined {
+	try {
+		return getRequestHeader("cookie") ?? undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Appends Set-Cookie headers to the current TanStack Start response.
+ * Preserves any Set-Cookie headers already set by other middleware or
+ * earlier calls, so multiple API calls in one request don't clobber
+ * each other's cookies.
+ *
+ * Safe to call outside a request scope (no-op).
+ */
+export function forwardResponseCookies(cookies: string[]): void {
+	if (!cookies.length) return;
+	try {
+		const headers = getResponseHeaders();
+		const existing: string[] =
+			typeof headers.getSetCookie === "function"
+				? headers.getSetCookie()
+				: [];
+		setResponseHeader("set-cookie", [...existing, ...cookies]);
+	} catch {
+		// Outside request context (build time, etc.) — ignore.
+	}
+}