@decocms/start 2.22.0 → 2.23.0

package/.agents/skills/deco-to-tanstack-migration/SKILL.md

@@ -43,7 +43,7 @@ Each phase has entry/exit criteria. Follow in order. Automation % indicates how
 | [2](#phase-2--signals--state) | Signals & State | ~50% | `references/signals/` |
 | [3](#phase-3--deco-framework) | Deco Framework Elimination | ~80% | `references/deco-framework/` |
 | [4](#phase-4--commerce--types) | Commerce Types & UI | ~70% | `references/commerce/` |
-| [5](#phase-5--platform-hooks) | Platform Hooks | 0% | `references/platform-hooks/` |
+| [5](#phase-5--platform-hooks) | Platform Hooks (factories, W12+) | template | `references/platform-hooks-factories.md` |
 | [6](#phase-6--islands-elimination) | Islands Elimination | ~60% | `references/islands.md` |
 | [7](#phase-7--section-registry) | Section Registry & Setup | 0% | `references/async-rendering.md` |
 | [8](#phase-8--routes--cms) | Routes & CMS | template | `references/navigation.md` |
@@ -152,14 +152,18 @@ See: `references/commerce/README.md`, `references/vtex-commerce.md`
 
 **Entry**: Phase 4 complete
 
-**Actions** (manual implementation):
-1. Create `src/hooks/useCart.ts` — module-level singleton + listener pattern
-2. Create `src/hooks/useUser.ts`, `src/hooks/useWishlist.ts` (stubs or real)
-3. Wire VTEX API calls via `@decocms/apps` invoke functions
+**Actions (Wave 12+ factory-based — current)**:
+1. `src/hooks/useCart.ts` — 5-line shim around `createUseCart` from `@decocms/apps/vtex/hooks/createUseCart`
+2. `src/hooks/useUser.ts` — 5-line shim around `createUseUser`
+3. `src/hooks/useWishlist.ts` — 5-line shim around `createUseWishlist`
+4. The migration template (`scripts/migrate/templates/hooks.ts`) emits all three for VTEX sites automatically.
+
+For non-VTEX platforms, scaffold no-op stubs using `@decocms/start/sdk/signal` (see factories doc § "Non-VTEX platforms").
 
 **Exit**: Cart add/remove works, no `apps/{platform}/hooks` imports
 
-See: `references/platform-hooks/README.md`
+See: `references/platform-hooks-factories.md` (canonical, Wave 12+).
+Pre-W12 manual approach is preserved at `references/platform-hooks/README.md` for sites that haven't migrated to factories yet.
 
 ---
 
@@ -356,7 +360,8 @@ For sites with 100+ sections:
 | Signals → TanStack Store | `references/signals/` |
 | Deco framework elimination | `references/deco-framework/` |
 | Commerce & widget types | `references/commerce/` |
-| Platform hooks (VTEX) | `references/platform-hooks/` |
+| Platform hooks (VTEX, factories — Wave 12+) | `references/platform-hooks-factories.md` |
+| Platform hooks (manual, legacy pre-W12) | `references/platform-hooks/README.md` |
 | Vite configuration | `references/vite-config/` |
 | Automation commands | `references/codemod-commands.md` |
 | Islands elimination | `references/islands.md` |

package/.agents/skills/deco-to-tanstack-migration/references/platform-hooks/README.md

@@ -1,16 +1,29 @@
-# Platform Hooks Migration
+# Platform Hooks Migration (legacy reference)
 
-Platform hooks (useCart, useUser, useWishlist) are the most complex migration target because they have real business logic.
+> **This document describes the pre-Wave-12 manual approach.** New
+> migrations should follow
+> [`platform-hooks-factories.md`](../platform-hooks-factories.md), which
+> covers the `createUseCart` / `createUseUser` / `createUseWishlist`
+> factories from `@decocms/apps/vtex/hooks`. The factories collapse
+> everything below into a 5-line site shim per hook.
+>
+> This file is kept for sites that scaffolded before the factories
+> existed — typically sites with `src/lib/vtex-cart-server.ts` or
+> hand-rolled `createServerFn` calls to VTEX endpoints inside
+> `src/hooks/useCart.ts`. See the **"Migrating off the manual approach"**
+> section in the new doc for the cleanup playbook.
 
-## Strategy
+---
+
+## Strategy (legacy)
 
 All hooks are **site-local**. No Vite alias tricks. No compat layers.
 
-- Active platform hooks (VTEX for this store) -> `~/hooks/useCart.ts` with real implementation
-- Inactive platform hooks (Wake, Shopify, etc.) -> `~/hooks/platform/{name}.ts` with no-op stubs
-- Auth hooks -> `~/hooks/useUser.ts`, `~/hooks/useWishlist.ts`
+- Active platform hooks (VTEX for this store) → `~/hooks/useCart.ts` with real implementation
+- Inactive platform hooks (Wake, Shopify, etc.) → `~/hooks/platform/{name}.ts` with no-op stubs
+- Auth hooks → `~/hooks/useUser.ts`, `~/hooks/useWishlist.ts`
 
-## VTEX useCart (Real Implementation)
+## VTEX useCart (Manual Implementation)
 
 ### Why Server Functions Are Required
 
@@ -18,7 +31,7 @@ The storefront domain (e.g., `my-store.deco.site`) differs from the VTEX checkou
 
 Use TanStack Start `createServerFn` to create server-side proxy functions that the client hook calls transparently.
 
-### Server Functions (~/lib/vtex-cart-server.ts)
+### Server Functions (`~/lib/vtex-cart-server.ts`)
 
 ```typescript
 import { createServerFn } from "@tanstack/react-start";
@@ -40,50 +53,46 @@ export const getOrCreateCart = createServerFn({ method: "GET" })
         "X-VTEX-API-AppKey": API_KEY,
         "X-VTEX-API-AppToken": API_TOKEN,
       },
-      body: JSON.stringify({ expectedOrderFormSections: ["items", "totalizers", "shippingData", "clientPreferencesData", "storePreferencesData", "marketingData"] }),
+      body: JSON.stringify({
+        expectedOrderFormSections: [
+          "items",
+          "totalizers",
+          "shippingData",
+          "clientPreferencesData",
+          "storePreferencesData",
+          "marketingData",
+        ],
+      }),
     });
     return res.json();
   });
-
-export const addItemsToCart = createServerFn({ method: "POST" })
-  .validator((data: { orderFormId: string; items: any[] }) => data)
-  .handler(async ({ data }) => {
-    const res = await fetch(
-      `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm/${data.orderFormId}/items`,
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json", "X-VTEX-API-AppKey": API_KEY, "X-VTEX-API-AppToken": API_TOKEN },
-        body: JSON.stringify({ orderItems: data.items }),
-      },
-    );
-    return res.json();
-  });
-
-export const updateCartItems = createServerFn({ method: "POST" })
-  .validator((data: { orderFormId: string; items: any[] }) => data)
-  .handler(async ({ data }) => {
-    const res = await fetch(
-      `https://${ACCOUNT}.vtexcommercestable.com.br/api/checkout/pub/orderForm/${data.orderFormId}/items/update`,
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json", "X-VTEX-API-AppKey": API_KEY, "X-VTEX-API-AppToken": API_TOKEN },
-        body: JSON.stringify({ orderItems: data.items }),
-      },
-    );
-    return res.json();
-  });
 ```
 
-### Hook (~/hooks/useCart.ts)
+> **Don't write code like this in new sites.** The factories already wrap
+> all canonical VTEX action endpoints (cart, session, masterdata,
+> newsletter, checkout) in `@decocms/apps/vtex/actions/*`. The migration
+> template scaffolds `src/server/invoke.gen.ts` which exposes them as
+> typed server functions; `~/server/invoke.ts` then re-exports them
+> under `invoke.vtex.actions.*`. The factory consumes that surface and
+> returns the legacy hook shape.
 
-Key design decisions:
+### Hook (`~/hooks/useCart.ts`)
+
+Key design decisions of the legacy manual hook:
 - **Module-level singleton state** shared across all component instances
 - **Pub/sub pattern** (`_listeners` Set) for notifying React components of changes
-- **Cookie-based session**: reads/writes `checkout.vtex.com__orderFormId` on the **client** side (not VTEX's domain cookie)
+- **Cookie-based session**: reads/writes `checkout.vtex.com__orderFormId` on the **client** side
 - Returns `cart` and `loading` with `.value` getter/setter for backward compat with Preact-era components
 - Lazy initialization: cart is fetched on first component mount, not on module load
 - Exports `itemToAnalyticsItem` for cart-specific analytics mapping
 
+The factory in `@decocms/apps/vtex/hooks/createUseCart` ships *exactly*
+these semantics — that's the implementation behind the new shim. If your
+site needs to extend behaviour (e.g. extra analytics events, custom
+post-add hooks), prefer wrapping the factory's exports rather than
+forking back to a manual hook; the factory leaves space for that
+without giving up the upgrade path.
+
 ### Cross-Domain Checkout
 
 The minicart's "Finalizar Compra" button must link to the VTEX checkout domain with the `orderFormId` as a query parameter — the VTEX domain can't read the storefront's cookies:
@@ -92,10 +101,8 @@ The minicart's "Finalizar Compra" button must link to the VTEX checkout domain w
 const checkoutUrl = `https://secure.${STORE_DOMAIN}/checkout/?orderFormId=${orderFormId}`;
 ```
 
-### VTEX Types (~/types/vtex.ts)
-
-Site-local types for VTEX-specific structures:
-- `OrderFormItem`, `SimulationOrderForm`, `Sla`, `SKU`, `VtexProduct`
+This pattern is unchanged by the factory — it's a UI concern, not a hook
+concern. Implement it in your minicart component as before.
 
 ## Inactive Platform Stubs
 
@@ -130,9 +137,13 @@ export function useWishlist() {
 }
 ```
 
-Create similar stubs for: `shopify.ts`, `linx.ts`, `vnda.ts`, `nuvemshop.ts`.
+Create similar stubs for: `shopify.ts`, `linx.ts`, `vnda.ts`, `nuvemshop.ts`. Match the return shape to what each platform's AddToCartButton expects (some use `addItem`, others `addItems`).
 
-Match the return shape to what each platform's AddToCartButton expects (some use `addItem`, others `addItems`).
+The factory equivalent for non-VTEX sites is documented in
+[`platform-hooks-factories.md` § "Non-VTEX platforms"](../platform-hooks-factories.md#non-vtex-platforms).
+Until each platform has its own factory in `@decocms/apps`, the stub
+shape above is still correct — but use `@decocms/start/sdk/signal`
+instead of hand-rolled `{ value: ... }` objects.
 
 ## Import Rewrites
 
@@ -143,7 +154,6 @@ sed -i '' 's|from "apps/vtex/hooks/useWishlist.ts"|from "~/hooks/useWishlist"|g'
 sed -i '' 's|from "apps/vtex/utils/types.ts"|from "~/types/vtex"|g'
 sed -i '' 's|from "apps/shopify/hooks/useCart.ts"|from "~/hooks/platform/shopify"|g'
 sed -i '' 's|from "apps/wake/hooks/useCart.ts"|from "~/hooks/platform/wake"|g'
-# etc. for all platforms
 ```
 
 ## Verification

package/.agents/skills/deco-to-tanstack-migration/references/platform-hooks-factories.md

@@ -0,0 +1,186 @@
+# Platform Hooks — Factory Pattern
+
+> **Canonical reference for `createUseCart` / `createUseUser` /
+> `createUseWishlist` from `@decocms/apps/vtex/hooks`.** These factories
+> ship the legacy invoke-based hook semantics that migrated Fresh sites
+> depend on — module-level singleton state, listener-based re-render,
+> awaitable async actions, signal-shaped accessors. Sites consume them
+> as 5-line shims.
+
+This doc replaces the pre-W12 "manual `createServerFn` per VTEX endpoint"
+approach in
+[`platform-hooks/README.md`](./platform-hooks/README.md). If you scaffolded
+a site before Wave 12 (≤ `@decocms/apps@2.x` / `@decocms/start@2.18`), see
+"Migrating off the manual approach" at the bottom.
+
+---
+
+## What the factories own
+
+| Concern | Where it lives |
+|---|---|
+| Module-level singleton state (`cart`, `user`, `wishlist`) | Inside the factory closure |
+| `useEffect` + `forceRender(c => c + 1)` re-render pattern | Factory |
+| Signal-shaped accessors (`cart.value`, `user.value`) | Factory |
+| Awaitable mutations (`await addItem(...)`) | Factory |
+| `itemToAnalyticsItem` helper (cart) | Factory |
+| Wishlist arg swap (`productId` ↔ `productGroupId`) | Factory |
+| **VTEX HTTP calls** | NOT in the factory — provided by the `invoke` proxy you pass in |
+
+The factory only wires state + listeners. The site provides an `invoke`
+object whose shape is structurally typed against
+`CreateUseCartInvoke` / `CreateUseUserInvoke` / `CreateUseWishlistInvoke`
+(exported next to each factory). The migration template generates an
+`invoke` proxy in `src/server/invoke.ts` that meets all three shapes
+without any extra wiring.
+
+---
+
+## Site-local shim (the entire file)
+
+### `src/hooks/useCart.ts`
+
+```ts
+import { createUseCart } from "@decocms/apps/vtex/hooks/createUseCart";
+import { invoke } from "~/server/invoke";
+
+export type { OrderForm, OrderFormItem } from "@decocms/apps/vtex/types";
+
+export const { useCart, resetCart, itemToAnalyticsItem } = createUseCart({
+  invoke,
+});
+```
+
+### `src/hooks/useUser.ts`
+
+```ts
+import { createUseUser } from "@decocms/apps/vtex/hooks/createUseUser";
+import { invoke } from "~/server/invoke";
+
+export type { Person } from "@decocms/apps/vtex/loaders/user";
+
+export const { useUser, resetUser } = createUseUser({ invoke });
+```
+
+### `src/hooks/useWishlist.ts`
+
+```ts
+import { createUseWishlist } from "@decocms/apps/vtex/hooks/createUseWishlist";
+import { invoke } from "~/server/invoke";
+
+export type { WishlistItem } from "@decocms/apps/vtex/loaders/wishlist";
+
+export const { useWishlist, resetWishlist } = createUseWishlist({ invoke });
+```
+
+That's the whole hook — no `createServerFn`, no VTEX URLs, no `AppKey`
+plumbing. `npm run migrate` scaffolds these three files automatically
+when `--platform vtex` is set; if you regenerate, the migration template
+in `scripts/migrate/templates/hooks.ts` is the source of truth.
+
+---
+
+## Why a factory and not a single hook?
+
+> Two reasons that come up repeatedly when reviewing migration PRs.
+
+1. **`useCart` already exists in apps.** The canonical `vtex/hooks/useCart.ts`
+   is built on TanStack Query and exposes the `Minicart` shape — that is
+   the shape new code should target. The factory exists strictly so
+   already-migrated UIs keep working without a rewrite. Both can coexist
+   in one site.
+2. **Singletons can't live in a shared package without leaking across
+   sites.** The factory call instantiates a fresh module-level state per
+   site. Importing `useCart` directly from apps would share state across
+   any sites that ran in the same Worker (matters less in practice, but
+   it's the architectural reason the factory exists).
+
+The factory boundary is also the seam where we'd later wire
+`@tanstack/store` if we wanted to — the API shape is signal-compatible
+already.
+
+---
+
+## Non-VTEX platforms
+
+Sites that target Wake / Shopify / VNDA / Linx / Nuvemshop still need a
+hook surface that AddToCartButtons can consume. Until each platform has
+its own factory in `@decocms/apps`, scaffold a no-op shim:
+
+```ts
+// src/hooks/useCart.ts (custom platform)
+import { signal } from "@decocms/start/sdk/signal";
+
+const cart = signal<unknown>(null);
+const loading = signal(false);
+
+export function useCart() {
+  return {
+    cart,
+    loading,
+    async getCart() {
+      // TODO: call your platform's cart API via ~/server/invoke
+      return null;
+    },
+    async addItems(_items: unknown[]) {
+      // TODO
+    },
+    async updateItems(_items: unknown[]) {
+      // TODO
+    },
+    setCart(next: unknown) {
+      cart.value = next;
+    },
+  };
+}
+
+export default useCart;
+```
+
+`@decocms/start/sdk/signal` (re-exported via `~/sdk/signal` after
+migration) gives you the same `.value` getter/setter the factory uses,
+so AddToCart UI components don't need to know which platform is wired.
+
+The migration template's `generateGenericUseCart()` emits this stub when
+`--platform` is `custom` (or any non-VTEX value).
+
+---
+
+## Migrating off the manual approach (pre-W12 sites)
+
+If your site contains files like `src/lib/vtex-cart-server.ts` or hand-rolled `createServerFn` blocks for VTEX endpoints in `src/hooks/useCart.ts`, the post-cleanup audit will not auto-fix them — the manual code accumulated 6+ months of site-specific edits and the per-site judgment call about "what's still needed?" is real. The mechanical part:
+
+1. Replace the entire body of `src/hooks/useCart.ts` with the 5-line factory shim above.
+2. Delete `src/lib/vtex-cart-server.ts` (the migration template's `src/server/invoke.gen.ts` provides equivalent server functions wrapping `@decocms/apps/vtex/actions/checkout`).
+3. Verify `src/server/invoke.ts` exports the proxy shape the factory needs (cart actions under `invoke.vtex.actions`). The migration template scaffolds this; older sites may need to add the missing entries by hand.
+4. Run `npm run typecheck` — TypeScript will surface any callsites that referenced removed helpers (e.g. local `getOrCreateCart` shims).
+5. Repeat for `useUser` / `useWishlist`.
+
+For `useUser`, the analog of step 2 is removing any local `currentUser` /
+`getUser` server functions in favor of `@decocms/apps/vtex/loaders/user`
+exposed via `invoke.vtex.loaders.user()`. For `useWishlist`, the
+canonical surface is `@decocms/apps/vtex/{actions,loaders}/wishlist`.
+
+If you find yourself wanting to add behaviour to a factory (extra cart
+actions, custom analytics events) rather than ripping out the factory and going back to a manual hook:
+
+- **Extra read paths** → expose a new loader from
+  `@decocms/apps/vtex/loaders/*`, register it in `~/server/invoke.ts`,
+  call from your component (the factory doesn't need to know).
+- **Extra write paths** → ditto for `@decocms/apps/vtex/actions/*`.
+- **Cross-cutting business logic** (e.g. PIX-specific offer pricing) →
+  this is the kind of seam that justifies a parallel `useOffer` factory.
+  Talk to the apps maintainers; opening up a factory's plugin slots is a
+  one-PR change in apps, not a per-site rewrite.
+
+---
+
+## Related
+
+- `scripts/migrate/templates/hooks.ts` — the template that emits the
+  shims above.
+- `apps-start/vtex/hooks/createUseCart.ts` /
+  `createUseUser.ts` / `createUseWishlist.ts` — the factories
+  themselves; each docstring is the authoritative API reference.
+- `references/platform-hooks/README.md` — historical reference for the
+  pre-W12 manual approach (kept for sites that haven't migrated yet).

package/MIGRATION_TOOLING_PLAN.md

@@ -239,6 +239,58 @@ Each item carries a status: ⬜ pending, 🟡 in progress, ✅ done, 🚫 blocke
 
 > Append-only. Each entry: date, what we found, where it impacts the plan.
 
+### 2026-05-01 — Wave 15-A double-check exposed a self-perpetuating template→audit loop
+
+- **Q1 (sites→packages promotion completeness):** Two subagents
+  swept `casaevideo-storefront` + `baggagio-tanstack`. The big
+  A-list icebergs are caught — but **5 cross-site duplications
+  satisfying D4** slipped through (`useSuggestions`, `useOffer`
+  forks, `useVariantPossibilities` forks, site-local copies of
+  framework `clx` / `useSendEvent`, three competing `Picture`
+  APIs). Plus 4 migration debts where the framework already has
+  the answer (`useCart` factory not adopted in casaevideo,
+  `runtime.ts` inline proxy still scaffolded, location matcher
+  duplication, inline cookie helpers).
+- **Q2 (script/skill coverage of what we shipped):** Worse. The
+  migration script's templates were **scaffolding code that the
+  audit's `--fix` then removed** — the textbook
+  self-perpetuating loop. `templates/vite-config.ts` was emitting
+  `site-manual-chunks` + `deco-stub-meta-gen` (both already
+  inside `decoVitePlugin()`). `templates/server-entry.ts` was
+  emitting a 47-line `createNestedInvokeProxy` body (already in
+  `@decocms/start/sdk`). The factories shipped in W12 (`createUseUser`
+  / `createUseWishlist`) had **zero skill mentions** — the
+  pre-W12 manual approach was still the canonical doc. Cookie
+  passthrough helpers in `cookiePassthrough.ts` were **half-shipped**:
+  the deco-start side compiled, the apps-start providers it
+  references in its own docstring don't exist, and the migration
+  script never wired either.
+- **Decided: ship Wave 15-A as a single PR.** Drop the obsolete
+  emissions (G1/G2/G4/G5), expand `dead-runtime-shim` to catch
+  both the legacy inline shape (with `Runtime` export) and the
+  Wave-15-A canonical re-export shape (skip — desired form),
+  publish a `platform-hooks-factories.md` skill that supersedes
+  the stale README, and update plan + journal.
+- **Defer to Wave 15-B / 16:** (G3) promotion of the
+  `invoke.gen.ts` 170-LOC server-fn block to apps-start needs
+  research on TanStack Start's compiler scanning behaviour
+  (whether `createServerFn` can be transformed when it lives in
+  a node_module). (H1) full cookie-passthrough provider wiring
+  (`setRequestCookieProvider` / `setResponseCookieForwarder` in
+  apps-start, auto-wire in `setup.ts`) needs design. The 5
+  cross-site convergence promotions (`useSuggestions`,
+  `useOffer` factory, `Picture` unification, `clx`/`useSendEvent`
+  redirects, `relative()` extension) are now in the priority-2
+  backlog, sequenced after Wave 15-A merges.
+- **The double-check itself is a useful primitive.** "Did we
+  ship script/skill/audit coverage for everything we built?" run
+  against the framework + apps inventory consistently surfaces
+  these loops. Codify it: when promoting a new factory or
+  helper, the PR checklist must include "matching template
+  emit", "matching audit-rule expansion", "matching skill doc
+  entry". This is the kind of self-check that prevents the next
+  16-month-old stale skill.
+
 ### 2026-05-01 — Wave 14-A rescoped from three codemods to one based on real als data
 
 - **Pre-data plan vs post-data plan.** The plan called for three
@@ -984,6 +1036,98 @@ recipes in `references/htmx-rewrite.md`.
   not the import), but the import-removal would create dead
   references. Order is correct.
 
+### Wave 15-A (close template→audit loops + factories skill — Priority 2 follow-on) — 🟡 **IN FLIGHT**
+
+Triggered by the double-check audit on 2026-05-01: subagent sweeps over
+casaevideo-storefront + baggagio-tanstack revealed (a) the migration
+template was scaffolding code that the audit's `--fix` then removed,
+and (b) the W12 factory hooks (`createUseUser`, `createUseWishlist`)
+had no skill coverage. Wave 15-A closes both loops in one PR.
+
+**Shipped (one PR against `decocms/deco-start`):**
+
+37. `feat(migrate): close template→audit loops for vite plugins, runtime, cookies, branding + factories skill` 🟡 **WAITING ON CI**.
+    - **`templates/vite-config.ts`** — drop `site-manual-chunks` and
+      `deco-stub-meta-gen` plugin emissions. Both already live in
+      `decoVitePlugin()` (`src/vite/plugin.js`). The audit's
+      `obsolete-vite-plugins --fix` was undoing the template's own
+      output; now the template emits clean, the audit catches
+      regressions in legacy sites.
+    - **`templates/server-entry.ts` `generateRuntime()`** — replace
+      the 47-line inline `createNestedInvokeProxy` body with a 6-line
+      re-export from `@decocms/start/sdk`. Sites keep
+      `import { invoke } from "~/runtime"` and `Runtime.invoke`
+      shapes. A2 of the original investigation finally lands at the
+      template layer (was previously only patched post-migration by
+      the audit).
+    - **`templates/server-entry.ts` `generateInvoke()` (VTEX path)**
+      — replace inline `mergeSetCookies` helper with
+      `forwardResponseCookies` from
+      `@decocms/start/sdk/cookiePassthrough`. The framework helper
+      already shipped with try/catch for build-time safety.
+      `getVtexCookies` stays inline (it's auth-specific filtering, not
+      generic passthrough — see Wave 15-B/16 for full provider wiring
+      under H1).
+    - **`templates/routes.ts` + `templates/commerce-loaders.ts`** —
+      replace casaevideo-specific branding leaks ("Tudo para sua
+      casa…" tagline, "O melhor site de compras online…"
+      `productListPageCollection` SEO description) with
+      `${siteTitle}`-derived defaults plus `MIGRATION TODO` markers
+      pointing at the per-site customization spot. CMS `Site.seo`
+      overrides the defaults at runtime so leaving them visible in
+      pre-resolution states is the safe behaviour.
+    - **Audit rule expansion: `dead-runtime-shim`** — previously only
+      flagged when exports were exactly `{ invoke }` or
+      `{ invoke, createNestedInvokeProxy }`. Updated to detect (a)
+      inline `createNestedInvokeProxy` body via regex (catches the
+      legacy 47-line shape **with** `Runtime` export — which the old
+      heuristic missed entirely; this is the shape every existing
+      VTEX site has) and (b) skip the new Wave-15-A canonical
+      re-export shape (where `import invoke from
+      @decocms/start/sdk` is present and no inline proxy body
+      exists). Auto-fix is gated by `safeToAutoFix` metadata: legacy
+      shim shapes get the rewrite + delete; sites that mix the proxy
+      with custom helpers get a warning only. Three new tests.
+      **Verified against casaevideo-storefront**: now flags
+      `[invoke, Runtime] inline createNestedInvokeProxy body` (was
+      missed entirely before).
+    - **Skill: `references/platform-hooks-factories.md`** — new
+      canonical doc covering `createUseCart` / `createUseUser` /
+      `createUseWishlist`. Replaces the pre-W12 manual approach of
+      hand-rolling 200+ LOC of `createServerFn` wrappers per site.
+      Documents the 5-line shim shape, why factories instead of
+      direct hook imports (state isolation per site), non-VTEX
+      stubs using `@decocms/start/sdk/signal`, and the migration
+      path off the manual approach.
+    - **Skill update: `references/platform-hooks/README.md`** —
+      retained as legacy reference but now opens with a
+      "deprecated, see canonical" header pointing at the new doc.
+      The pre-W12 `createServerFn` examples are kept for sites that
+      haven't migrated to factories yet.
+    - **`SKILL.md` index update** — Phase 5 entry now points to the
+      factories doc; reference table lists both new + legacy paths.
+    - 342 → 345 tests pass, typecheck clean, smoke against casaevideo
+      + baggagio confirms expanded rule fires correctly on legacy
+      shapes and stays silent on baggagio (no `runtime.ts` file there).
+
+**Deferred to Wave 15-B / 16 (intentionally — see discoveries journal):**
+
+- **G3** — promote the 170-LOC `invoke.gen.ts` VTEX `createServerFn`
+  wrappers into `@decocms/apps/vtex/server-fns`. Needs research on
+  whether TanStack Start's compiler can transform `createServerFn`
+  call sites that live inside a node_module. Not safe to ship blind.
+- **H1** — full cookie-passthrough provider wiring
+  (`setRequestCookieProvider` / `setResponseCookieForwarder` in
+  apps-start, auto-wire in `templates/setup.ts`). The
+  `cookiePassthrough.ts` docstring already references this design but
+  the apps-start side doesn't exist. Needs a design pass to scope
+  what calls inside `vtex/utils/fetch.ts` need the provider hook
+  (currently each call site forwards cookies manually).
+- **Cross-site convergence promotions** (5 items) — `useSuggestions`,
+  `useOffer` factory, `Picture` API unification, redirect
+  `useSendEvent`/`clx`/location-matcher imports, `relative()`
+  SKU-stripping extension. Sequenced after 15-A merges.
+
 ### Wave 15+ (htmx cleanup PRs on als + propagation to other sites) — Priority 3 / 4
 
 Each htmx pattern that survives the codemod becomes a per-pattern PR

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.22.0",
+  "version": "2.23.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

@@ -462,6 +462,31 @@ function findAttachedLeadingComments(content: string, openIdx: number): number {
 /* Rule 3 — dead `src/runtime.ts` invoke shim                          */
 /* ------------------------------------------------------------------ */
 
+/**
+ * Detection covers two shapes of `src/runtime.ts`:
+ *
+ * 1. Legacy inline proxy (pre-Wave 15-A migration template) — defines
+ *    `createNestedInvokeProxy` plus `invoke` and `Runtime` constants.
+ *    The whole 40-50 LOC body duplicates `@decocms/start/sdk`'s `invoke`.
+ *
+ * 2. Simple re-export shim — the file only re-exports `invoke` /
+ *    `createNestedInvokeProxy` (no inline proxy body, but also not yet
+ *    pointing at `@decocms/start/sdk`).
+ *
+ * Both should be replaced with `import { invoke } from "@decocms/start/sdk"`
+ * at every callsite, and the file deleted. The Wave 15-A migration template
+ * scaffolds a thin re-export form that's also acceptable (re-exports
+ * `invoke` from `@decocms/start/sdk` and rebuilds `Runtime = { invoke }`);
+ * we explicitly skip it via the "imports invoke from @decocms/start/sdk
+ * AND no inline proxy" check below.
+ */
+const INLINE_PROXY_RE =
+  /(?:function|const)\s+createNestedInvokeProxy\b|new\s+Proxy\s*\(\s*Object\.assign\s*\(\s*async\s*\(\s*props/;
+const FRAMEWORK_INVOKE_IMPORT_RE =
+  /import\s+\{[^}]*\binvoke\b[^}]*\}\s+from\s+['"]@decocms\/start(?:\/sdk)?['"]/;
+
+const ALLOWED_RUNTIME_EXPORTS = new Set(["invoke", "createNestedInvokeProxy", "Runtime"]);
+
 const ruleDeadRuntimeShim: Rule = {
   id: "dead-runtime-shim",
   title: "Dead src/runtime.ts invoke shim",
@@ -469,24 +494,54 @@ const ruleDeadRuntimeShim: Rule = {
     const abs = `${siteDir}/src/runtime.ts`;
     if (!fs.exists(abs)) return [];
     const content = fs.readText(abs);
-    // Heuristic: if the file's only meaningful exports are `invoke` /
-    // `createNestedInvokeProxy`, it's purely a shim.
+
+    const hasInlineProxy = INLINE_PROXY_RE.test(content);
+    const reExportsFromFramework = FRAMEWORK_INVOKE_IMPORT_RE.test(content);
     const exports = extractExports(content);
-    const onlyInvokeShim =
-      exports.length > 0 && exports.every((e) => ["invoke", "createNestedInvokeProxy"].includes(e));
-    if (!onlyInvokeShim) return [];
+    const onlyKnownInvokeExports =
+      exports.length > 0 && exports.every((e) => ALLOWED_RUNTIME_EXPORTS.has(e));
+
+    // Wave 15-A canonical template: re-exports invoke from @decocms/start/sdk
+    // and exposes `Runtime = { invoke }` for legacy callers. No inline proxy
+    // body. This is the desired shape — skip.
+    if (reExportsFromFramework && !hasInlineProxy) return [];
+
+    // Site-specific helpers alongside invoke: don't flag — the file has its
+    // own purpose beyond shimming. (Old behavior preserved.)
+    if (!hasInlineProxy && !onlyKnownInvokeExports) return [];
+
+    const exportSummary = exports.length > 0 ? exports.join(", ") : "(re-exports only)";
+    const flavor = hasInlineProxy ? "inline createNestedInvokeProxy body" : "shim re-exports";
+    // Only safe to auto-delete when exports are pure invoke surface; if a
+    // legacy file mixes the inline proxy with custom helpers, we still flag
+    // it but skip the destructive fix.
+    const safeToAutoFix = onlyKnownInvokeExports;
+
     return [
       {
         rule: "dead-runtime-shim",
         severity: "info",
         file: "src/runtime.ts",
-        message: `Only re-exports invoke (${exports.join(", ")}) — replace with @decocms/start/sdk`,
-        fix: 'rg -l "from \\"~/runtime\\"" src/ | xargs sed -i \'\' \'s|from "~/runtime"|from "@decocms/start/sdk"|g\' && rm src/runtime.ts',
+        message: safeToAutoFix
+          ? `${flavor} [${exportSummary}] — replace with @decocms/start/sdk`
+          : `${flavor} [${exportSummary}] — manual review: file mixes the runtime proxy with site-specific exports`,
+        fix: safeToAutoFix
+          ? 'rg -l "from \\"~/runtime\\"" src/ | xargs sed -i \'\' \'s|from "~/runtime"|from "@decocms/start/sdk"|g\' && rm src/runtime.ts'
+          : "Move the inline `createNestedInvokeProxy` body to call @decocms/start/sdk's `invoke`; relocate site-specific helpers to a dedicated module before deleting src/runtime.ts",
+        meta: {
+          hasInlineProxy,
+          exports,
+          safeToAutoFix,
+        },
       },
     ];
   },
   applyFix(ctx, findings, writer): FixAction[] {
     if (findings.length === 0) return [];
+    // Honor the per-finding safety gate emitted by run() — never auto-delete
+    // a runtime.ts that mixes the proxy with site-specific helpers.
+    const safe = findings.every((f) => f.meta?.safeToAutoFix !== false);
+    if (!safe) return [];
     const updated = rewriteImportSpec(ctx, writer, "~/runtime", "@decocms/start/sdk");
     writer.deleteFile(`${ctx.siteDir}/src/runtime.ts`);
     return [

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

@@ -227,9 +227,11 @@ describe("rule: dead-runtime-shim", () => {
     const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
     expect(r.findings).toHaveLength(1);
     expect(r.findings[0].file).toBe("src/runtime.ts");
+    expect(r.findings[0].meta?.safeToAutoFix).toBe(true);
+    expect(r.findings[0].meta?.hasInlineProxy).toBe(true);
   });
 
-  it("does not flag a runtime.ts that exports site-specific helpers", () => {
+  it("does not flag a runtime.ts that exports site-specific helpers (no inline proxy)", () => {
     const fs = makeFs({
       "/site/src/runtime.ts": "export const invoke = {};\nexport const customHelper = () => 1;\n",
     });
@@ -237,6 +239,80 @@ describe("rule: dead-runtime-shim", () => {
     const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
     expect(r.findings).toEqual([]);
   });
+
+  it("does NOT flag the Wave 15-A canonical re-export shape", () => {
+    // The migration template now scaffolds a thin re-export from
+    // @decocms/start/sdk plus a Runtime alias. No inline proxy body.
+    const fs = makeFs({
+      "/site/src/runtime.ts":
+        'import { invoke } from "@decocms/start/sdk";\nexport { invoke };\nexport const Runtime = { invoke };\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("flags the legacy 47-line inline createNestedInvokeProxy body (with Runtime export)", () => {
+    // The pre-Wave-15-A migration template emitted a full Proxy body
+    // alongside `Runtime = { invoke }`. The earlier rule heuristic
+    // missed this shape because `Runtime` was not in its allowlist.
+    const fs = makeFs({
+      "/site/src/runtime.ts": `
+function createNestedInvokeProxy(path: string[] = []): any {
+  return new Proxy(
+    Object.assign(async (props: any) => {
+      const key = path.join("/");
+      const response = await fetch(\`/deco/invoke/\${key}\`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(props ?? {}),
+      });
+      return response.json();
+    }, {}),
+    {
+      get(_target: any, prop: string) {
+        if (prop === "then") return undefined;
+        return createNestedInvokeProxy([...path, prop]);
+      },
+    },
+  );
+}
+
+export const invoke = createNestedInvokeProxy() as any;
+export const Runtime = { invoke };
+`,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.hasInlineProxy).toBe(true);
+    expect(r.findings[0].meta?.safeToAutoFix).toBe(true);
+    expect(r.findings[0].message).toContain("inline createNestedInvokeProxy body");
+  });
+
+  it("flags but does NOT auto-fix when inline proxy coexists with site-specific helpers", () => {
+    // Defensive: if a site has hand-tuned the runtime file with extra
+    // exports beyond invoke/Runtime, deletion would lose data. Surface
+    // the issue but skip the destructive fix.
+    const fs = makeFs({
+      "/site/src/runtime.ts": `
+function createNestedInvokeProxy(path: string[] = []): any {
+  return new Proxy(Object.assign(async (props: any) => {}, {}), {});
+}
+export const invoke = createNestedInvokeProxy();
+export const trackPageView = () => console.log("custom tracker");
+`,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.hasInlineProxy).toBe(true);
+    expect(r.findings[0].meta?.safeToAutoFix).toBe(false);
+    expect(r.findings[0].message).toContain("manual review");
+    // applyFix should be a no-op when safeToAutoFix is false — verified
+    // implicitly by the runner test for --fix below; here we only
+    // assert the metadata gate.
+  });
 });
 
 describe("rule: site-local-with-globals", () => {

package/scripts/migrate/templates/commerce-loaders.ts

@@ -204,7 +204,8 @@ export function generateCommerceLoaders(ctx: MigrationContext): string {
       lines.push(`      breadcrumb: createBreadcrumbFromPath(url.pathname, url, collection.name) ?? {},`);
       lines.push(`      seo: {`);
       lines.push(`        title: collection.name,`);
-      lines.push(`        description: "O melhor site de compras online para sua casa: compre itens de cozinha, móveis para sala e escritório, acessórios de tecnologia e mais. Clique já!",`);
+      lines.push(`        // MIGRATION TODO: replace with site-specific category description`);
+      lines.push(`        description: collection.name,`);
       lines.push(`        noIndexing: false,`);
       lines.push(`        canonical: url.toString(),`);
       lines.push(`      },`);

package/scripts/migrate/templates/routes.ts

@@ -67,8 +67,10 @@ import { DecoRootLayout } from "@decocms/start/hooks";
 // @ts-ignore Vite ?url import
 import appCss from "../styles/app.css?url";
 
-const DEFAULT_DESCRIPTION =
-  "${siteTitle} - Tudo para sua casa com os melhores preços.";
+// MIGRATION TODO: customize description, OG image, and locale for ${siteTitle}.
+// The migration scaffold leaves a generic default so it never falls through;
+// CMS \`Site.seo\` overrides this once block resolution kicks in.
+const DEFAULT_DESCRIPTION = "${siteTitle}";
 
 export const Route = createRootRoute({
   head: () => ({
@@ -108,11 +110,14 @@ function generateIndex(ctx: MigrationContext, siteTitle: string): string {
 import { cmsHomeRouteConfig, deferredSectionLoader } from "@decocms/start/routes";
 import { DecoPageRenderer } from "@decocms/start/hooks";
 
+// MIGRATION TODO: customize defaultTitle / defaultDescription / fallback
+// copy below for ${siteTitle}. CMS \`Site.seo\` overrides these once block
+// resolution kicks in, so leaving the migration scaffold defaults is safe
+// but visible in pre-block-resolution states.
 export const Route = createFileRoute("/")({
   ...cmsHomeRouteConfig({
-    defaultTitle: "${siteTitle} - Tudo para sua casa",
-    defaultDescription:
-      "${siteTitle} - Tudo para sua casa com os melhores preços.",
+    defaultTitle: "${siteTitle}",
+    defaultDescription: "${siteTitle}",
     siteName: "${siteTitle}",
   }),
   component: HomePage,
@@ -126,8 +131,7 @@ function HomePage() {
       <div className="min-h-screen flex items-center justify-center">
         <div className="text-center">
           <h1 className="text-4xl font-bold mb-4">${siteTitle}</h1>
-          <p className="text-lg text-base-content/60">Tudo para sua casa</p>
-          <p className="text-sm text-base-content/40 mt-2">Nenhuma página CMS encontrada para /</p>
+          <p className="text-sm text-base-content/40 mt-2">No CMS page registered for /</p>
         </div>
       </div>
     );
@@ -152,11 +156,12 @@ function generateCatchAll(ctx: MigrationContext, siteTitle: string): string {
 import { cmsRouteConfig, deferredSectionLoader } from "@decocms/start/routes";
 import { DecoPageRenderer } from "@decocms/start/hooks";
 
+// MIGRATION TODO: customize defaultTitle / defaultDescription for ${siteTitle}
+// (CMS \`Site.seo\` overrides these per-page once block resolution kicks in).
 const routeConfig = cmsRouteConfig({
   siteName: "${siteTitle}",
-  defaultTitle: "${siteTitle} - Tudo para sua casa",
-  defaultDescription:
-    "${siteTitle} - Tudo para sua casa com os melhores preços.",
+  defaultTitle: "${siteTitle}",
+  defaultDescription: "${siteTitle}",
   ignoreSearchParams: ["skuId"],
 });
 

package/scripts/migrate/templates/server-entry.ts

@@ -216,50 +216,20 @@ declare module "@tanstack/react-router" {
 
 function generateRuntime(): string {
   return `/**
- * Runtime invoke proxy.
+ * Runtime invoke proxy — re-exports the framework canonical from @decocms/start/sdk.
  *
- * Turns nested property access into a typed RPC call to /deco/invoke.
- * Converts dot-notation paths to slash-separated keys:
- *   invoke.vtex.loaders.productList(props)
- *   → POST /deco/invoke/vtex/loaders/productList
+ * The implementation (typed RPC over /deco/invoke, dotted-path proxy, .ts
+ * suffix fallback) lives in @decocms/start/sdk/invoke. This file exists so
+ * existing site code can keep \`import { invoke } from "~/runtime"\` and
+ * \`Runtime.invoke\` shapes without churn.
  *
- * The .ts suffix variant is also tried if the primary key isn't found
- * (registered loaders may have ".ts" extensions in their keys).
+ * Don't reimplement here — extend @decocms/start/sdk/invoke instead.
  */
-function createNestedInvokeProxy(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(\`/deco/invoke/\${k}\`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(props ?? {}),
-        });
-        if (response.status === 404) continue;
-        if (!response.ok) {
-          throw new Error(\`invoke(\${k}) failed: \${response.status}\`);
-        }
-        return response.json();
-      }
-      throw new Error(\`invoke(\${key}) failed: handler not found\`);
-    }, {}),
-    {
-      get(_target: any, prop: string) {
-        if (prop === "then" || prop === "catch" || prop === "finally") {
-          return undefined;
-        }
-        return createNestedInvokeProxy([...path, prop]);
-      },
-    },
-  );
-}
+import { invoke } from "@decocms/start/sdk";
 
-export const invoke = createNestedInvokeProxy() as any;
+export { invoke };
 
-export const Runtime = {
-  invoke,
-};
+export const Runtime = { invoke };
 `;
 }
 
@@ -299,11 +269,8 @@ export const invoke = {} as const;
  * auto-generated in invoke.gen.ts. Run \`npm run generate:invoke\` to update.
  */
 import { createServerFn } from "@tanstack/react-start";
-import {
-  getRequestHeader,
-  getResponseHeaders,
-  setResponseHeader,
-} from "@tanstack/react-start/server";
+import { getRequestHeader } from "@tanstack/react-start/server";
+import { forwardResponseCookies } from "@decocms/start/sdk/cookiePassthrough";
 import { vtexActions } from "./invoke.gen";
 ${hasVtexAuthLoader ? `import vtexAuthLoader from "../loaders/vtex-auth-loader";\n` : ""}import {
   extractVtexCookiesFromHeader,
@@ -314,15 +281,6 @@ ${hasVtexAuthLoader ? `import vtexAuthLoader from "../loaders/vtex-auth-loader";
 
 export type { OrderForm } from "./invoke.gen";
 
-function mergeSetCookies(newCookies: string[]): void {
-  if (newCookies.length === 0) return;
-  const existing: string[] =
-    typeof getResponseHeaders().getSetCookie === "function"
-      ? getResponseHeaders().getSetCookie()
-      : [];
-  setResponseHeader("set-cookie", [...existing, ...newCookies]);
-}
-
 function getVtexCookies(): string {
   return extractVtexCookiesFromHeader(getRequestHeader("cookie") ?? "");
 }
@@ -336,7 +294,7 @@ ${hasVtexAuthLoader ? `const _vtexAuth = createServerFn({ method: "POST" })
     } as any);
     if (result instanceof Response) {
       const setCookies = result.headers.getSetCookie?.() ?? [];
-      mergeSetCookies(stripCookieDomain(setCookies));
+      forwardResponseCookies(stripCookieDomain(setCookies));
       return result.json();
     }
     return result;
@@ -344,7 +302,7 @@ ${hasVtexAuthLoader ? `const _vtexAuth = createServerFn({ method: "POST" })
 ` : ""}const _logout = createServerFn({ method: "POST" }).handler(
   async (): Promise<{ success: boolean }> => {
     const { setCookies } = await performVtexLogout(getVtexCookies());
-    mergeSetCookies(setCookies);
+    forwardResponseCookies(setCookies);
     return { success: true };
   },
 );

package/scripts/migrate/templates/vite-config.ts

@@ -53,41 +53,6 @@ export default defineConfig({
     }),
     tailwindcss(),
     decoVitePlugin(),
-    {
-      name: "site-manual-chunks",
-      config(_cfg, { command }) {
-        if (command !== "build") return;
-        return {
-          build: {
-            rollupOptions: {
-              output: {
-                manualChunks(id: string) {
-                  if (id.includes("node_modules/react-dom") || id.includes("node_modules/react/"))
-                    return "vendor-react";
-                  if (id.includes("@tanstack/react-router") || id.includes("@tanstack/start"))
-                    return "vendor-router";
-                  if (id.includes("@tanstack/react-query")) return "vendor-query";
-                },
-              },
-            },
-          },
-        };
-      },
-    },
-    {
-      name: "deco-stub-meta-gen",
-      enforce: "pre" as const,
-      resolveId(id, importer, options) {
-        if (!options?.ssr && importer && id.includes("meta.gen")) {
-          return "\\0stub:meta-gen";
-        }
-      },
-      load(id) {
-        if (id === "\\0stub:meta-gen") {
-          return "export default {};";
-        }
-      },
-    },
   ],
   build: {
     sourcemap: "hidden",