@decocms/start 6.2.0 → 6.3.0

package/.agents/skills/deco-migrate-script/SKILL.md

@@ -293,9 +293,10 @@ Generates `MIGRATION_REPORT.md` with:
 ### Phase 7: Bootstrap
 
 Runs automatically after all phases (skipped in `--dry-run`):
-1. `npm install` (or `bun install`)
-2. `npx tsx node_modules/@decocms/start/scripts/generate-blocks.ts`
-3. `npx tsr generate`
+1. `bun install`
+2. `bunx tsx node_modules/@decocms/start/scripts/generate-blocks.ts`
+3. `bunx tsx node_modules/@decocms/start/scripts/generate-invoke.ts` — emits `src/server/invoke.gen.ts` (top-level `createServerFn` declarations for every VTEX action, plus the `forwardResponseCookies()` Set-Cookie bridge). Without this step the site falls back to the `/deco/invoke/...` proxy and the cart breaks at `/checkout` after addItemToCart. See `.cursor/skills/deco-server-functions-invoke/troubleshooting.md` ("Cart 'forgets' items between requests") for the failure mode.
+4. `bunx tsr generate`
 
 ### Phase 8: Compile
 

package/.cursor/skills/deco-apps-vtex-porting/cookie-auth-patterns.md

@@ -31,6 +31,19 @@ export async function vtexFetchWithCookies<T>(
 
 Use in: `checkout.ts`, `auth.ts`, `session.ts` (create/edit).
 
+### Pitfall: never copy with `Headers.entries()` or `forEach`
+
+When a caller pushes the captured cookies onto the request scope's response headers (e.g. `RequestContext.responseHeaders.append("set-cookie", c)`), the eventual HTTP-response bridge must read them back with `Headers.getSetCookie()`. **Do not** iterate `headers.entries()` (or `forEach`) and re-append, because both collapse multiple `Set-Cookie` values into a single comma-joined string, which browsers silently discard. The result: the cart appears empty after addItemToCart even though the action returned an OrderForm with items.
+
+Two bridges where this rule applies in a TanStack Start site:
+
+- `src/server/invoke.gen.ts` — the auto-generated `forwardResponseCookies()` already uses `getSetCookie()`. Re-run `bunx tsx node_modules/@decocms/start/scripts/generate-invoke.ts` if the file is missing or stale.
+- `@decocms/start/src/admin/invoke.ts` — `forwardCtxHeadersTo()` does the same for the `/deco/invoke/...` HTTP path. Versions ≥ 5.0.0 ship the fix.
+
+### Client-side `setOrderFormIdCookie` is defense-in-depth, not the fix
+
+Some migrated `useCart` hooks (e.g. miess-01-tanstack) manually call `document.cookie = "checkout.vtex.com__orderFormId=..."` after each cart action. That only patches one cookie — `segment`, `sc`, `vtex_session` etc. are still dropped. Keep the workaround if you like (cheap, idempotent), but the real fix is the two server-side bridges above. Once both are in place, the manual cookie write can be removed without regressing the cart.
+
 ## buildAuthCookieHeader
 
 VTEX IO GraphQL at `{account}.myvtex.com` requires both cookie names:

package/.cursor/skills/deco-apps-vtex-review/SKILL.md

@@ -63,6 +63,21 @@ const result = await vtexFetchWithCookies<OrderForm>(url, opts);
 
 **Where NOT needed**: Read-only loaders, GraphQL queries.
 
+**Server→browser bridge** — the cookies that `vtexFetchWithCookies` captures must be forwarded onto the outgoing HTTP response, or the browser never sees them and the cart appears empty on the next request. There are two bridge points in a TanStack Start site, and both must be wired:
+
+1. **`src/server/invoke.gen.ts`** (TanStack RPC path). Generated by `bunx tsx node_modules/@decocms/start/scripts/generate-invoke.ts`. Audit:
+   - File exists?
+   - Contains `function forwardResponseCookies()`?
+   - Every action handler calls `forwardResponseCookies()` after the `await`?
+
+   If any answer is "no", regenerate with the script above. Then make sure `useCart`, `useUser`, `useWishlist` import `invoke` from `~/server/invoke.gen` (or a barrel that re-exports it), not from the proxy `~/runtime.ts`.
+
+2. **`@decocms/start/src/admin/invoke.ts`** (`/deco/invoke/...` HTTP path). The framework's single + batch invoke handlers must use `Headers.getSetCookie()` (not `entries()`!) when copying `RequestContext.responseHeaders` onto the response. Pin to a version ≥ 5.0.0 that ships `forwardCtxHeadersTo`.
+
+The historical failure mode: a `for…of headers.entries()` loop collapsed N `Set-Cookie` values into one comma-joined string, which browsers silently discard. Every VTEX cart action returns 3–5 cookies (`checkout.vtex.com__orderFormId`, `segment`, `sc`, `vtex_session`…), so even one collapse breaks the entire cart flow.
+
+**Quick diagnosis**: Add an item, watch DevTools → Network → the cart-action response should have **multiple** `Set-Cookie:` rows, not one comma-joined line.
+
 ### 2. Auth Cookie Headers
 
 All authenticated VTEX IO GraphQL calls need both cookie variants:

package/.cursor/skills/deco-server-functions-invoke/troubleshooting.md

@@ -1,5 +1,27 @@
 # Troubleshooting
 
+## Cart "forgets" items between requests / /checkout opens empty after addItemToCart
+
+**Symptom**: `invoke.vtex.actions.addItemsToCart(...)` succeeds (returns an `OrderForm` with items), but the next page load — or clicking the cart icon — shows an empty cart, and `/checkout` lands on a fresh empty order. Sometimes the orderFormId is different from the one just returned.
+
+**Root cause**: The VTEX cart cookies (`checkout.vtex.com__orderFormId`, `segment`, `sc`, `vtex_session`) never reach the browser because somewhere in the chain, multiple `Set-Cookie` headers got collapsed into a single comma-joined string. Browsers silently discard malformed `Set-Cookie` values, so every subsequent request hits VTEX without authentication and gets a new empty orderForm.
+
+**Two places this can break**:
+
+1. **`src/server/invoke.gen.ts` missing or stale**. This is the TanStack RPC path. Each action must call `forwardResponseCookies()` after awaiting the underlying VTEX call. The helper uses `Headers.getSetCookie()` (not `entries()`!) to read the un-collapsed list and writes each value to TanStack's response via `setResponseHeader("set-cookie", [...])`. If the file doesn't exist, the site falls back to the `/deco/invoke/...` proxy.
+
+2. **`/deco/invoke/...` HTTP proxy** (`~/runtime.ts` pattern). The framework's admin handler (`@decocms/start/src/admin/invoke.ts`) used to iterate `RequestContext.responseHeaders.entries()` which collapses Set-Cookie. Fixed in @decocms/start ≥ 5.0.0 by switching to `getSetCookie()` + a `forwardCtxHeadersTo()` helper applied on both single and batch paths.
+
+**Diagnosis**: Open DevTools → Network → response to the cart action. You should see **multiple distinct** `Set-Cookie:` rows. If you see a single `Set-Cookie: foo=1, bar=2; Path=/, baz=3` line, that's the collapse bug.
+
+**Fix**:
+1. Upgrade `@decocms/start` to the version with `forwardCtxHeadersTo` in `src/admin/invoke.ts` (search the file — both single and batch handlers should call it).
+2. Run `bunx tsx node_modules/@decocms/start/scripts/generate-invoke.ts` to regenerate `src/server/invoke.gen.ts`. Verify it has `function forwardResponseCookies()` and that every emitted handler calls it.
+3. Make sure `useCart` (and other VTEX hooks) imports `invoke` from `~/server/invoke.gen` (or a barrel re-export of it), not from `~/runtime`.
+4. The migration script (`scripts/migrate.ts` bootstrap) runs `generate-invoke.ts` automatically on freshly-migrated sites — if a site was migrated before that, run the generator manually.
+
+**Client-side workaround** (defense-in-depth, removable): some sites manually `document.cookie = "checkout.vtex.com__orderFormId=..."` inside `useCart`. That only patches one cookie of many. With the server-side fix in place, the workaround is harmless but no longer load-bearing — see `~/conductor/workspaces/miess-01-tanstack/newport-beach/src/hooks/useCart.ts` for an example.
+
 ## CORS Error on Add to Cart / Checkout
 
 **Symptom**: Browser console shows CORS error when calling VTEX API directly.

package/package.json

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

package/scripts/migrate/post-cleanup/rules.ts

@@ -1578,12 +1578,101 @@ const rulePackageManagerMissing: Rule = {
   },
 };
 
