@decocms/start 0.38.0 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
@@ -42,6 +42,7 @@
     "./sdk/createInvoke": "./src/sdk/createInvoke.ts",
     "./matchers/posthog": "./src/matchers/posthog.ts",
     "./apps/autoconfig": "./src/apps/autoconfig.ts",
+    "./sdk/setupApps": "./src/sdk/setupApps.ts",
     "./matchers/builtins": "./src/matchers/builtins.ts",
     "./types/widgets": "./src/types/widgets.ts",
     "./routes": "./src/routes/index.ts",

package/src/admin/index.ts

@@ -1,9 +1,11 @@
 export { corsHeaders, isAdminOrLocalhost, registerAdminOrigin, registerAdminOrigins } from "./cors";
 export { handleDecofileRead, handleDecofileReload } from "./decofile";
 export {
+  clearInvokeHandlers,
   handleInvoke,
   type InvokeAction,
   type InvokeLoader,
+  registerInvokeHandlers,
   setInvokeActions,
   setInvokeLoaders,
 } from "./invoke";

package/src/admin/invoke.ts

@@ -7,11 +7,21 @@
  * - FormData parsing for file uploads and form submissions
  * - `?select=field1,field2` to pick fields from the result
  * - Resolves __resolveType in batch payloads
+ *
+ * Handlers can write to `RequestContext.responseHeaders` to forward
+ * headers (e.g., Set-Cookie from VTEX checkout). The invoke endpoint
+ * copies those headers into the final HTTP Response.
  */
 
+import { RequestContext } from "../sdk/requestContext";
+
 export type InvokeLoader = (props: any, request: Request) => Promise<any>;
 export type InvokeAction = (props: any, request: Request) => Promise<any>;
 
+// Additive handler registry — registerInvokeHandlers() adds to this map.
+const handlerRegistry = new Map<string, InvokeLoader | InvokeAction>();
+
+// Legacy getter-based registries (backward compat for setInvokeLoaders/Actions).
 let getRegisteredLoaders: () => Record<string, InvokeLoader> = () => ({});
 let getRegisteredActions: () => Record<string, InvokeAction> = () => ({});
 
@@ -23,6 +33,29 @@ export function setInvokeActions(getter: () => Record<string, InvokeAction>) {
   getRegisteredActions = getter;
 }
 
+/**
+ * Additive handler registration — adds handlers without replacing existing ones.
+ * First registration wins: if a key already exists, it is NOT overwritten.
+ * Use this for automatic manifest-based registration from setupApps().
+ */
+export function registerInvokeHandlers(
+  handlers: Record<string, InvokeLoader | InvokeAction>,
+): void {
+  for (const [key, handler] of Object.entries(handlers)) {
+    if (!handlerRegistry.has(key)) {
+      handlerRegistry.set(key, handler);
+    }
+  }
+}
+
+/**
+ * Clear all registered invoke handlers.
+ * Called by setupApps() before re-registering on hot-reload.
+ */
+export function clearInvokeHandlers(): void {
+  handlerRegistry.clear();
+}
+
 const JSON_HEADERS = { "Content-Type": "application/json" } as const;
 
 const isDev =
