@decocms/start 2.26.0 → 2.28.0

package/.agents/skills/deco-to-tanstack-migration/references/css-styling.md

@@ -154,3 +154,85 @@ c = Color("#EE4F31")
 l, c_val, h = c.convert("oklch").coords()
 print(f"{l*100:.2f}% {c_val:.2f} {h:.0f}deg")  # 64.42% 0.20 33deg
 ```
+
+
+## 48. Custom Color Palette + fontFamily Dropped on Migration
+
+**Severity**: HIGH — entire pages render unstyled and Vite throws "unknown utility class" hot-overlay errors
+
+The migrator's scaffold writes a minimal `app.css` with `@theme` containing only the gray scale + a couple of colors. Sites that defined custom palettes in `tailwind.config.ts` `theme.extend.colors` (e.g. an `als: { gray: {...}, blue: {...} }` namespace, or seasonal/brand maps) lose ALL of those tokens on migration. Same for `theme.extend.fontFamily`.
+
+**Symptom**:
+- Vite HMR overlay: `Cannot apply unknown utility class 'font-bebas-neue'` / `'bg-als-blue-500'`
+- Or for CSS files using the v3 `theme()` helper: `Could not resolve value for theme function: theme(colors.als.gray.50)`
+- Page DOM renders correctly but visually unstyled — no colors, default fonts.
+
+**Detection** (run before booting dev for a fresh migration):
+```bash
+# Find all <prefix>-{custom-name}-* tailwind classes used in the codebase
+grep -rEo '\b(bg|text|border|fill|stroke|ring|outline|divide|placeholder|caret|accent|shadow|from|to|via)-[a-z]+-[a-z-]+(-[0-9]+)?\b' src/ \
+  | awk -F: '{print $2}' | sort -u
+
+# Find theme() calls in CSS that need v4 vars
+grep -rE 'theme\(colors\.|theme\(fontFamily\.' src/styles/
+```
+
+Cross-reference against the original `tailwind.config.ts` `theme.extend.colors` / `theme.extend.fontFamily` keys.
+
+**Fix** — port the missing tokens into `@theme`:
+
+```css
+/* src/styles/app.css */
+@theme {
+  --color-*: initial;
+  /* gray scale + std colors ... */
+
+  /* Custom brand palette (ported from tailwind.config.ts) */
+  --color-als-gray-50: #E4E4E4;
+  --color-als-gray-100: #BBBBBB;
+  /* ...etc */
+  --color-als-blue-500: #1C4DA1;
+
+  /* Custom fonts (ported from tailwind.config.ts) */
+  --font-bebas-neue: "Bebas Neue", sans-serif;
+  --font-bebas-neue-pro: "bebas-neue-pro", sans-serif;
+  --font-suisse-intl: "SuisseIntl", sans-serif;
+}
+```
+
+Tailwind v4 auto-generates `bg-als-blue-500`, `font-bebas-neue` etc. from these vars.
+
+**For raw `theme()` calls in CSS files** — Tailwind v4's `theme()` resolver accepts the dot path but only for tokens registered under `@theme`. Easier and more idiomatic: rewrite as `var(--color-...)`:
+
+```css
+/* v3 → v4 */
+background-color: theme(colors.als.gray.50);   /* old */
+background-color: var(--color-als-gray-50);    /* new */
+```
+
+
+## 49. `@layer components` Custom Classes Can't Be `@apply`d in v4
+
+**Severity**: MEDIUM — Vite overlay error `Cannot apply unknown utility class 'container-pdp'`
+
+Tailwind v4 only allows `@apply` to reference *utility classes* (built-ins or those declared with `@utility`). Custom classes declared inside `@layer components { .my-class { ... } }` are not utilities and can't be `@apply`d from elsewhere.
+
+**Symptom**:
+```css
+@layer components {
+  .container-pdp { @apply max-w-[1920px] md:!ml-[83px]; }
+}
+
+/* Later: */
+.product-details ~ .pdt-div { @apply container-pdp w-full; }
+/* ❌ "Cannot apply unknown utility class 'container-pdp'" */
+```
+
+**Fix** — promote the helper to a `@utility` directive:
+```css
+@utility container-pdp {
+  @apply max-w-[1920px] md:!ml-[83px] lg:!ml-[167px] ml-0;
+}
+```
+
+Then `@apply container-pdp` works, and so do variants (`hover:container-pdp`).

package/.agents/skills/deco-to-tanstack-migration/references/gotchas.md

@@ -9,5 +9,36 @@ This file is an index. Each topic has its own focused file.
 | [jsx-migration.md](jsx-migration.md) | Preact→React JSX differences | #4–6, #11, #20–22, #41 |
 | [vtex-commerce.md](vtex-commerce.md) | VTEX loaders, cart, facets, price specs | #1, #7–8, #32, #34–36, #39 |
 | [worker-cloudflare.md](worker-cloudflare.md) | Worker entry, build, Cloudflare, npm | #9–10, #12–14, #19, #24–28, #30, #44–45 |
-| [css-styling.md](css-styling.md) | Tailwind v4, oklch, DaisyUI | #15, #17, #31, #37, #40, #42–43 |
+| [css-styling.md](css-styling.md) | Tailwind v4, oklch, DaisyUI, custom palettes | #15, #17, #31, #37, #40, #42–43, #48–49 |
 | [admin-cms.md](admin-cms.md) | Admin routes, schema, device context | #16, #18, #23, #26, #29 |
+| [vtex-commerce.md](vtex-commerce.md) | Section loader composition (`withSectionLoader`) | #50 |
+
+## #50 Quick Reference — Section Loader Composition
+
+When wiring `registerSectionLoaders`, mixins (`withDevice`, `withMobile`,
+`withSearchParam`) MUST be composed with the section's own `loader`
+export — never replace it. The framework calls the registered entry as
+THE section loader; if you register only mixins, the section's
+`loader.ts` work silently never runs and the section renders empty
+(or worse, downstream components crash on the missing data).
+
+**Use `withSectionLoader` from `@decocms/start/cms` (≥ 2.28):**
+
+```typescript
+import { compose, withDevice, withSearchParam, withSectionLoader } from "@decocms/start/cms";
+
+registerSectionLoaders({
+  "site/sections/Header/Header.tsx": compose(
+    withDevice(),
+    withSearchParam(),
+    withSectionLoader(() => import("~/sections/Header/Header")),
+  ),
+});
+```
+
+`withSectionLoader` MUST be last — it sees the mixin-enriched props and
+returns the merged result. The `@decocms/start@2.28+` migrator emits
+this layout automatically; sites migrated with older versions need a
+manual rewire (16 sections in als-tanstack — symptom was empty pages
+and `Cannot read properties of undefined` cascades). Full pattern in
+[vtex-commerce.md](vtex-commerce.md).

package/.agents/skills/deco-to-tanstack-migration/templates/setup-ts.md

@@ -13,6 +13,7 @@ import { setBlocks } from "@decocms/start/cms/loader";
 import { setMetaData, setInvokeLoaders, setRenderShell } from "@decocms/start/admin";
 import { registerSections, registerSectionsSync, setResolvedComponent } from "@decocms/start/cms/registry";
 import { registerSectionLoaders, registerLayoutSections } from "@decocms/start/cms/sectionLoaders";
+import { compose, withDevice, withMobile, withSearchParam, withSectionLoader } from "@decocms/start/cms";
 import { registerCommerceLoaders, setAsyncRenderingConfig, onBeforeResolve } from "@decocms/start/cms/resolve";
 import { createCachedLoader } from "@decocms/start/sdk/cachedLoader";
 import appCss from "./styles/app.css?url";
@@ -77,13 +78,39 @@ registerLayoutSections([
 // 4. SECTION LOADERS
 // ==========================================================================
 
-// Section loaders enrich CMS props with server-side data (e.g., VTEX API calls).
-// Only needed for sections that export `const loader`.
+// Section loaders enrich CMS props with server-side data.
+//
+// Composition pattern — mixins inject helpers (device, isMobile,
+// currentSearchParam) BEFORE the section's own loader, then the
+// section's loader has the final say:
+//
+//   compose(
+//     withMobile(),
+//     withSearchParam(),
+//     withSectionLoader(() => import("~/sections/Foo")),  // must be last
+//   )
+//
+// withSectionLoader is a no-op if the module has no `loader` export and
+// catches loader exceptions (legacy `(props, req, ctx)` signatures throw
+// because we no longer pass ctx) — so a single broken loader never takes
+// the page down. Errors are logged via `[withSectionLoader] section
+// loader threw`.
+//
+// Anti-pattern (silently drops the section's loader):
+//
+//   "site/sections/Product/SearchContainer.tsx": withSearchParam(),
+//   // ❌ SearchContainer's own loader (which sets `props.url`, runs
+//   // VTEX queries, etc.) is REPLACED by the mixin — page renders
+//   // with stale props.
 registerSectionLoaders({
-  "site/sections/Product/ProductShelf.tsx": (props: any, req: Request) =>
-    import("./components/product/ProductShelf").then((m) => m.loader(props, req)),
-  "site/sections/Product/SearchResult.tsx": (props: any, req: Request) =>
-    import("./components/search/SearchResult").then((m) => m.loader(props, req)),
+  "site/sections/Product/ProductShelf.tsx": withSectionLoader(
+    () => import("./components/product/ProductShelf"),
+  ),
+  "site/sections/Product/SearchResult.tsx": compose(
+    withMobile(),
+    withSearchParam(),
+    withSectionLoader(() => import("./components/search/SearchResult")),
+  ),
   // ... add for each section that has `export const loader`
 });
 