+/* ------------------------------------------------------------------ */
+/* Rule N — `vtex-proxy-handler-missing` — worker-entry without proxy */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Every VTEX storefront on @decocms/start needs a reverse proxy for
+ * `/checkout/*`, `/account/*`, `/api/*`, `/files/*`, etc. — those paths
+ * must hit the VTEX origin (not TanStack Start) so the user lands on
+ * the real checkout UI carrying their VTEX session cookies.
+ *
+ * The canonical wiring lives in `src/worker-entry.ts` via
+ * `createDecoWorkerEntry(..., { proxyHandler })`, where the handler
+ * calls `shouldProxyToVtex(url.pathname)` + a `createVtexCheckoutProxy`
+ * instance. The migration scaffold (`scripts/migrate/templates/server-entry.ts`)
+ * emits this by default for VTEX sites, but two regressions sneak it out:
+ *
+ *  1. A site migrated by a pre-scaffold version of the script (e.g.
+ *     before the VTEX worker-entry template existed).
+ *  2. Someone refactors `worker-entry.ts` and drops the proxy block.
+ *
+ * Without the proxy, add-to-cart still "succeeds" (the action runs
+ * server-side via TanStack RPC), but clicking "Finalizar" navigates
+ * to `/checkout` on the storefront — which returns the SPA shell —
+ * and the user never reaches VTEX checkout. The VTEX-side orderForm
+ * lives at vtexcommercestable.com.br with no way to see it.
+ *
+ * Detection is cheap: VTEX sites should import `shouldProxyToVtex`
+ * (or wire a `proxyHandler:` to `createDecoWorkerEntry`). We flag
+ * absence as `info` (not warning) because old in-prod sites we
+ * deliberately don't touch would otherwise stay noisy.
+ */
+const ruleVtexProxyHandlerMissing: Rule = {
+  id: "vtex-proxy-handler-missing",
+  title: "VTEX worker-entry missing the checkout/API proxy handler",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    // Only run when the site is actually VTEX. The cheapest signal is
+    // any import from `@decocms/apps/vtex/...` in src/ — every VTEX
+    // site has at least one (commerceLoaders, hooks, types, etc.).
+    const srcFiles = fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
+    const isVtex = srcFiles.some((abs) =>
+      fs.readText(abs).includes("@decocms/apps/vtex"),
+    );
+    if (!isVtex) return [];
+
+    const workerEntryAbs = `${siteDir}/src/worker-entry.ts`;
+    if (!fs.exists(workerEntryAbs)) {
+      return [
+        {
+          rule: "vtex-proxy-handler-missing",
+          severity: "info",
+          file: "src/worker-entry.ts",
+          message:
+            "VTEX site has no src/worker-entry.ts — /checkout proxy can't run, the user will see the SPA shell instead of VTEX checkout",
+          fix: "Re-run `deco-migrate` (the scaffold emits a worker-entry with createVtexCheckoutProxy), or copy from scripts/migrate/templates/server-entry.ts",
+        },
+      ];
+    }
+
+    const content = fs.readText(workerEntryAbs);
+    // Match either symbol — sites use the factory function OR the
+    // shouldProxyToVtex predicate as the entry point. Presence of
+    // either is a strong signal the proxy block exists; absence of
+    // both means it was dropped.
+    const hasProxyImport =
+      /from\s+["']@decocms\/apps\/vtex\/utils\/proxy["']/.test(content);
+    // Match both long form (`proxyHandler: async (...) => ...`) and
+    // object-shorthand wiring (`{ proxyHandler }`, `{ proxyHandler, admin }`).
+    // The anchor `[{,]` requires the identifier to appear as a property —
+    // not as a bare `const proxyHandler = ...` declaration, which is
+    // followed by `=` and wouldn't match either branch.
+    const hasProxyHandler = /[{,]\s*proxyHandler\s*[:,}]/.test(content);
+
+    if (hasProxyImport && hasProxyHandler) return [];
+
+    return [
+      {
+        rule: "vtex-proxy-handler-missing",
+        severity: "info",
+        file: "src/worker-entry.ts",
+        message: hasProxyImport
+          ? "imports proxy helpers but no `proxyHandler:` is wired into createDecoWorkerEntry — /checkout requests will fall through to TanStack and render the SPA shell"
+          : "no `@decocms/apps/vtex/utils/proxy` import — VTEX /checkout, /account, /api won't be proxied to the origin",
+        fix: "Add `proxyHandler` to createDecoWorkerEntry; see scripts/migrate/templates/server-entry.ts (generateVtexWorkerEntry) for the canonical block",
+      },
+    ];
+  },
+};
+
 export const ALL_RULES: Rule[] = [
   ruleDeadLibShims,
   ruleObsoleteVitePlugins,
   ruleDeadRuntimeShim,
   ruleSiteLocalGlobals,
   ruleVtexShimRegression,
+  ruleVtexProxyHandlerMissing,
   ruleLocalWidgetsTypes,
   ruleFrameworkTodos,
   ruleLocalFrameworkDuplicate,
@@ -1606,6 +1695,7 @@ export const _internals = {
     ruleDeadRuntimeShim,
     ruleSiteLocalGlobals,
     ruleVtexShimRegression,
+    ruleVtexProxyHandlerMissing,
     ruleHtmxResidue,
     ruleLocalWidgetsTypes,
     ruleFrameworkTodos,

package/scripts/migrate/post-cleanup/runner.test.ts

@@ -628,6 +628,109 @@ describe("rule: framework-todos", () => {
   });
 });
 