@@ -100,6 +133,11 @@ async function parseBody(request: Request): Promise<any> {
 function findHandler(
   key: string,
 ): { handler: InvokeLoader | InvokeAction; type: "loader" | "action" } | null {
+  // 1. Check additive registry first (from registerInvokeHandlers / setupApps)
+  const registered = handlerRegistry.get(key);
+  if (registered) return { handler: registered, type: "action" };
+
+  // 2. Fall back to legacy getter-based registries
   const loaders = getRegisteredLoaders();
   if (loaders[key]) return { handler: loaders[key], type: "loader" };
 
@@ -126,15 +164,25 @@ export async function handleInvoke(request: Request): Promise<Response> {
 
     try {
       const result = await found.handler(body, request);
-      // Response passthrough: if the loader/action returns a Response object,
-      // forward it as-is (preserving headers like Set-Cookie). This matches
-      // deco-cx/deco's invokeToHttpResponse behavior where auth loaders return
-      // Response objects with Set-Cookie headers for HttpOnly cookies.
+      // Response passthrough: if the handler returns a Response object,
+      // forward it as-is (preserving headers like Set-Cookie).
       if (result instanceof Response) {
         return result;
       }
       const filtered = selectFields(result, select);
-      return new Response(JSON.stringify(filtered), { status: 200, headers: JSON_HEADERS });
+      const response = new Response(JSON.stringify(filtered), { status: 200, headers: JSON_HEADERS });
+
+      // Copy any headers that handlers wrote to RequestContext.responseHeaders
+      // (e.g., Set-Cookie from proxySetCookie). This mirrors deco-cx/deco's
+      // ctx.response.headers → HTTP Response forwarding.
+      const ctx = RequestContext.current;
+      if (ctx) {
+        for (const [key, value] of ctx.responseHeaders.entries()) {
+          response.headers.append(key, value);
+        }
+      }
+
+      return response;
     } catch (error) {
       return errorResponse((error as Error).message, 500, error);
     }

package/src/admin/setup.ts

@@ -8,7 +8,13 @@
  * import from "@decocms/start/admin" instead.
  */
 
-export { type InvokeAction, type InvokeLoader, setInvokeActions, setInvokeLoaders } from "./invoke";
+export {
+  type InvokeAction,
+  type InvokeLoader,
+  registerInvokeHandlers,
+  setInvokeActions,
+  setInvokeLoaders,
+} from "./invoke";
 export { setMetaData } from "./meta";
 export {
   type LoaderConfig,

package/src/apps/autoconfig.ts

@@ -1,9 +1,9 @@
 /**
- * Auto-configures known apps from CMS blocks.
+ * Auto-configures known apps from CMS blocks using AppModContract.
  *
- * Scans the decofile for known app block keys (e.g. "deco-resend") and:
- * 1. Configures the app client with CMS-provided credentials
- * 2. Registers invoke handlers so `invoke.app.actions.*` works via the proxy
+ * Scans the decofile for known app block keys (e.g. "deco-vtex", "deco-resend")
+ * and calls each app's `configure()` function from its mod.ts.
+ * Then delegates to `setupApps()` for invoke handler registration, middleware, etc.
  *
  * Usage in setup.ts:
  *   import { autoconfigApps } from "@decocms/start/apps/autoconfig";
@@ -11,62 +11,60 @@
  *   await autoconfigApps(generatedBlocks);
  */
 
-import { setInvokeActions, type InvokeAction } from "../admin/invoke";
 import { onChange } from "../cms/loader";
 import { resolveSecret } from "../sdk/crypto";
+import {
+	setupApps,
+	type AppDefinition,
+	type AppDefinitionWithHandlers,
+} from "../sdk/setupApps";
 
 // ---------------------------------------------------------------------------
-// Known app block keys → dynamic import + configure
+// Known app block keys → dynamic import of their mod.ts
 // ---------------------------------------------------------------------------
 
-interface AppAutoconfigurator {
-	/** Try to import, configure, and return invoke actions for this app */
-	(blockData: unknown): Promise<Record<string, InvokeAction>>;
-}
+const APP_MODS: Record<string, () => Promise<any>> = {
+	"deco-vtex": () => import("@decocms/apps/vtex/mod" as string),
+	"deco-shopify": () => import("@decocms/apps/shopify/mod" as string),
+	"deco-resend": () => import("@decocms/apps/resend/mod" as string),
+};
 
-const KNOWN_APPS: Record<string, AppAutoconfigurator> = {
-	"deco-resend": async (block: any): Promise<Record<string, InvokeAction>> => {
-		try {
-			const [resendClient, resendActions] = await Promise.all([
-				import("@decocms/apps/resend/client" as string),
-				import("@decocms/apps/resend/actions/send" as string),
-			]);
-			const { configureResend } = resendClient as { configureResend: (cfg: any) => void };
-			const { sendEmail } = resendActions as { sendEmail: (props: any) => Promise<any> };
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
 
-			const apiKey = await resolveSecret(block.apiKey, "RESEND_API_KEY");
-			if (!apiKey) {
-				console.warn(
-					"[autoconfig] deco-resend: no API key found." +
-					" Set DECO_CRYPTO_KEY to decrypt CMS secrets, or set RESEND_API_KEY as fallback.",
-				);
-				return {} as Record<string, InvokeAction>;
-			}
+async function configureAllApps(
+	blocks: Record<string, unknown>,
+): Promise<AppDefinitionWithHandlers[]> {
+	const apps: AppDefinitionWithHandlers[] = [];
 
-			configureResend({
-				apiKey,
-				emailFrom: block.emailFrom
-					? `${block.emailFrom.name || "Contact"} ${block.emailFrom.domain || "<onboarding@resend.dev>"}`
-					: undefined,
-				emailTo: block.emailTo,
-				subject: block.subject,
-			});
+	for (const [blockKey, importMod] of Object.entries(APP_MODS)) {
+		const block = blocks[blockKey];
+		if (!block) continue;
+
+		try {
+			const mod = await importMod();
+			if (typeof mod.configure !== "function") continue;
 
-			const handler: InvokeAction = async (props: any) => sendEmail(props);
-			return {
-				"resend/actions/emails/send": handler,
-				"resend/actions/emails/send.ts": handler,
+			const appDef: AppDefinition | null = await mod.configure(
+				block,
+				resolveSecret,
+			);
+			if (!appDef) continue;
+
+			// Attach explicit handlers from mod.ts (e.g. resend's pre-wrapped handlers)
+			const withHandlers: AppDefinitionWithHandlers = {
+				...appDef,
+				handlers: mod.handlers,
 			};
+			apps.push(withHandlers);
 		} catch {
-			// @decocms/apps not installed or doesn't have resend — skip
-			return {};
+			// App not installed or configure failed — skip silently
 		}
-	},
-};
+	}
 
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
+	return apps;
+}
 
 /**
  * Auto-configure apps from CMS blocks.
@@ -75,37 +73,17 @@ const KNOWN_APPS: Record<string, AppAutoconfigurator> = {
 export async function autoconfigApps(blocks: Record<string, unknown>) {
 	if (typeof document !== "undefined") return; // server-only
 
-	const actions: Record<string, InvokeAction> = {};
-
-	for (const [blockKey, configurator] of Object.entries(KNOWN_APPS)) {
-		const block = blocks[blockKey];
-		if (!block) continue;
-
-		try {
-			const appActions = await configurator(block);
-			Object.assign(actions, appActions);
-		} catch (e) {
-			console.warn(`[autoconfig] ${blockKey}:`, e);
-		}
-	}
-
-	if (Object.keys(actions).length > 0) {
-		setInvokeActions(() => ({ ...actions }));
+	const apps = await configureAllApps(blocks);
+	if (apps.length > 0) {
+		await setupApps(apps);
 	}
 
 	// Re-configure on admin hot-reload
 	onChange(async (newBlocks) => {
 		if (typeof document !== "undefined") return;
-		const updatedActions: Record<string, InvokeAction> = {};
-		for (const [blockKey, configurator] of Object.entries(KNOWN_APPS)) {
-			const block = newBlocks[blockKey];
-			if (!block) continue;
-			try {
-				Object.assign(updatedActions, await configurator(block));
-			} catch {}
-		}
-		if (Object.keys(updatedActions).length > 0) {
-			setInvokeActions(() => ({ ...updatedActions }));
+		const updatedApps = await configureAllApps(newBlocks);
+		if (updatedApps.length > 0) {
+			await setupApps(updatedApps);
 		}
 	});
 }

package/src/sdk/invoke.ts

@@ -1,21 +1,22 @@
 /**
- * Typed invoke proxy for client-side RPC to deco loaders/actions.
+ * Typed invoke proxies for client-side RPC to deco loaders/actions.
  *
- * Creates a Proxy object that maps loader keys to `POST /deco/invoke/:key` calls,
- * providing a type-safe, ergonomic API for client-side data fetching.
+ * Two flavors:
+ *
+ * 1. `createInvokeProxy<T>()` — flat keys (e.g. `invoke["vtex/loaders/productList.ts"](props)`)
+ * 2. `createAppInvoke<T>()` — nested keys (e.g. `invoke.vtex.actions.checkout.addItemsToCart(props)`)
+ *
+ * Both POST to `/deco/invoke/{key}` under the hood.
  *
  * @example
  * ```ts
- * // Define your loader registry type
- * type Loaders = {
- *   "vtex/loaders/intelligentSearch/productList.ts": (props: { query: string }) => Promise<Product[]>;
- *   "vtex/loaders/intelligentSearch/productDetailsPage.ts": (props: { slug: string }) => Promise<ProductDetailsPage>;
- * };
+ * // Flat proxy (legacy):
+ * const invoke = createInvokeProxy<Loaders>();
+ * await invoke["vtex/loaders/productList.ts"]({ query: "shoes" });
  *
- * const invoke = createInvokeProxy<Loaders>("/deco/invoke");
- *
- * // Type-safe calls:
- * const products = await invoke["vtex/loaders/intelligentSearch/productList.ts"]({ query: "shoes" });
+ * // Nested proxy (recommended):
+ * const invoke = createAppInvoke();
+ * await invoke.vtex.actions.checkout.addItemsToCart({ orderFormId, orderItems });
  * ```
  */
 
@@ -131,3 +132,113 @@ export function invokeQueryOptions<TResult = unknown>(
     gcTime: options?.gcTime,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Nested invoke proxy — createAppInvoke
+// ---------------------------------------------------------------------------
+
+/**
+ * Converts flat slash-separated keys into a nested object type.
+ *
+ * @example
+ * ```ts
+ * type Map = {
+ *   "vtex/actions/checkout/addItemsToCart": (props: CartInput) => Promise<OrderForm>;
+ *   "vtex/loaders/catalog/getProduct": (props: { slug: string }) => Promise<Product>;
+ * };
+ * type Nested = NestedFromFlat<Map>;
+ * // { vtex: { actions: { checkout: { addItemsToCart: (props: CartInput) => Promise<OrderForm> } } } }
+ * ```
+ */
+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 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;
+
+export type NestedFromFlat<T extends Record<string, any>> = DeepMerge<
+  UnionToIntersection<
+    { [K in keyof T & string]: BuildNested<K, T[K]> }[keyof T & string]
+  >
+>;
+
+/**
+ * Creates a typed nested invoke proxy.
+ *
+ * Each property access accumulates path segments. When called as a function,
+ * the segments are joined with "/" and POSTed to `/deco/invoke/{key}`.
+ * If the primary key returns 404, a `.ts` suffix variant is tried.
+ *
+ * @example
+ * ```ts
+ * import { createAppInvoke } from "@decocms/start/sdk/invoke";
+ *
+ * // Untyped (any):
+ * const invoke = createAppInvoke();
+ * await invoke.vtex.actions.checkout.addItemsToCart({ orderFormId, orderItems });
+ *
+ * // Typed (with handler map):
+ * type Handlers = {
+ *   "vtex/actions/checkout/addItemsToCart": (props: CartInput) => Promise<OrderForm>;
+ * };
+ * const invoke = createAppInvoke<Handlers>();
+ * await invoke.vtex.actions.checkout.addItemsToCart({ orderFormId, orderItems });
+ * ```
+ */
+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 {
+  function buildProxy(path: string[]): any {
+    return new Proxy(
+      Object.assign(async (props: any) => {
+        const key = path.join("/");
+        for (const k of [key, `${key}.ts`]) {
+          const response = await fetch(`${basePath}/${k}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(props ?? {}),
+          });
+          if (response.status === 404) { await response.body?.cancel(); continue; }
+          if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: response.statusText }));
+            throw new Error(
+              `invoke(${k}) failed (${response.status}): ${(error as any).error || response.statusText}`,
+            );
+          }
+          return response.json();
+        }
+        throw new Error(`invoke(${key}) failed: handler not found`);
+      }, {}),
+      {
+        get(_target: any, prop: string | symbol) {
+          if (typeof prop === "symbol") return undefined;
+          if (prop === "then" || prop === "catch" || prop === "finally") {
+            return undefined;
+          }
+          return buildProxy([...path, prop]);
+        },
+      },
+    );
+  }
+
+  return buildProxy([]);
+}

package/src/sdk/requestContext.ts

@@ -44,6 +44,17 @@ export interface RequestContextData {
   _isBot?: boolean;
   /** Arbitrary bag for middleware to attach custom data. */
   bag: Map<string, unknown>;
+  /**
+   * Outgoing response headers that handlers can write to.
+   * Invoke handlers (actions/loaders) use this to forward Set-Cookie
+   * and other headers from upstream APIs (e.g., VTEX checkout).
+   * The invoke HTTP handler copies these into the final Response.
+   *
+   * This mirrors deco-cx/deco's `ctx.response.headers` pattern where
+   * `proxySetCookie(apiResponse.headers, ctx.response.headers)` forwards
+   * cookies transparently.
+   */
+  responseHeaders: Headers;
 }
 
 // -------------------------------------------------------------------------
@@ -87,6 +98,7 @@ export const RequestContext = {
       signal: controller.signal,
       startedAt: Date.now(),
       bag: new Map(),
+      responseHeaders: new Headers(),
     };
 
     return storage.run(ctx, fn);
@@ -169,6 +181,17 @@ export const RequestContext = {
     });
   },
 
+  /**
+   * Outgoing response headers. Handlers write here; the invoke endpoint
+   * copies them into the HTTP Response (mirroring ctx.response.headers
+   * from deco-cx/deco).
+   */
+  get responseHeaders(): Headers {
+    const ctx = storage.getStore();
+    if (!ctx) throw new Error("RequestContext.responseHeaders accessed outside a request scope");
+    return ctx.responseHeaders;
+  },
+
   /**
    * Get/set arbitrary values in the request bag.
    * Useful for middleware to pass data to loaders.
@@ -182,4 +205,23 @@ export const RequestContext = {
     const ctx = storage.getStore();
     ctx?.bag.set(key, value);
   },
+
+  /**
+   * Get an app's state from the request bag.
+   * Apps register their state via `setupApps()` which injects it
+   * into the bag as `app:{name}:state` before each request.
+   *
+   * @example
+   * ```ts
+   * import { RequestContext } from "@decocms/start/sdk/requestContext";
+   * import type { VtexState } from "@decocms/apps/vtex/mod";
+   *
+   * const vtex = RequestContext.getAppState<VtexState>("vtex");
+   * if (vtex) console.log(vtex.config.account);
+   * ```
+   */
+  getAppState<T>(appName: string): T | undefined {
+    const ctx = storage.getStore();
+    return ctx?.bag.get(`app:${appName}:state`) as T | undefined;
+  },
 };

package/src/sdk/setupApps.ts

@@ -0,0 +1,211 @@
+/**
+ * App system integration pipeline.
+ *
+ * Consumes AppDefinition objects from @decocms/apps and automates:
+ * 1. Invoke handler registration (from manifest + explicit handlers)
+ * 2. Section registration (when manifest.sections is available)
+ * 3. App middleware registration (with state injection into RequestContext)
+ *
+ * @example
+ * ```ts
+ * import { setupApps } from "@decocms/start/sdk/setupApps";
+ * import * as vtexApp from "@decocms/apps/vtex/mod";
+ * import * as resendApp from "@decocms/apps/resend/mod";
+ *
+ * const vtex = await vtexApp.configure(blocks["deco-vtex"], resolveSecret);
+ * const resend = await resendApp.configure(blocks["deco-resend"], resolveSecret);
+ *
+ * await setupApps([vtex, resend].filter(Boolean));
+ * ```
+ */
+
+import { clearInvokeHandlers, registerInvokeHandlers } from "../admin/invoke";
+import { registerSections } from "../cms/registry";
+import { RequestContext } from "./requestContext";
+
+// ---------------------------------------------------------------------------
+// Types — mirrors @decocms/apps/commerce/app-types without importing it
+// ---------------------------------------------------------------------------
+
+export interface AppManifest {
+  name: string;
+  loaders: Record<string, Record<string, unknown>>;
+  actions: Record<string, Record<string, unknown>>;
+  sections?: Record<string, () => Promise<any>>;
+}
+
+export interface AppMiddleware {
+  (request: Request, next: () => Promise<Response>): Promise<Response>;
+}
+
+export interface AppDefinition<TState = unknown> {
+  name: string;
+  manifest: AppManifest;
+  state: TState;
+  middleware?: AppMiddleware;
+  dependencies?: AppDefinition[];
+}
+
+/**
+ * Extended definition with optional explicit handlers.
+ * autoconfigApps() attaches mod.handlers here before calling setupApps().
+ */
+export interface AppDefinitionWithHandlers<TState = unknown>
+  extends AppDefinition<TState> {
+  /** Pre-wrapped handlers from the app's mod.ts (e.g. unwrapped VTEX actions). */
+  handlers?: Record<string, (props: any, request: Request) => Promise<any>>;
+}
+
+// ---------------------------------------------------------------------------
+// App middleware registry
+// ---------------------------------------------------------------------------
+
+/** Per-app state entries — injected into RequestContext.bag on every request. */
+const appStates: Array<{ name: string; state: unknown }> = [];
+
+const appMiddlewares: Array<{
+  name: string;
+  middleware: AppMiddleware;
+}> = [];
+
+function registerAppState(name: string, state: unknown) {
+  appStates.push({ name, state });
+}
+
+export function registerAppMiddleware(
+  name: string,
+  mw: AppMiddleware,
+) {
+  appMiddlewares.push({ name, middleware: mw });
+}
+
+/**
+ * Clear all registrations. Called before re-running setupApps()
+ * on admin hot-reload to prevent duplicate middleware/state entries.
+ */
+function clearRegistrations() {
+  appStates.length = 0;
+  appMiddlewares.length = 0;
+}
+
+/**
+ * Returns a chained middleware that runs all registered app middlewares.
+ * The site wires this into its own createMiddleware() chain.
+ *
+ * Before running app middlewares, all app states are injected into
+ * RequestContext.bag so loaders can access them via getAppState().
+ *
+ * Returns undefined if no app states or middlewares were registered.
+ */
+export function getAppMiddleware(): AppMiddleware | undefined {
+  if (appStates.length === 0 && appMiddlewares.length === 0) return undefined;
+
+  return async (request, next) => {
+    // Inject all app states into RequestContext bag
+    for (const { name, state } of appStates) {
+      RequestContext.setBag(`app:${name}:state`, state);
+    }
+
+    // Chain app middlewares (first registered runs outermost)
+    if (appMiddlewares.length === 0) return next();
+    const run = async (i: number): Promise<Response> => {
+      if (i >= appMiddlewares.length) return next();
+      return appMiddlewares[i].middleware(request, () => run(i + 1));
+    };
+    return run(0);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Dependency flattening
+// ---------------------------------------------------------------------------
+
+/**
+ * Topological sort: dependencies before parents.
+ * Combined with first-wins registration in registerInvokeHandlers,
+ * this means parent apps can override handlers from their dependencies
+ * by providing explicit `handlers` (registered before manifest flatten).
+ */
+function flattenDependencies(apps: AppDefinition[]): AppDefinition[] {
+  const seen = new Set<string>();
+  const result: AppDefinition[] = [];
+
+  function visit(app: AppDefinition) {
+    if (seen.has(app.name)) return;
+    seen.add(app.name);
+    if (app.dependencies) {
+      for (const dep of app.dependencies) visit(dep);
+    }
+    result.push(app);
+  }
+
+  for (const app of apps) visit(app);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Main pipeline
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialize apps from their AppDefinitions.
+ *
+ * Call once in setup.ts after configuring apps via their mod.configure().
+ * Handles: invoke handler registration, section registration, middleware setup.
+ */
+export async function setupApps(
+  apps: Array<AppDefinitionWithHandlers | AppDefinition>,
+): Promise<void> {
+  if (typeof document !== "undefined") return; // server-only
+
+  // Clear previous registrations (safe for hot-reload via onChange)
+  clearRegistrations();
+  clearInvokeHandlers();
+
+  for (const app of flattenDependencies(apps as AppDefinition[])) {
+    const appWithHandlers = app as AppDefinitionWithHandlers;
+
+    // 1. Register explicit handlers (pre-unwrapped by the app, e.g. resend)
+    if (appWithHandlers.handlers) {
+      registerInvokeHandlers(appWithHandlers.handlers);
+    }
+
+    // 2. Flatten manifest modules → individual invoke handlers
+    // manifest.actions["vtex/actions/checkout"] = { getOrCreateCart, addItemsToCart, ... }
+    // → register "vtex/actions/checkout/getOrCreateCart" as handler
+    for (const category of ["loaders", "actions"] as const) {
+      const modules = app.manifest[category];
+      if (!modules) continue;
+
+      for (const [moduleKey, moduleExports] of Object.entries(modules)) {
+        for (const [fnName, fn] of Object.entries(
+          moduleExports as Record<string, unknown>,
+        )) {
+          if (typeof fn !== "function") continue;
+          const key = `${moduleKey}/${fnName}`;
+          const handler = (props: any, req: Request) =>
+            (fn as Function)(props, req);
+          registerInvokeHandlers({
+            [key]: handler,
+            [`${key}.ts`]: handler,
+          });
+        }
+      }
+    }
+
+    // 3. Register sections from manifest (future — when apps export sections)
+    if (app.manifest.sections) {
+      registerSections(
+        app.manifest.sections as Record<string, () => Promise<any>>,
+      );
+    }
+
+    // 4. Always register app state (so getAppState() works for all apps)
+    registerAppState(app.name, app.state);
+
+    // 5. Register middleware (optional — not all apps have middleware)
+    if (app.middleware) {
+      registerAppMiddleware(app.name, app.middleware);
+    }
+  }
+}

package/src/sdk/workerEntry.ts

@@ -36,6 +36,7 @@ import { buildHtmlShell } from "./htmlShell";
 import { cleanPathForCacheKey } from "./urlUtils";
 import { isMobileUA } from "./useDevice";
 import { getRenderShellConfig } from "../admin/setup";
+import { RequestContext } from "./requestContext";
 
 /**
  * Append Link preload headers for CSS and fonts so the browser starts
@@ -653,6 +654,10 @@ export function createDecoWorkerEntry(
       env: Record<string, unknown>,
       ctx: WorkerExecutionContext,
     ): Promise<Response> {
+      // Wrap the entire request in a RequestContext so that all code
+      // in the call stack (loaders, invoke handlers, vtexFetchWithCookies)
+      // can access the request and write response headers.
+      return RequestContext.run(request, async () => {
       const url = new URL(request.url);
 
       // Admin routes (/_meta, /.decofile, /live/previews) — always handled first
@@ -879,6 +884,7 @@ export function createDecoWorkerEntry(
       // the stream in Workers runtime, causing Error 1101.
       storeInCache(origin);
       return dressResponse(origin, "MISS");
+      }); // end RequestContext.run()
     },
   };
 }