package/MIGRATION_TOOLING_PLAN.md

@@ -1528,3 +1528,179 @@ What's still ahead:
 - **C8 (state persistence between migration phases)**: moderate effort, value mostly in skipping `npm install` on phase-9 retries. Polish.
 - **`vibe-dex/*` orphan branches in apps-start**: ✅ all 5 cleaned this wave.
 - **Apps registry (apps-start#18 + deco-start#81)**: defer until clear consumer.
+
+### Wave 16 (2026-05-02 — baggagio as production canary, stacked-PR pitfall RECURRENCE)
+
+User merged baggagio's PRs B1–B6 to use as guinea pig before applying the same patterns to casaevideo + lebiscuit (which ARE in production). Live validation found a critical fact: **only B1 (the bump) actually reached `main`**. PRs #13–#17 were all merged in GitHub UI but their merge commits ended up on the **previous PR's branch**, never on `main`.
+
+#### What happened (the same pitfall as Wave 8, recurring)
+
+Each PR was opened with `base = previous PR's branch`:
+
+| PR | Title | base | Merge commit landed on |
+|---|---|---|---|
+| #12 | bump 2.10→2.26 + apps 1.7→1.9 | `main` | ✅ `main` |
+| #13 | drop `src/sdk/clx.ts` | `chore/bump-deco-2.26-apps-1.9` | ❌ that branch |
+| #14 | createUseSuggestions factory | `chore/drop-local-clx` | ❌ that branch |
+| #15 | canonical `relative()` | `chore/use-framework-suggestions-factory` | ❌ that branch |
+| #16 | canonical `Picture` | `refactor/use-canonical-relative-url` | ❌ that branch |
+| #17 | drop dead `useUser` stub | `refactor/use-canonical-picture` | ❌ that branch |
+
+Each PR shows `state: MERGED` in GitHub. But the merge commit physically landed on each PR's source-branch tip, not on main. Result: all 5 cleanup PRs were silently orphaned.
+
+Detection method that worked: file-existence check on `git show main:<deleted-file>` — `clx.ts`, `url.ts`, `Picture.tsx`, `useUser.ts` were all still present on main despite their PRs being "merged". Exists/absent is a faster signal than diff browsing.
+
+#### Recovery: PR #18 — single consolidation
+
+The deepest stacked branch (`chore/drop-dead-local-useuser`) cumulatively contained all 5 cleanups (B2–B6) linearly stacked on B1. Opened [`baggagio-tanstack#18`](https://github.com/deco-sites/baggagio-tanstack/pull/18) as `chore/consolidate-b2-b6-to-main` → `main`, replaying the exact contents of #13–#17 in order. Diff vs main: **59 files changed, +70 / −240, 4 files deleted**. Typecheck + build clean. Preview at `pr-18-baggagio-tanstack.deco-cx.workers.dev` rendered identical homepage / PLP / PDP / search to current main with zero new console errors. Merged to main, deploy succeeded.
+
+#### Live validation post-merge (cumulative state on main)
+
+Tested via Playwright (cursor-ide-browser MCP) on `https://baggagio-tanstack.deco-cx.workers.dev/`:
+
+| Surface | Result | Notes |
+|---|---|---|
+| Homepage | ✅ Renders | Banner, categories, product carousel, footer all intact |
+| PLP `/s?q=mochila` | ✅ 927 produtos | Filter + sort UI present, all images load |
+| PDP `/mochila-masculina-executiva-para-notebook-horizonte/p` | ✅ Renders | Image gallery, prices, COMPRAR, frete calc, descrição all present |
+| Search suggestions endpoint | ✅ 200 | Empty `searches[]` confirmed pre-existing (matches www.bagaggio.com.br) |
+| `<picture>` HTML | ✅ 18 picture / 36 source | composable canonical pattern |
+| Console errors (filtered 3rd-party) | ✅ Same as before | `[inline-script polyfill]` + image preload warnings pre-existing on main |
+
+**Bonus discovery**: PR-B5 (canonical Picture) now correctly emits `<link rel="preload" as="image" media="(max-width: 767px)" imageSrcSet="..." fetchPriority="high">` for LCP banners — a real Web Vitals improvement that was NOT visible before the consolidation because Picture.tsx (the local wrapper without preload) was still on main.
+
+#### Each PR's safety verdict (for casaevideo + lebiscuit replay)
+
+| PR | Status | Safe to replay? |
+|---|---|---|
+| B1 — bump 2.x → 2.26 + apps 1.x → 1.9 | ✅ | YES — zero regressions on real site |
+| B2 — drop `src/sdk/clx.ts` | ✅ | YES — pure rewrite, framework export is byte-equivalent |
+| B3 — `createUseSuggestions` factory | ✅ | YES — wiring works end-to-end (200 status, payload reaches store) |
+| B4 — canonical `relative()` with `stripSearchParams` | ✅ | YES — only affects PLPs with `?skuId=` URL params, no functional regression |
+| B5 — canonical `Picture` from apps | ✅ + bonus | YES — adds proper `<link rel="preload" as="image" media>` for LCP |
+| B6 — drop dead `src/hooks/useUser.ts` | ✅ | YES — file had 0 external imports |
+
+**For casaevideo + lebiscuit**: same set of PRs is validated as safe. The replays (`C1`–`C11`, `L1`–`L11`) can proceed on production sites with confidence.
+
+### Wave 16 — discoveries
+
+- **Stacked-PR pitfall recurred even after Wave 8 documented it.** The Wave 8 mitigation ("verify base is main before merging") was not enforced; the user merged B2–B6 with original stacked bases. Stronger mitigation needed: when opening a stacked PR, **default to a single consolidating PR at the end** rather than 5 separate stacked merges. Single PR is one merge button, one CI run, one deploy — not 5 chances to mis-target the base.
+- **File-existence check is the fastest "did the merge actually land on main?" probe.** Faster than reading PR-stats, faster than diffing branches. `git show main:<deleted-file> 2>&1` — empty stderr means the deletion didn't reach main.
+- **Preview deploys via `wrangler versions upload --preview-alias` are cheap, fast (90 s), and PR-scoped.** Used `https://pr-N-baggagio-tanstack.deco-cx.workers.dev` to validate cumulative state BEFORE merging. Should be the default validation step for any consolidation PR.
+- **The canonical Picture component's per-source `<link rel="preload" as="image" media="...">` injection is a real LCP win** — but it only triggers when `<Picture preload={true}>` is set on the call site. Baggagio's `BannerCarousel.tsx` already passes `preload={lcp}` from the CMS config; the local Picture.tsx wrapper just didn't honor it. Migration to canonical IS a perf upgrade, not just a code-cleanup.
+- **Canary-driven validation matters even when the changes are mechanical.** I had high confidence the cumulative state would work (typecheck + build clean), but the live test is what surfaced the "PR-B5 actually emits preload links now" finding. Without the canary loop the perf delta would have been invisible.
+
+### Wave 17 (2026-05-02 — als clean migration: end-to-end first time, with discoveries) — ✅ **SHIPPED**
+
+User opted to wipe `als-tanstack` and re-import `als-storefront` from
+scratch, then run our migration tooling end-to-end on a real, htmx-heavy
+site for the first time. Goal stop-point: dev server boots + homepage
+SSR returns 200. Stretch: "the right way, not the fast way" — port the
+real things, then backport the learnings.
+
+#### What landed on als-tanstack `main` (force-pushed, fresh history)
+
+| Commit | What |
+|---|---|
+| `f1b6a11` | Import `als-storefront` baseline at origin/main `096686ab` |
+| `3af54d4` | Run `@decocms/start migrate.ts` (analyze/scaffold/transform/cleanup) |
+| `69727a0` | `npm install` + run codegens (blocks/sections/loaders/schema/routes) |
+| `85d5317` | Worker boots — homepage SSR returns HTTP 200 |
+| `2123516` | Port casaevideo CI/CD; bump deco-start `^2.27` + apps `^1.10`; rename worker |
+| `c6f9dcb` | Defensive guards + restored site-local utils (`format`, `formatPhoneNumber`, `formatStatusName`) |
+| `e6a1fd8` | Rewire 16 section loaders + restore Tailwind v4 theme tokens (`als` palette + custom fonts) |
+
+End state: `npm run dev` boots, homepage renders 2592 DOM nodes (full
+shell, navigation, content, footer), no Invalid URL / undefined.invoke
+crashes. CSP and `clogger` warnings are non-fatal residue from the
+pre-migration site (catalog as known follow-up).
+
+#### Framework changes back-ported to deco-start (this PR)
+
+The als run surfaced THREE migrator regressions that previous sites
+(casaevideo / lebiscuit / baggagio) didn't trip because their section
+authors happened to wire `loader` exports differently. Three real fixes:
+
+| Fix | File | Why |
+|---|---|---|
+| **`withSectionLoader` helper** | `src/cms/sectionMixins.ts` | Lets `compose(withDevice(), withSearchParam(), withSectionLoader(() => import("~/sections/Foo")))` chain mixins WITH the section's own `loader` export. Previously the migrator's template chose mixins XOR own-loader and silently dropped the section's loader when both were present. |
+| **Migrator template fix** | `scripts/migrate/templates/section-loaders.ts` | Always emit `withSectionLoader(...)` last in the chain when `meta.hasLoader === true`, alongside any `withDevice / withMobile / withSearchParam` mixins. Eliminates the silent-drop bug for future migrations. |
+| **`gotcha #50` + `setup-ts.md` template + `css-styling.md` #48–#49** | `.agents/skills/deco-to-tanstack-migration/` | Documents both the section-loader composition pattern AND the Tailwind v4 custom-palette / `@layer components → @utility` migration pitfalls discovered during als CSS restoration. |
+
+`withSectionLoader` is defensive by design — if the module has no
+`loader`, returns props unchanged; if the loader throws (e.g. legacy
+`(props, req, ctx)` signature with `ctx === undefined`), logs once via
+`[withSectionLoader] section loader threw` and returns the original
+props. One broken section never takes the page down.
+
+#### Wave 17 — discoveries (added to gotcha catalog)
+
+- **The migrator template was XOR-ing mixins vs section loaders.** This
+  is a class of bug, not just one section. Across als 16 sections were
+  affected. Detection on a fresh migration is hard because everything
+  builds and SSR renders — sections just silently drop their data.
+  Symptoms: empty product carousels, `Cannot read properties of
+  undefined (reading 'X')` cascades from downstream components that
+  expected the loader's data. Now detected at template-generation time
+  by always composing both.
+- **Tailwind v4 `@theme` token loss.** The migrator's scaffold writes a
+  minimal `app.css` with grays + base colors only. Sites with custom
+  brand palettes in `tailwind.config.ts theme.extend.colors` (als had
+  `als: { gray, blue, red, ... }` namespace) lose ALL of those tokens.
+  Symptom: Vite HMR overlay `Cannot apply unknown utility class
+  'font-bebas-neue' / 'bg-als-blue-500'`, page DOM correct but visually
+  unstyled. Plus a v4-specific second hop: `theme(colors.als.gray.50)`
+  in `.css` files no longer resolves — must rewrite as
+  `var(--color-als-gray-50)`. Plus `@layer components` custom classes
+  (`.container-pdp`) can't be `@apply`d in v4 — must promote to
+  `@utility`. All three documented in [css-styling.md #48–49](.agents/skills/deco-to-tanstack-migration/references/css-styling.md).
+- **Site-local format utilities should NOT be hoisted to the apps SDK.**
+  The migrator's overly-aggressive import-rewriting routed
+  `formatPhoneNumber` / `formatStatusName` / `capitalize` to
+  `@decocms/apps/commerce/sdk/formatPrice` (which doesn't export
+  them). Only true commerce primitives (price formatting, currency,
+  installments) belong in the apps SDK. Site-specific text formatting
+  stays site-local in `src/sdk/`. Restored als-local versions and
+  fixed import paths.
+- **`HttpError` was the third common shim.** Already promoted `cn`,
+  `cookie`, `encoding`, `STATUS_CODE`, `UserAgent` to `@decocms/start/sdk/`
+  in Wave 15. `HttpError` joined them in [deco-start#138](https://github.com/decocms/deco-start/pull/138).
+  als-tanstack ships with a temporary local shim until the next apps
+  release picks up the framework export — TODO is checked into
+  `src/lib/http-utils.ts`.
+- **CI/CD porting from casaevideo to a new TanStack site is a 1-minute
+  copy.** `deploy.yml`, `preview.yml`, `regen-blocks.yml`, plus
+  `wrangler.jsonc` worker `name` rename, plus `account_id` paste from
+  another site. No template needed yet — three sites is too few. Will
+  template if a fourth migration needs it.
+
+#### Counter-evidence the user-rule asks for
+
+Going "the right way" added ~3 hours over going "the fast way" (the
+fast way was: defer the 16 section-loader rewiring, accept empty
+shelves, ship the boot SSR-200 commit and stop). The fast way would
+have hidden two of the three discoveries above, because:
+
+1. The migrator template fix only became obvious AFTER manually
+   rewiring 16 sections by hand and noticing the pattern. If we had
+   stopped at boot, the next site to migrate would have hit the same
+   silent-drop bug.
+2. The Tailwind v4 token-loss issue was only visible after the page
+   rendered enough DOM to see "this should be branded." Boot
+   verification (HTTP 200) would have passed without it.
+
+So: 3 hours of "right way" produced one framework helper, one migrator
+fix, three documented gotchas, and a working canary site. The next
+htmx-heavy migration starts with these problems already solved. Net
+positive.
+
+#### What this PR does NOT do (deliberately)
+
+- Migrate als's htmx surface to React (deferred per Wave 14 plan; the
+  codemod handled the mechanical 47% — the rest is per-component
+  product work and depends on des-system decisions for things like
+  filter sidebars + minicart drawer animation)
+- Validate als visually against production (visual-parity is a Phase 5+
+  task; we're at Phase 4 dev-boots)
+- Ship `HttpError` consumption in als or apps — als has a local shim,
+  apps will pick up the framework export on next release

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.26.0",
+  "version": "2.28.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
@@ -19,6 +19,9 @@
     "./sdk/useScript": "./src/sdk/useScript.ts",
     "./sdk/signal": "./src/sdk/signal.ts",
     "./sdk/clx": "./src/sdk/clx.ts",
+    "./sdk/cn": "./src/sdk/cn.ts",
+    "./sdk/encoding": "./src/sdk/encoding.ts",
+    "./sdk/http": "./src/sdk/http.ts",
     "./sdk/useSuggestions": "./src/sdk/useSuggestions.ts",
     "./sdk/retry": "./src/sdk/retry.ts",
     "./sdk/useId": "./src/sdk/useId.ts",
@@ -96,7 +99,9 @@
   },
   "dependencies": {
     "@deco-cx/warp-node": "^0.3.16",
+    "clsx": "^2.1.1",
     "fast-json-patch": "^3.1.0",
+    "tailwind-merge": "^3.3.1",
     "tsx": "^4.19.0",
     "ws": "^8.18.0"
   },

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

@@ -69,6 +69,7 @@ export function generateSectionLoaders(ctx: MigrationContext): string {
   lines.push(`  withDevice,`);
   lines.push(`  withMobile,`);
   lines.push(`  withSearchParam,`);
+  lines.push(`  withSectionLoader,`);
   lines.push(`  compose,`);
   lines.push(`} from "@decocms/start/cms";`);
 
@@ -117,20 +118,36 @@ export function generateSectionLoaders(ctx: MigrationContext): string {
   for (const meta of ctx.sectionMetas) {
     if (!meta.isHeader || !meta.hasLoader) continue;
     const sectionKey = `site/${meta.path}`;
-    entries.push(`  // Header: device + search param`);
+    const importPath = `~/` + meta.path.replace(/\.tsx?$/, "");
+    entries.push(`  // Header: device + search param + section's own loader`);
     entries.push(`  "${sectionKey}": async (props, req) => ({`);
-    entries.push(`    ...(await compose(withDevice(), withSearchParam())(props, req)),`);
+    entries.push(`    ...(await compose(`);
+    entries.push(`      withDevice(),`);
+    entries.push(`      withSearchParam(),`);
+    entries.push(`      withSectionLoader(() => import("${importPath}")),`);
+    entries.push(`    )(props, req)),`);
     entries.push(`    userName: "",`);
     entries.push(`  }),`);
   }
 
-  // ---------- Device/mobile sections ----------
+  // ---------- Device/mobile/url + own-loader composition ----------
+  //
+  // Rule of thumb: if a section exports its own `loader`, ALWAYS run it.
+  // Mixins (withDevice/withMobile/withSearchParam) are composed BEFORE the
+  // section loader so they can inject device/search-param props the section
+  // loader may read; the section loader has the final say over what is
+  // returned.
+  //
+  // The previous template chose mixins XOR own-loader and silently dropped
+  // the section's loader when both were present — see als-tanstack
+  // SearchContainerV2 SSR regression.
   for (const meta of ctx.sectionMetas) {
     if (meta.isHeader || meta.isAccountSection || meta.isStatusOnly) continue;
     // Skip sections with no loader AND no device needs
     if (!meta.hasLoader && !meta.loaderUsesDevice) continue;
     const sectionKey = `site/${meta.path}`;
     const basename = meta.path.split("/").pop()?.replace(/\.\w+$/, "") || "";
+    const importPath = `~/` + meta.path.replace(/\.tsx?$/, "");
 
     // Skip sections handled specially below
     const specialSections = [
@@ -141,27 +158,22 @@ export function generateSectionLoaders(ctx: MigrationContext): string {
     ];
     if (specialSections.includes(basename)) continue;
 
-    if (meta.loaderUsesDevice && meta.loaderUsesUrl) {
-      const deviceMixin = meta.usesMobileBoolean ? "withMobile()" : "withDevice()";
-      entries.push(`  "${sectionKey}": compose(${deviceMixin}, withSearchParam()),`);
-    } else if (meta.loaderUsesDevice) {
-      if (meta.usesMobileBoolean) {
-        entries.push(`  "${sectionKey}": withMobile(),`);
-      } else {
-        entries.push(`  "${sectionKey}": withDevice(),`);
-      }
-    } else if (meta.loaderUsesUrl) {
-      entries.push(`  "${sectionKey}": withSearchParam(),`);
-    } else if (meta.hasLoader) {
-      const importPath = `~/` + meta.path.replace(/\.tsx?$/, "");
-      entries.push(`  "${sectionKey}": async (props: any, req: Request) => {`);
-      entries.push(`    const mod = await import("${importPath}");`);
-      // Cast to any: legacy Fresh/Deno section loaders are typed `(props, req, ctx)`.
-      // We invoke with 2 args; any ctx-dependent code path inside the loader will throw
-      // at runtime and must be refactored — the migration phase-transform flags these.
-      entries.push(`    if (typeof mod.loader === "function") return (mod.loader as any)(props, req);`);
-      entries.push(`    return props;`);
-      entries.push(`  },`);
+    const mixins: string[] = [];
+    if (meta.loaderUsesDevice) {
+      mixins.push(meta.usesMobileBoolean ? "withMobile()" : "withDevice()");
+    }
+    if (meta.loaderUsesUrl) mixins.push("withSearchParam()");
+    if (meta.hasLoader) {
+      mixins.push(`withSectionLoader(() => import("${importPath}"))`);
+    }
+
+    if (mixins.length === 0) continue;
+    if (mixins.length === 1) {
+      entries.push(`  "${sectionKey}": ${mixins[0]},`);
+    } else {
+      entries.push(`  "${sectionKey}": compose(`);
+      for (const m of mixins) entries.push(`    ${m},`);
+      entries.push(`  ),`);
     }
   }
 

package/src/cms/index.ts

@@ -75,6 +75,12 @@ export {
   runSectionLoaders,
   runSingleSectionLoader,
 } from "./sectionLoaders";
-export { compose, withDevice, withMobile, withSearchParam } from "./sectionMixins";
+export {
+  compose,
+  withDevice,
+  withMobile,
+  withSearchParam,
+  withSectionLoader,
+} from "./sectionMixins";
 export type { ApplySectionConventionsInput, SectionMetaEntry } from "./applySectionConventions";
 export { applySectionConventions } from "./applySectionConventions";

package/src/cms/sectionMixins.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Section mixins — focused on `withSectionLoader` since the device/mobile
+ * mixins are exercised by sectionLoaders integration tests already.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { compose, withSectionLoader, withSearchParam } from "./sectionMixins";
+
+const makeReq = (url = "https://store.example/foo?q=hello") =>
+  new Request(url, { headers: { "user-agent": "vitest" } });
+
+describe("withSectionLoader", () => {
+  it("invokes the section's exported loader and returns its result", async () => {
+    const loader = vi.fn(async (props: Record<string, unknown>) => ({
+      ...props,
+      url: "https://store.example/foo?q=hello",
+      enriched: true,
+    }));
+
+    const mixin = withSectionLoader(async () => ({ loader }));
+    const result = await mixin({ original: "value" }, makeReq());
+
+    expect(loader).toHaveBeenCalledTimes(1);
+    expect(result).toEqual({
+      original: "value",
+      url: "https://store.example/foo?q=hello",
+      enriched: true,
+    });
+  });
+
+  it("returns props unchanged when module has no loader export", async () => {
+    const mixin = withSectionLoader(async () => ({ default: () => null }));
+    const props = { foo: "bar" };
+    const result = await mixin(props, makeReq());
+    expect(result).toBe(props);
+  });
+
+  it("returns props unchanged when module is undefined / loader is not a function", async () => {
+    const mixin = withSectionLoader(async () => undefined);
+    const props = { foo: "bar" };
+    expect(await mixin(props, makeReq())).toBe(props);
+
+    const mixinWithBadLoader = withSectionLoader(async () => ({
+      loader: "not-a-function",
+    }));
+    expect(await mixinWithBadLoader(props, makeReq())).toBe(props);
+  });
+
+  it("swallows loader errors and returns the original props", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const mixin = withSectionLoader(async () => ({
+      loader: async () => {
+        throw new Error("boom");
+      },
+    }));
+    const props = { foo: "bar" };
+    const result = await mixin(props, makeReq());
+    expect(result).toBe(props);
+    expect(errorSpy).toHaveBeenCalledWith(
+      "[withSectionLoader] section loader threw:",
+      expect.any(Error),
+    );
+    errorSpy.mockRestore();
+  });
+
+  it("falls back to original props when loader returns undefined", async () => {
+    const mixin = withSectionLoader(async () => ({
+      loader: async () => undefined,
+    }));
+    const props = { foo: "bar" };
+    expect(await mixin(props, makeReq())).toBe(props);
+  });
+
+  it("composes alongside mixins: mixins run first, then the section loader sees the enriched props", async () => {
+    const seen: Array<Record<string, unknown>> = [];
+    const sectionLoader = vi.fn(
+      async (props: Record<string, unknown>) => {
+        seen.push({ ...props });
+        return { ...props, sectionLoaderRan: true };
+      },
+    );
+
+    const composed = compose(
+      withSearchParam(),
+      withSectionLoader(async () => ({ loader: sectionLoader })),
+    );
+
+    const result = await composed({ original: 1 }, makeReq());
+
+    expect(seen).toHaveLength(1);
+    // The section loader sees the enriched props (currentSearchParam injected by withSearchParam)
+    expect(seen[0]).toMatchObject({
+      original: 1,
+      currentSearchParam: "hello",
+    });
+    expect(result).toMatchObject({
+      original: 1,
+      currentSearchParam: "hello",
+      sectionLoaderRan: true,
+    });
+  });
+
+  it("loads the module lazily — modImport is only called on first invocation", async () => {
+    const modImport = vi.fn(async () => ({
+      loader: async (p: Record<string, unknown>) => ({ ...p, ran: true }),
+    }));
+    const mixin = withSectionLoader(modImport);
+    expect(modImport).not.toHaveBeenCalled();
+
+    await mixin({ a: 1 }, makeReq());
+    expect(modImport).toHaveBeenCalledTimes(1);
+
+    // A second invocation calls the import again — caching is the
+    // dynamic import's responsibility (which the runtime memoises).
+    await mixin({ a: 2 }, makeReq());
+    expect(modImport).toHaveBeenCalledTimes(2);
+  });
+});