+describe("rule: vtex-proxy-handler-missing", () => {
+  // Canonical wiring matching scripts/migrate/templates/server-entry.ts (generateVtexWorkerEntry):
+  // imports from @decocms/apps/vtex/utils/proxy and passes proxyHandler to createDecoWorkerEntry.
+  const okWorkerEntry = `
+import { createDecoWorkerEntry } from "@decocms/start/sdk/workerEntry";
+import { shouldProxyToVtex, createVtexCheckoutProxy } from "@decocms/apps/vtex/utils/proxy";
+const proxy = createVtexCheckoutProxy({ account: "x", checkoutOrigin: "x.vtexcommercestable.com.br" });
+export default createDecoWorkerEntry(serverEntry, {
+  proxyHandler: async (req, url) => {
+    if (!shouldProxyToVtex(url.pathname)) return null;
+    return proxy(req, url);
+  },
+});
+`;
+
+  it("does not flag non-VTEX sites", () => {
+    const fs = makeFs({
+      "/site/src/index.ts": "export const x = 1;",
+      // Worker entry intentionally without the proxy import — non-VTEX
+      // sites don't need it and shouldn't be flagged.
+      "/site/src/worker-entry.ts": "export default {};",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-proxy-handler-missing")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("does not flag VTEX site whose worker-entry has the proxyHandler wired", () => {
+    const fs = makeFs({
+      "/site/src/commerceLoaders.ts": "import {} from \"@decocms/apps/vtex/mod\";",
+      "/site/src/worker-entry.ts": okWorkerEntry,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-proxy-handler-missing")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("flags VTEX site missing src/worker-entry.ts entirely", () => {
+    const fs = makeFs({
+      "/site/src/commerceLoaders.ts": "import {} from \"@decocms/apps/vtex/mod\";",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-proxy-handler-missing")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].severity).toBe("info");
+    expect(r.findings[0].message).toContain("no src/worker-entry.ts");
+  });
+
+  it("flags VTEX site whose worker-entry omits the proxy import", () => {
+    const fs = makeFs({
+      "/site/src/commerceLoaders.ts": "import {} from \"@decocms/apps/vtex/mod\";",
+      "/site/src/worker-entry.ts": `
+import { createDecoWorkerEntry } from "@decocms/start/sdk/workerEntry";
+export default createDecoWorkerEntry(serverEntry, { admin: {} });
+`,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-proxy-handler-missing")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].message).toContain("no `@decocms/apps/vtex/utils/proxy` import");
+  });
+
+  it("does not flag VTEX site using object-shorthand proxyHandler wiring", () => {
+    // Hand-written worker entries commonly hoist proxyHandler to a top-level
+    // const and pass it via shorthand. The detector must treat
+    // `{ proxyHandler }`, `{ proxyHandler, admin }`, and `{ admin, proxyHandler }`
+    // the same as `proxyHandler: ...` — otherwise the audit cries wolf.
+    const shorthandWorkerEntry = `
+import { createDecoWorkerEntry } from "@decocms/start/sdk/workerEntry";
+import { shouldProxyToVtex, createVtexCheckoutProxy } from "@decocms/apps/vtex/utils/proxy";
+const proxy = createVtexCheckoutProxy({ account: "x", checkoutOrigin: "x.vtexcommercestable.com.br" });
+const proxyHandler = async (req: Request, url: URL) => {
+  if (!shouldProxyToVtex(url.pathname)) return null;
+  return proxy(req, url);
+};
+export default createDecoWorkerEntry(serverEntry, { admin: {}, proxyHandler });
+`;
+    const fs = makeFs({
+      "/site/src/commerceLoaders.ts": "import {} from \"@decocms/apps/vtex/mod\";",
+      "/site/src/worker-entry.ts": shorthandWorkerEntry,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-proxy-handler-missing")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("flags VTEX site that imports proxy helpers but never wires proxyHandler", () => {
+    const fs = makeFs({
+      "/site/src/commerceLoaders.ts": "import {} from \"@decocms/apps/vtex/mod\";",
+      "/site/src/worker-entry.ts": `
+import { createDecoWorkerEntry } from "@decocms/start/sdk/workerEntry";
+import { shouldProxyToVtex } from "@decocms/apps/vtex/utils/proxy";
+// note: shouldProxyToVtex imported but not used in a proxyHandler.
+export default createDecoWorkerEntry(serverEntry, { admin: {} });
+`,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-proxy-handler-missing")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].message).toContain("no `proxyHandler:` is wired");
+  });
+});
+
 describe("internals", () => {
   it("extractExports parses common forms (top-level, unindented)", () => {
     const code = [

package/scripts/migrate.ts

@@ -255,6 +255,19 @@ function bootstrap(ctx: { sourceDir: string }) {
   const pm = "bun";
   if (!run(`${pm} install`, "Install dependencies", true)) return;
   run("bunx tsx node_modules/@decocms/start/scripts/generate-blocks.ts", "Generate CMS blocks");
+  // generate-invoke emits src/server/invoke.gen.ts with top-level
+  // createServerFn declarations + the forwardResponseCookies bridge that
+  // propagates VTEX Set-Cookie headers (orderFormId, segment, sc…) to the
+  // browser. Without this file, the site falls back to the proxy
+  // `~/runtime.ts` route which hits /deco/invoke and used to drop cookies,
+  // making the cart appear empty at /checkout after addItemToCart. The
+  // upstream invoke handler now also forwards cookies correctly, but
+  // running the generator gives every freshly-migrated site the canonical
+  // RPC path so VTEX hooks (useCart, useUser, useWishlist) work end-to-end.
+  run(
+    "bunx tsx node_modules/@decocms/start/scripts/generate-invoke.ts",
+    "Generate VTEX invoke server functions",
+  );
   run("bunx tsr generate", "Generate TanStack routes");
 
   if (failures > 0) {

package/src/admin/invoke.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Regression tests for /deco/invoke Set-Cookie propagation.
+ *
+ * The historical bug: the single- and batch-invoke paths copied
+ * `RequestContext.responseHeaders` to the HTTP response via
+ * `headers.entries()`, which collapses multiple `Set-Cookie` values
+ * into a single comma-joined string. Browsers silently discard those,
+ * so every VTEX cart action lost its session cookies and the user
+ * ended up at /checkout with an empty cart.
+ *
+ * These tests pin the fix: when a handler appends multiple
+ * Set-Cookie values to `RequestContext.responseHeaders`, the response
+ * returned by `handleInvoke` must surface them as N distinct
+ * Set-Cookie headers (readable via `response.headers.getSetCookie()`).
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { RequestContext } from "../sdk/requestContext";
+import {
+  clearInvokeHandlers,
+  handleInvoke,
+  registerInvokeHandlers,
+} from "./invoke";
+
+const COOKIE_A = "checkout.vtex.com__orderFormId=of-123; Path=/; HttpOnly";
+const COOKIE_B = "segment=eyJjYW1wYWlnbnMiOiJ4In0=; Path=/; HttpOnly";
+const COOKIE_C = "sc=1; Path=/; HttpOnly";
+
+function makeInvokeRequest(key: string, body: unknown = {}): Request {
+  return new Request(`http://localhost/deco/invoke/${key}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+function makeBatchRequest(body: Record<string, unknown>): Request {
+  return new Request("http://localhost/deco/invoke", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+describe("handleInvoke — Set-Cookie propagation (single)", () => {
+  beforeEach(() => clearInvokeHandlers());
+  afterEach(() => clearInvokeHandlers());
+
+  it("forwards multiple Set-Cookie values as distinct headers", async () => {
+    registerInvokeHandlers({
+      "vtex/actions/addItemsToCart": async () => {
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_A);
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_B);
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_C);
+        return { orderFormId: "of-123" };
+      },
+    });
+
+    const request = makeInvokeRequest("vtex/actions/addItemsToCart");
+    const response = await RequestContext.run(request, () => handleInvoke(request));
+
+    const cookies = response.headers.getSetCookie();
+    expect(cookies).toHaveLength(3);
+    expect(cookies).toContain(COOKIE_A);
+    expect(cookies).toContain(COOKIE_B);
+    expect(cookies).toContain(COOKIE_C);
+  });
+
+  it("does not collapse cookies into a single Set-Cookie entry", async () => {
+    registerInvokeHandlers({
+      "vtex/actions/foo": async () => {
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_A);
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_B);
+        return {};
+      },
+    });
+
+    const request = makeInvokeRequest("vtex/actions/foo");
+    const response = await RequestContext.run(request, () => handleInvoke(request));
+
+    // The regressed bug appended a single comma-joined string, so
+    // `getSetCookie()` returned a 1-element array. The fix appends each
+    // value individually — verifying the count alone catches the regression.
+    expect(response.headers.getSetCookie()).toHaveLength(2);
+  });
+
+  it("forwards non-cookie headers unchanged", async () => {
+    registerInvokeHandlers({
+      "vtex/actions/withHeader": async () => {
+        RequestContext.responseHeaders.append("x-vtex-trace-id", "abc-123");
+        return {};
+      },
+    });
+
+    const request = makeInvokeRequest("vtex/actions/withHeader");
+    const response = await RequestContext.run(request, () => handleInvoke(request));
+    expect(response.headers.get("x-vtex-trace-id")).toBe("abc-123");
+  });
+
+  it("does not forward Set-Cookie when handler writes none", async () => {
+    registerInvokeHandlers({
+      "vtex/loaders/productList": async () => ({ items: [] }),
+    });
+
+    const request = makeInvokeRequest("vtex/loaders/productList");
+    const response = await RequestContext.run(request, () => handleInvoke(request));
+    expect(response.headers.getSetCookie()).toEqual([]);
+  });
+});
+
+describe("handleInvoke — Set-Cookie propagation (batch)", () => {
+  beforeEach(() => clearInvokeHandlers());
+  afterEach(() => clearInvokeHandlers());
+
+  it("forwards cookies that batch handlers append to the shared context", async () => {
+    registerInvokeHandlers({
+      "vtex/actions/addItemsToCart": async () => {
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_A);
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_B);
+        return { orderFormId: "of-123" };
+      },
+      "vtex/loaders/productList": async () => {
+        // Loader writes its own cookie (e.g. segment) — must also propagate.
+        RequestContext.responseHeaders.append("set-cookie", COOKIE_C);
+        return { items: [] };
+      },
+    });
+
+    const request = makeBatchRequest({
+      "vtex/actions/addItemsToCart": { orderFormId: "x" },
+      "vtex/loaders/productList": {},
+    });
+    const response = await RequestContext.run(request, () => handleInvoke(request));
+
+    const cookies = response.headers.getSetCookie();
+    expect(cookies).toHaveLength(3);
+    expect(cookies).toContain(COOKIE_A);
+    expect(cookies).toContain(COOKIE_B);
+    expect(cookies).toContain(COOKIE_C);
+  });
+});

package/src/admin/invoke.ts

@@ -58,6 +58,41 @@ export function clearInvokeHandlers(): void {
 
 const JSON_HEADERS = { "Content-Type": "application/json" } as const;
 
+/**
+ * Copy headers that handlers wrote to `RequestContext.responseHeaders`
+ * onto an outgoing Response.
+ *
+ * Why this exists and is not a `for…of headers.entries()` one-liner:
+ * `Headers.entries()` (and `forEach`) collapses multiple `Set-Cookie`
+ * values into a single comma-joined string (per the Fetch spec).
+ * Browsers silently discard cookies whose value contains an unescaped
+ * comma, so every VTEX cart action that returns multiple cookies
+ * (`checkout.vtex.com__orderFormId`, `segment`, `sc`, `vtex_session`…)
+ * loses them in transit. The next request creates a fresh empty
+ * orderForm and the user lands on /checkout with an empty cart.
+ *
+ * `Headers.getSetCookie()` is the spec-blessed way to read the
+ * un-collapsed list. We append each value individually onto the
+ * response so the browser sees N distinct `Set-Cookie` headers, and
+ * use `forEach` to copy any non-cookie headers as-is.
+ */
+function forwardCtxHeadersTo(response: Response): void {
+  const ctx = RequestContext.current;
+  if (!ctx) return;
+  const cookies =
+    typeof ctx.responseHeaders.getSetCookie === "function"
+      ? ctx.responseHeaders.getSetCookie()
+      : [];
+  for (const cookie of cookies) {
+    response.headers.append("set-cookie", cookie);
+  }
+  ctx.responseHeaders.forEach((value, key) => {
+    if (key.toLowerCase() !== "set-cookie") {
+      response.headers.append(key, value);
+    }
+  });
+}
+
 const isDev =
   typeof globalThis.process !== "undefined" && globalThis.process.env?.NODE_ENV === "development";
 
@@ -171,17 +206,7 @@ export async function handleInvoke(request: Request): Promise<Response> {
       }
       const filtered = selectFields(result, select);
       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);
-        }
-      }
-
+      forwardCtxHeadersTo(response);
       return response;
     } catch (error) {
       return errorResponse((error as Error).message, 500, error);
@@ -202,8 +227,11 @@ export async function handleInvoke(request: Request): Promise<Response> {
           try {
             let result = await found.handler(payload, request);
             // If a loader returns a Response, extract its JSON body for batching.
-            // Set-Cookie headers from batch items are not forwarded individually
-            // (use single invoke for auth loaders that need cookie passthrough).
+            // Set-Cookie values from a handler-returned Response are *not*
+            // forwarded — those leave the AsyncLocalStorage scope. Handlers
+            // that need cookie passthrough must write to
+            // RequestContext.responseHeaders (which forwardCtxHeadersTo()
+            // below propagates onto the batch response).
             if (result instanceof Response) {
               try { result = await result.json(); } catch { result = null; }
             }
@@ -217,7 +245,12 @@ export async function handleInvoke(request: Request): Promise<Response> {
       }),
     );
 
-    return new Response(JSON.stringify(results), { status: 200, headers: JSON_HEADERS });
+    const response = new Response(JSON.stringify(results), { status: 200, headers: JSON_HEADERS });
+    // All batch handlers share the same RequestContext, so any Set-Cookie
+    // they appended (e.g. from VTEX vtexFetchWithCookies) is in
+    // `responseHeaders` by now. Forward it as N distinct Set-Cookie headers.
+    forwardCtxHeadersTo(response);
+    return response;
   }
 
   return errorResponse("No invoke key specified", 400);

package/src/middleware/observability.ts

@@ -253,6 +253,22 @@ export const MetricNames = {
    * `MIGRATION_TOOLING_PLAN.md` for the rationale.
    */
   COMMERCE_REQUEST_DURATION_MS: "commerce_request_duration_ms",
+  /**
+   * Per-loader execution duration. Emitted by `cachedLoader` for every
+   * loader call — cached or not. The `cache_status` label lets dashboards
+   * separate origin latency from in-memory hit latency without needing
+   * to join on traces.
+   *
+   * Canonical labels: `loader`, `cache_status`.
+   */
+  LOADER_DURATION_MS: "loader_duration_ms",
+  /**
+   * Counter incremented when a loader throws. Complements
+   * `loader_duration_ms` for error-rate dashboards.
+   *
+   * Canonical labels: `loader`.
+   */
+  LOADER_ERRORS_TOTAL: "loader_errors_total",
 } as const;
 
 /**
@@ -455,6 +471,35 @@ export function recordCommerceMetric(
   m.histogramRecord?.(MetricNames.COMMERCE_REQUEST_DURATION_MS, durationMs, merged);
 }
 
+/**
+ * Record a loader execution sample. Call from `cachedLoader` after the
+ * loader resolves or rejects. `cache_status` mirrors `CacheDecision` so
+ * dashboards can distinguish HIT (fresh) from STALE-HIT (SWR), STALE-ERROR
+ * (SIE fallback), MISS (origin fetch), and BYPASS (dev / no-store).
+ */
+export function recordLoaderMetric(
+  name: string,
+  durationMs: number,
+  cacheStatus: CacheDecision | "BYPASS",
+) {
+  const m = getState().meter;
+  if (!m) return;
+  m.histogramRecord?.(MetricNames.LOADER_DURATION_MS, durationMs, {
+    loader: name,
+    cache_status: cacheStatus,
+  });
+}
+
+/**
+ * Increment the loader error counter. Call when a loader throws and the
+ * error is not swallowed by a SIE fallback.
+ */
+export function recordLoaderError(name: string) {
+  const m = getState().meter;
+  if (!m) return;
+  m.counterInc(MetricNames.LOADER_ERRORS_TOTAL, 1, { loader: name });
+}
+
 function normalizePath(path: string): string {
   // Collapse dynamic segments to reduce cardinality
   return path

package/src/sdk/cachedLoader.ts

@@ -11,7 +11,12 @@
  * (e.g. "product") which derives timing from the unified profile system.
  */
 
-import { recordCacheMetric, withTracing } from "../middleware/observability";
+import {
+  recordCacheMetric,
+  recordLoaderError,
+  recordLoaderMetric,
+  withTracing,
+} from "../middleware/observability";
 import { type CacheProfileName, loaderCacheOptions } from "./cacheHeaders";
 
 export type CachePolicy = "no-store" | "no-cache" | "stale-while-revalidate";
@@ -100,17 +105,32 @@ export function createCachedLoader<TProps, TResult>(
     if (inflight) {
       // Treat in-flight dedup as a cache hit — avoided the origin call.
       recordCacheMetric(true, name, undefined, "cachedLoader");
-      return inflight as Promise<TResult>;
+      const start = performance.now();
+      return inflight.then((r) => {
+        recordLoaderMetric(name, performance.now() - start, "HIT");
+        return r as TResult;
+      });
     }
 
     if (isDev) {
       // Dev mode: no caching, but still useful to count attempts.
       recordCacheMetric(false, name, undefined, "cachedLoader");
+      const devStart = performance.now();
       const promise = withTracing(
         "deco.cachedLoader",
-        () => loaderFn(props).finally(() => inflightRequests.delete(cacheKey)),
+        () => loaderFn(props),
         { "deco.loader": name, "deco.cache.policy": "no-cache-dev" },
-      );
+      )
+        .then((r) => {
+          recordLoaderMetric(name, performance.now() - devStart, "BYPASS");
+          return r;
+        })
+        .catch((err) => {
+          recordLoaderMetric(name, performance.now() - devStart, "BYPASS");
+          recordLoaderError(name);
+          throw err;
+        })
+        .finally(() => inflightRequests.delete(cacheKey));
       inflightRequests.set(cacheKey, promise);
       return promise;
     }
@@ -122,6 +142,7 @@ export function createCachedLoader<TProps, TResult>(
     if (policy === "no-cache") {
       if (entry && !isStale) {
         recordCacheMetric(true, name, "HIT", "cachedLoader");
+        recordLoaderMetric(name, 0, "HIT");
         return entry.value;
       }
     }
@@ -129,12 +150,14 @@ export function createCachedLoader<TProps, TResult>(
     if (policy === "stale-while-revalidate") {
       if (entry && !isStale) {
         recordCacheMetric(true, name, "HIT", "cachedLoader");
+        recordLoaderMetric(name, 0, "HIT");
         return entry.value;
       }
 
       if (entry && isStale && !entry.refreshing) {
         // Stale-while-revalidate hit: serve stale, refresh in background.
         recordCacheMetric(true, name, "STALE-HIT", "cachedLoader");
+        recordLoaderMetric(name, 0, "STALE-HIT");
         entry.refreshing = true;
         loaderFn(props)
           .then((result) => {
@@ -160,6 +183,7 @@ export function createCachedLoader<TProps, TResult>(
         // the decision as STALE-ERROR so dashboards can distinguish
         // this from healthy SWR.
         recordCacheMetric(true, name, "STALE-ERROR", "cachedLoader");
+        recordLoaderMetric(name, 0, "STALE-ERROR");
         return entry.value;
       }
     }
@@ -167,11 +191,13 @@ export function createCachedLoader<TProps, TResult>(
     // Cache miss — emit metric, then run loader inside a span so individual
     // slow loaders are visible in traces.
     recordCacheMetric(false, name, "MISS", "cachedLoader");
+    const loaderStart = performance.now();
     const promise = withTracing("deco.cachedLoader", () => loaderFn(props), {
       "deco.loader": name,
       "deco.cache.policy": policy,
     })
       .then((result) => {
+        recordLoaderMetric(name, performance.now() - loaderStart, "MISS");
         cache.set(cacheKey, {
           value: result,
           createdAt: Date.now(),
@@ -190,9 +216,12 @@ export function createCachedLoader<TProps, TResult>(
             console.warn(
               `[cachedLoader] ${name}: origin error, serving stale entry (age=${Math.round(age / 1000)}s, sie=${Math.round(staleIfError / 1000)}s)`,
             );
+            recordLoaderMetric(name, performance.now() - loaderStart, "STALE-ERROR");
             return entry.value;
           }
         }
+        recordLoaderMetric(name, performance.now() - loaderStart, "MISS");
+        recordLoaderError(name);
         throw err;
       });
 

package/src/sdk/observability.ts

@@ -65,6 +65,8 @@ export {
   MetricNames,
   recordCacheMetric,
   recordCommerceMetric,
+  recordLoaderError,
+  recordLoaderMetric,
   recordRequestMetric,
   type RequestMetricLabels,
   type RequestStore,