@decocms/start 2.2.0 → 2.4.0

package/package.json

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

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;
+}

package/src/sdk/index.ts

@@ -11,12 +11,12 @@ export {
   type CacheProfileName,
   type CacheProfileOverrides,
   type CacheTimingWindow,
-  type EdgeCacheConfig,
-  type LoaderCacheOptions,
   cacheHeaders,
   detectCacheProfile,
+  type EdgeCacheConfig,
   edgeCacheConfig,
   getCacheProfile,
+  type LoaderCacheOptions,
   loaderCacheOptions,
   registerCachePattern,
   routeCacheDefaults,
@@ -24,15 +24,26 @@ export {
 } from "./cacheHeaders";
 export { clx } from "./clx";
 export { decodeCookie, deleteCookie, getCookie, getServerSideCookie, setCookie } from "./cookie";
+export { forwardResponseCookies, getRequestCookieHeader } from "./cookiePassthrough";
 export { buildCSPHeaderValue, type CSPOptions, setCSPHeaders } from "./csp";
+export { djb2, djb2Hex } from "./djb2";
 export { isDevMode } from "./env";
+export { buildHtmlShell, type HtmlShellOptions } from "./htmlShell";
 export {
   createInstrumentedFetch,
   type FetchInstrumentationOptions,
   type FetchMetrics,
   instrumentFetch,
 } from "./instrumentedFetch";
-export { batchInvoke, createInvokeProxy, type InvokeProxy, invokeQueryOptions } from "./invoke";
+export {
+  batchInvoke,
+  createAppInvoke,
+  createInvokeProxy,
+  type InvokeProxy,
+  invoke,
+  invokeQueryOptions,
+  type NestedFromFlat,
+} from "./invoke";
 export { createCacheControlCollector, mergeCacheControl } from "./mergeCacheControl";
 export {
   getProductionOrigins,
@@ -59,8 +70,6 @@ export {
   registerTrackingParams,
   stripTrackingParams,
 } from "./urlUtils";
-export { djb2, djb2Hex } from "./djb2";
-export { buildHtmlShell, type HtmlShellOptions } from "./htmlShell";
 export {
   checkDesktop,
   checkMobile,
@@ -74,9 +83,14 @@ export {
 } from "./useDevice";
 export { useHydrated } from "./useHydrated";
 export { useId } from "./useId";
-export { inlineScript, usePartialSection, useScript, useScriptAsDataURI, useSection } from "./useScript";
+export {
+  inlineScript,
+  usePartialSection,
+  useScript,
+  useScriptAsDataURI,
+  useSection,
+} from "./useScript";
 export { createDecoWorkerEntry, type DecoWorkerEntryOptions } from "./workerEntry";
-export { forwardResponseCookies, getRequestCookieHeader } from "./cookiePassthrough";
 export {
   isWrappedError,
   unwrapError,

package/src/sdk/invoke.test.ts

@@ -0,0 +1,115 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createAppInvoke, invoke } from "./invoke";
+
+describe("createAppInvoke", () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("collects nested property access into slash-separated key", async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+
+    const proxy = createAppInvoke();
+    const result = await proxy.vtex.actions.checkout.addItemsToCart({ qty: 1 });
+
+    expect(result).toEqual({ ok: true });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe("/deco/invoke/vtex/actions/checkout/addItemsToCart");
+    expect(init.method).toBe("POST");
+    expect(init.headers).toEqual({ "Content-Type": "application/json" });
+    expect(JSON.parse(init.body)).toEqual({ qty: 1 });
+  });
+
+  it("falls back to .ts suffix when first key returns 404", async () => {
+    fetchMock
+      .mockResolvedValueOnce(new Response(null, { status: 404 }))
+      .mockResolvedValueOnce(new Response(JSON.stringify({ via: "ts" }), { status: 200 }));
+
+    const proxy = createAppInvoke();
+    const result = await proxy.site.loaders.Wishlist({});
+
+    expect(result).toEqual({ via: "ts" });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(fetchMock.mock.calls[0][0]).toBe("/deco/invoke/site/loaders/Wishlist");
+    expect(fetchMock.mock.calls[1][0]).toBe("/deco/invoke/site/loaders/Wishlist.ts");
+  });
+
+  it("throws 'handler not found' when both key and .ts variant 404", async () => {
+    fetchMock.mockResolvedValue(new Response(null, { status: 404 }));
+
+    const proxy = createAppInvoke();
+    await expect(proxy.unknown({})).rejects.toThrow(/invoke\(unknown\) failed: handler not found/);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("throws with status and error body on non-OK non-404 response", async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify({ error: "boom" }), { status: 500 }));
+
+    const proxy = createAppInvoke();
+    await expect(proxy.broken({})).rejects.toThrow(/invoke\(broken\) failed \(500\): boom/);
+  });
+
+  it("defaults to empty object body when called with no props", async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+
+    const proxy = createAppInvoke();
+    await proxy.foo.bar();
+
+    const init = fetchMock.mock.calls[0][1];
+    expect(JSON.parse(init.body)).toEqual({});
+  });
+
+  it("traps `then`, `catch`, `finally` to avoid being awaited as a thenable", () => {
+    const proxy = createAppInvoke();
+    expect(proxy.then).toBeUndefined();
+    expect(proxy.catch).toBeUndefined();
+    expect(proxy.finally).toBeUndefined();
+    // And on a deeper path:
+    expect(proxy.foo.bar.then).toBeUndefined();
+  });
+
+  it("returns undefined for symbol property access (no spurious sub-proxy)", () => {
+    const proxy = createAppInvoke();
+    expect(proxy[Symbol.toPrimitive]).toBeUndefined();
+    expect(proxy[Symbol.iterator]).toBeUndefined();
+  });
+
+  it("respects custom basePath", async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+
+    const proxy = createAppInvoke("/custom/invoke");
+    await proxy.foo.bar({});
+
+    expect(fetchMock.mock.calls[0][0]).toBe("/custom/invoke/foo/bar");
+  });
+});
+
+describe("default invoke singleton", () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("is a usable nested proxy bound to /deco/invoke", async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+
+    await (invoke as any).site.loaders.example({ x: 1 });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0][0]).toBe("/deco/invoke/site/loaders/example");
+  });
+});

