@decocms/start 2.3.0 → 2.4.1

package/package.json

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

package/src/cms/sectionLoaders.test.ts

@@ -1,11 +1,11 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ResolvedSection } from "./resolve";
 import {
   registerCacheableSections,
   registerLayoutSections,
   registerSectionLoader,
   runSingleSectionLoader,
 } from "./sectionLoaders";
-import type { ResolvedSection } from "./resolve";
 
 const G = globalThis as any;
 
@@ -15,10 +15,7 @@ beforeEach(() => {
   G.__deco.cacheableSections.clear();
 });
 
-const makeSection = (
-  component: string,
-  props: Record<string, unknown> = {},
-): ResolvedSection => ({
+const makeSection = (component: string, props: Record<string, unknown> = {}): ResolvedSection => ({
   component,
   props,
   key: component,
@@ -75,10 +72,7 @@ describe("runSingleSectionLoader — page context injection", () => {
 
   it("returns section unchanged when no loader is registered", async () => {
     const section = makeSection("site/sections/NoLoader.tsx", { foo: 1 });
-    const result = await runSingleSectionLoader(
-      section,
-      new Request("https://store.com/"),
-    );
+    const result = await runSingleSectionLoader(section, new Request("https://store.com/"));
     expect(result).toBe(section);
   });
 });
@@ -135,10 +129,145 @@ describe("runSingleSectionLoader — error handling", () => {
     registerSectionLoader("site/sections/Boom.tsx", loader);
 
     const section = makeSection("site/sections/Boom.tsx", { x: 1 });
-    const result = await runSingleSectionLoader(
-      section,
-      new Request("https://store.com/"),
-    );
+    const result = await runSingleSectionLoader(section, new Request("https://store.com/"));
     expect(result).toEqual(section);
   });
 });
+
+describe("runSingleSectionLoader — nested section recursion", () => {
+  it("runs the loader of a nested section in props", async () => {
+    const childLoader = vi.fn(async (props: Record<string, unknown>) => ({
+      ...props,
+      enriched: true,
+    }));
+    registerSectionLoader("site/sections/CategoryBanner.tsx", childLoader);
+
+    // Parent has no own loader, only a nested section in props
+    const parent = makeSection("site/sections/BackgroundWrapper.tsx", {
+      child: {
+        Component: "site/sections/CategoryBanner.tsx",
+        props: { matcher: "/foo" },
+      },
+    });
+
+    const result = await runSingleSectionLoader(parent, new Request("https://store.com/foo"));
+
+    expect(childLoader).toHaveBeenCalledTimes(1);
+    expect(result.props).toEqual({
+      child: {
+        Component: "site/sections/CategoryBanner.tsx",
+        props: {
+          matcher: "/foo",
+          enriched: true,
+          // page context is injected for nested sections too
+          __pageUrl: "https://store.com/foo",
+          __pagePath: "/foo",
+        },
+      },
+    });
+  });
+
+  it("runs nested loaders in arrays (e.g. sections: Section[])", async () => {
+    const banner = vi.fn(async (props: any) => ({ ...props, ranBanner: true }));
+    const shelf = vi.fn(async (props: any) => ({ ...props, ranShelf: true }));
+    registerSectionLoader("site/sections/Banner.tsx", banner);
+    registerSectionLoader("site/sections/Shelf.tsx", shelf);
+
+    const parent = makeSection("site/sections/Wrapper.tsx", {
+      sections: [
+        { Component: "site/sections/Banner.tsx", props: { id: 1 } },
+        { Component: "site/sections/Shelf.tsx", props: { id: 2 } },
+      ],
+    });
+
+    const result = await runSingleSectionLoader(parent, new Request("https://store.com/"));
+
+    expect(banner).toHaveBeenCalledTimes(1);
+    expect(shelf).toHaveBeenCalledTimes(1);
+    const sections = (result.props as any).sections;
+    expect(sections[0].props).toMatchObject({ id: 1, ranBanner: true });
+    expect(sections[1].props).toMatchObject({ id: 2, ranShelf: true });
+  });
+
+  it("returns same props reference when no nested sections (zero-alloc leaf path)", async () => {
+    const loader = vi.fn(async (props: Record<string, unknown>) => props);
+    registerSectionLoader("site/sections/Leaf.tsx", loader);
+
+    const props = { foo: "bar" };
+    const section = makeSection("site/sections/Leaf.tsx", props);
+
+    const result = await runSingleSectionLoader(section, new Request("https://store.com/"));
+
+    // Loader returned the SAME props ref → enrichNestedSections must also
+    // return the same ref → no { ...result, props } wrapping happens
+    expect(result.props).toMatchObject({
+      foo: "bar",
+      __pageUrl: "https://store.com/",
+      __pagePath: "/",
+    });
+  });
+
+  it("recurses into deeply nested sections (wrapper inside wrapper)", async () => {
+    const inner = vi.fn(async (props: any) => ({ ...props, deep: true }));
+    registerSectionLoader("site/sections/Inner.tsx", inner);
+
+    const parent = makeSection("site/sections/Outer.tsx", {
+      child: {
+        Component: "site/sections/MidWrapper.tsx",
+        props: {
+          grandchild: {
+            Component: "site/sections/Inner.tsx",
+            props: { tag: "deep" },
+          },
+        },
+      },
+    });
+
+    const result = await runSingleSectionLoader(parent, new Request("https://store.com/"));
+
+    expect(inner).toHaveBeenCalledTimes(1);
+    const grandchild = (result.props as any).child.props.grandchild;
+    expect(grandchild.props).toMatchObject({ tag: "deep", deep: true });
+  });
+
+  it("ignores nested objects that do not look like sections", async () => {
+    const loader = vi.fn(async (props: Record<string, unknown>) => props);
+    registerSectionLoader("site/sections/Leaf.tsx", loader);
+
+    const section = makeSection("site/sections/Leaf.tsx", {
+      // Plain config object, not a section. Has `Component: string` but
+      // missing the `props` field — must NOT be treated as a nested section.
+      config: { Component: "ButtonStyle", color: "red" },
+    });
+
+    const result = await runSingleSectionLoader(section, new Request("https://store.com/"));
+
+    expect(loader).toHaveBeenCalledTimes(1);
+    expect((result.props as any).config).toEqual({
+      Component: "ButtonStyle",
+      color: "red",
+    });
+  });
+
+  it("runs nested loaders even when parent has no own loader", async () => {
+    const childLoader = vi.fn(async (props: any) => ({ ...props, ran: true }));
+    registerSectionLoader("site/sections/Child.tsx", childLoader);
+
+    // Parent has no entry in registry — but it has a nested section in props
+    // (typical of a pure layout container that just renders children).
+    const parent = makeSection("site/sections/UnregisteredLayout.tsx", {
+      child: {
+        Component: "site/sections/Child.tsx",
+        props: { foo: "bar" },
+      },
+    });
+
+    const result = await runSingleSectionLoader(parent, new Request("https://store.com/"));
+
+    expect(childLoader).toHaveBeenCalledTimes(1);
+    expect((result.props as any).child.props).toMatchObject({
+      foo: "bar",
+      ran: true,
+    });
+  });
+});

package/src/cms/sectionLoaders.ts

@@ -34,7 +34,9 @@ interface CacheableSectionConfig {
   maxAge: number;
 }
 
-export type CacheableSectionInput = CacheableSectionConfig | import("../sdk/cacheHeaders").CacheProfileName;
+export type CacheableSectionInput =
+  | CacheableSectionConfig
+  | import("../sdk/cacheHeaders").CacheProfileName;
 
 function resolveSectionCacheConfig(input: CacheableSectionInput): CacheableSectionConfig {
   if (typeof input === "string") {
@@ -255,10 +257,7 @@ export async function runSectionLoaders(
   if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
     for (const s of sections) {
       const key = s.component.toLowerCase();
-      if (
-        (key.includes("header") || key.includes("footer")) &&
-        !layoutSections.has(s.component)
-      ) {
+      if ((key.includes("header") || key.includes("footer")) && !layoutSections.has(s.component)) {
         console.warn(
           `[SectionLoaders] "${s.component}" looks like a layout section but is not in registerLayoutSections(). ` +
             `Add it to registerLayoutSections() in setup.ts for consistent caching across navigations.`,
@@ -318,47 +317,180 @@ function withPageContext(loader: SectionLoaderFn): SectionLoaderFn {
  * 1. Layout sections (Header/Footer) — 5min TTL + in-flight dedup
  * 2. Cacheable sections (ProductShelf, FAQ) — SWR with configurable maxAge
  * 3. Regular sections — no cache, always fresh
+ *
+ * After the section's own loader runs, recursively runs loaders for any
+ * nested sections found in its resolved props (e.g. wrapper sections with
+ * a `sections: Section[]` prop). This eliminates the need for sites to
+ * manually walk + invoke `runSingleSectionLoader` on children.
  */
 export async function runSingleSectionLoader(
   section: ResolvedSection,
   request: Request,
 ): Promise<ResolvedSection> {
   const loader = loaderRegistry.get(section.component);
-  if (!loader) return section;
-
-  // Wrap the loader so __pageUrl/__pagePath are injected at the call site.
-  // Cache keys (component name for layout, component+propsHash for cacheable)
-  // are computed from the *original* section.props — keeping cache entries
-  // URL-agnostic and shared across pages.
-  const wrapped = withPageContext(loader);
-
-  if (layoutSections.has(section.component)) {
-    try {
-      return await resolveLayoutSection(section, wrapped, request);
-    } catch (error) {
-      console.error(`[SectionLoader] Error in layout "${section.component}":`, error);
-      return section;
+
+  let result: ResolvedSection;
+
+  if (!loader) {
+    // No own-loader, but the section may still contain nested sections in
+    // its props (CMS-resolved children) that need their loaders run.
+    result = section;
+  } else {
+    // Wrap the loader so __pageUrl/__pagePath are injected at the call site.
+    // Cache keys (component name for layout, component+propsHash for cacheable)
+    // are computed from the *original* section.props — keeping cache entries
+    // URL-agnostic and shared across pages.
+    const wrapped = withPageContext(loader);
+
+    if (layoutSections.has(section.component)) {
+      try {
+        result = await resolveLayoutSection(section, wrapped, request);
+      } catch (error) {
+        console.error(`[SectionLoader] Error in layout "${section.component}":`, error);
+        result = section;
+      }
+    } else {
+      const cacheConfig = cacheableSections.get(section.component);
+      if (cacheConfig) {
+        try {
+          result = await runCacheableSectionLoader(section, wrapped, request, cacheConfig);
+        } catch (error) {
+          console.error(`[SectionLoader] Error in cacheable "${section.component}":`, error);
+          result = section;
+        }
+      } else {
+        try {
+          const enrichedProps = await wrapped(section.props as Record<string, unknown>, request);
+          result = { ...section, props: enrichedProps };
+        } catch (error) {
+          console.error(`[SectionLoader] Error in "${section.component}":`, error);
+          result = section;
+        }
+      }
     }
   }
 
-  const cacheConfig = cacheableSections.get(section.component);
-  if (cacheConfig) {
-    try {
-      return await runCacheableSectionLoader(section, wrapped, request, cacheConfig);
-    } catch (error) {
-      console.error(`[SectionLoader] Error in cacheable "${section.component}":`, error);
-      return section;
+  // Recurse into nested sections AFTER the parent's loader/cache lookup so
+  // child sections keep their own cache TTL independent from the parent's.
+  // For layout/cacheable parents, this means a 5-min layout cache hit still
+  // re-evaluates child sections (whose own caches are usually shorter, e.g.
+  // ProductShelf 60s). For leaf sections, `enrichNestedSections` returns
+  // the same reference (no allocation, no extra work).
+  const props = result.props as Record<string, unknown> | undefined;
+  if (props && typeof props === "object") {
+    const enrichedProps = await enrichNestedSections(props, request);
+    if (enrichedProps !== props) {
+      return { ...result, props: enrichedProps };
     }
   }
+  return result;
+}
 
-  try {
-    const enrichedProps = await wrapped(
-      section.props as Record<string, unknown>,
-      request,
-    );
-    return { ...section, props: enrichedProps };
-  } catch (error) {
-    console.error(`[SectionLoader] Error in "${section.component}":`, error);
-    return section;
+// ---------------------------------------------------------------------------
+// Nested section loader support
+// ---------------------------------------------------------------------------
+
+/**
+ * Type guard: matches the shape produced by `normalizeNestedSections` in
+ * resolve.ts — `{ Component: string, props: object }`. This is how the CMS
+ * resolver represents nested sections (children of wrapper sections).
+ *
+ * Note: the `Component` key uses capital C to match the runtime renderer's
+ * convention (mirrors deco-cx/deco's Fresh API). Not to be confused with
+ * the lowercase `component` on `ResolvedSection`.
+ */
+function isNestedSection(
+  value: unknown,
+): value is { Component: string; props: Record<string, unknown> } {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.Component === "string" &&
+    obj.props != null &&
+    typeof obj.props === "object" &&
+    !Array.isArray(obj.props)
+  );
+}
+
+/**
+ * Walk a props object and run section loaders for any nested sections.
+ * Handles direct child sections AND arrays of sections (e.g.
+ * `sections: Section[]`, `slides: Slide[]`).
+ *
+ * Returns the same reference if nothing changed — so leaf sections (the
+ * vast majority) incur zero allocation overhead.
+ *
+ * Concurrency: all nested loader calls run in parallel via Promise.all.
+ */
+async function enrichNestedSections(
+  props: Record<string, unknown>,
+  request: Request,
+): Promise<Record<string, unknown>> {
+  type Pending = {
+    key: string;
+    index?: number;
+    promise: Promise<ResolvedSection>;
+  };
+  const pending: Pending[] = [];
+
+  for (const [key, value] of Object.entries(props)) {
+    if (isNestedSection(value)) {
+      pending.push({
+        key,
+        promise: runSingleSectionLoader(
+          {
+            component: value.Component,
+            props: value.props,
+            key: value.Component,
+          } as ResolvedSection,
+          request,
+        ),
+      });
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        const item = value[i];
+        if (isNestedSection(item)) {
+          pending.push({
+            key,
+            index: i,
+            promise: runSingleSectionLoader(
+              {
+                component: item.Component,
+                props: item.props,
+                key: item.Component,
+              } as ResolvedSection,
+              request,
+            ),
+          });
+        }
+      }
+    }
   }
+
+  if (pending.length === 0) return props;
+
+  const results = await Promise.all(pending.map((p) => p.promise));
+  const updated: Record<string, unknown> = { ...props };
+
+  for (let i = 0; i < pending.length; i++) {
+    const { key, index } = pending[i];
+    const enriched = results[i];
+    const nestedValue = { Component: enriched.component, props: enriched.props };
+
+    if (index != null) {
+      // Array item — clone the array on first mutation for this key
+      const current = updated[key];
+      if (current === props[key]) {
+        updated[key] = [...(current as unknown[])];
+      }
+      (updated[key] as unknown[])[index] = nestedValue;
+    } else {
+      updated[key] = nestedValue;
+    }
+  }
+
+  return updated;
 }

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();