package/src/sdk/invoke.ts

@@ -154,29 +154,21 @@ type SplitFirst<S extends string> = S extends `${infer Head}/${infer Tail}`
   ? [Head, Tail]
   : [S, never];
 
-type BuildNested<Key extends string, Value> = SplitFirst<Key> extends [
-  infer H extends string,
-  infer T,
-]
-  ? T extends string
-    ? { [K in H]: BuildNested<T, Value> }
-    : { [K in H]: Value }
-  : never;
+type BuildNested<Key extends string, Value> =
+  SplitFirst<Key> extends [infer H extends string, infer T]
+    ? T extends string
+      ? { [K in H]: BuildNested<T, Value> }
+      : { [K in H]: Value }
+    : never;
 
-type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
-  k: infer I,
-) => void
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void
   ? I
   : never;
 
-type DeepMerge<T> = T extends object
-  ? { [K in keyof T]: DeepMerge<T[K]> }
-  : T;
+type DeepMerge<T> = T extends object ? { [K in keyof T]: DeepMerge<T[K]> } : T;
 
 export type NestedFromFlat<T extends Record<string, any>> = DeepMerge<
-  UnionToIntersection<
-    { [K in keyof T & string]: BuildNested<K, T[K]> }[keyof T & string]
-  >
+  UnionToIntersection<{ [K in keyof T & string]: BuildNested<K, T[K]> }[keyof T & string]>
 >;
 
 /**
@@ -203,10 +195,10 @@ export type NestedFromFlat<T extends Record<string, any>> = DeepMerge<
  * ```
  */
 export function createAppInvoke(basePath?: string): any;
-export function createAppInvoke<T extends Record<string, any>>(basePath?: string): NestedFromFlat<T>;
-export function createAppInvoke(
-  basePath = "/deco/invoke",
-): any {
+export function createAppInvoke<T extends Record<string, any>>(
+  basePath?: string,
+): NestedFromFlat<T>;
+export function createAppInvoke(basePath = "/deco/invoke"): any {
   function buildProxy(path: string[]): any {
     return new Proxy(
       Object.assign(async (props: any) => {
@@ -217,7 +209,10 @@ export function createAppInvoke(
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(props ?? {}),
           });
-          if (response.status === 404) { await response.body?.cancel(); continue; }
+          if (response.status === 404) {
+            await response.body?.cancel();
+            continue;
+          }
           if (!response.ok) {
             const error = await response.json().catch(() => ({ error: response.statusText }));
             throw new Error(
@@ -242,3 +237,24 @@ export function createAppInvoke(
 
   return buildProxy([]);
 }
+
+/**
+ * Default nested invoke proxy bound to `/deco/invoke`.
+ *
+ * Replaces site-level `~/runtime.ts` shims that wrap the same `createAppInvoke`
+ * call. Importing this singleton means no per-site boilerplate.
+ *
+ * @example
+ * ```ts
+ * import { invoke } from "@decocms/start/sdk/invoke";
+ *
+ * await invoke.vtex.actions.checkout.addItemsToCart({ orderFormId, orderItems });
+ * await invoke.site.loaders.Wishlist.getWishlist({});
+ * ```
+ *
+ * For a custom `basePath` or typed handlers, call `createAppInvoke()` directly:
+ * ```ts
+ * const invoke = createAppInvoke<Handlers>("/my/invoke");
+ * ```
+ */
+export const invoke = createAppInvoke();