@decocms/start 2.27.0 → 2.28.1

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

@@ -1589,3 +1589,118 @@ Tested via Playwright (cursor-ide-browser MCP) on `https://baggagio-tanstack.dec
 - **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.27.0",
+  "version": "2.28.1",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/generate-blocks.ts

@@ -18,6 +18,12 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import {
+  blockHasPath,
+  type Candidate,
+  decodeBlockNameWithPasses,
+  mergeCandidates,
+} from "./lib/blocks-dedupe";
 
 const args = process.argv.slice(2);
 function arg(name: string, fallback: string): string {
@@ -29,20 +35,6 @@ const blocksDir = path.resolve(process.cwd(), arg("blocks-dir", ".deco/blocks"))
 const outFile = path.resolve(process.cwd(), arg("out-file", "src/server/cms/blocks.gen.ts"));
 const jsonFile = outFile.replace(/\.ts$/, ".json");
 
-function decodeBlockName(filename: string): string {
-  let name = filename.replace(/\.json$/, "");
-  while (name.includes("%")) {
-    try {
-      const next = decodeURIComponent(name);
-      if (next === name) break;
-      name = next;
-    } catch {
-      break; // literal % in the decoded name — nothing left to decode
-    }
-  }
-  return name;
-}
-
 const TS_STUB = [
   "// Auto-generated — thin wrapper around blocks.gen.json.",
   "// The Vite plugin replaces this at load time with JSON.parse(...).",
@@ -62,30 +54,53 @@ if (!fs.existsSync(blocksDir)) {
 
 const files = fs.readdirSync(blocksDir).filter((f) => f.endsWith(".json"));
 
-// Deduplicate: when multiple files decode to the same key, prefer the one
-// with actual content (largest file size wins over empty {} stubs).
-const blockFiles: Record<string, string> = {};
+// Read each file into a Candidate, then let the dedupe lib pick the winner
+// per decoded key and report any collisions. See `lib/blocks-dedupe.ts` for
+// the priority order and the rationale behind it (TL;DR: never use file size,
+// don't trust mtime alone in CI clones).
+const candidatesWithKeys: Array<{ candidate: Candidate; key: string }> = [];
 for (const file of files) {
-  const name = decodeBlockName(file);
-  if (blockFiles[name]) {
-    const existingSize = fs.statSync(path.join(blocksDir, blockFiles[name])).size;
-    const newSize = fs.statSync(path.join(blocksDir, file)).size;
-    if (newSize > existingSize) {
-      blockFiles[name] = file;
-    }
+  const { name, passes } = decodeBlockNameWithPasses(file);
+  const fp = path.join(blocksDir, file);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fs.readFileSync(fp, "utf-8"));
+  } catch (e) {
+    console.warn(`Failed to parse ${file}:`, e);
     continue;
   }
-  blockFiles[name] = file;
+  candidatesWithKeys.push({
+    key: name,
+    candidate: {
+      file,
+      passes,
+      mtimeMs: fs.statSync(fp).mtimeMs,
+      hasPath: blockHasPath(parsed),
+      parsed,
+    },
+  });
 }
 
-const blocks: Record<string, unknown> = {};
-for (const [name, file] of Object.entries(blockFiles)) {
-  try {
-    const content = fs.readFileSync(path.join(blocksDir, file), "utf-8");
-    blocks[name] = JSON.parse(content);
-  } catch (e) {
-    console.warn(`Failed to parse ${file}:`, e);
+const { winners, collisions } = mergeCandidates(candidatesWithKeys);
+
+if (collisions.length > 0) {
+  console.warn(
+    `Detected ${collisions.length} filename collision(s) in ${path.relative(process.cwd(), blocksDir)}:`,
+  );
+  for (const c of collisions) {
+    const losers = c.files.filter((f) => f !== c.winner);
+    console.warn(`  - ${c.key}`);
+    console.warn(`      winner: ${c.winner}`);
+    for (const l of losers) console.warn(`      ignore: ${l}`);
   }
+  console.warn("    Cause: multiple writers (manual sync vs deco-sync-bot) producing");
+  console.warn("    different filename encodings for the same logical key. Delete the");
+  console.warn("    stale file(s) listed under 'ignore' to silence this warning.");
+}
+
+const blocks: Record<string, unknown> = {};
+for (const [name, c] of Object.entries(winners)) {
+  blocks[name] = c.parsed;
 }
 
 fs.mkdirSync(path.dirname(outFile), { recursive: true });

package/scripts/lib/blocks-dedupe.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, it } from "vitest";
+import {
+  blockHasPath,
+  type Candidate,
+  decodeBlockName,
+  decodeBlockNameWithPasses,
+  mergeCandidates,
+  pickWinner,
+} from "./blocks-dedupe";
+
+const cand = (overrides: Partial<Candidate> & { file: string }): Candidate => ({
+  passes: 0,
+  mtimeMs: 0,
+  hasPath: true,
+  parsed: { path: "/" },
+  ...overrides,
+});
+
+describe("decodeBlockNameWithPasses", () => {
+  it("returns the literal key with a 0 pass count when filename has no encoding", () => {
+    expect(decodeBlockNameWithPasses("Header.json")).toEqual({ name: "Header", passes: 0 });
+  });
+
+  it("decodes a single layer of URL encoding", () => {
+    expect(decodeBlockNameWithPasses("pages-Home%20-%20LB-618509.json")).toEqual({
+      name: "pages-Home - LB-618509",
+      passes: 1,
+    });
+  });
+
+  it("decodes the bot's double-encoded scheme through to the literal key", () => {
+    // Bot encodes the raw prod URL-encoded key once: `encodeURIComponent("pages-Home%20-%20LB-618509")`.
+    expect(decodeBlockNameWithPasses("pages-Home%2520-%2520LB-618509.json")).toEqual({
+      name: "pages-Home - LB-618509",
+      passes: 2,
+    });
+  });
+
+  it("stops decoding when a literal % survives a round", () => {
+    // `%` alone isn't valid encoding — the loop catches the throw and stops.
+    expect(decodeBlockNameWithPasses("weird%percent.json")).toEqual({
+      name: "weird%percent",
+      passes: 0,
+    });
+  });
+});
+
+describe("decodeBlockName", () => {
+  it("matches decodeBlockNameWithPasses on the name", () => {
+    expect(decodeBlockName("pages-Home%2520-%2520LB-618509.json")).toBe("pages-Home - LB-618509");
+  });
+});
+
+describe("blockHasPath", () => {
+  it("returns true for live page blocks", () => {
+    expect(blockHasPath({ path: "/", sections: [] })).toBe(true);
+  });
+
+  it("returns false when path is null (zombie entry)", () => {
+    expect(blockHasPath({ path: null, sections: [] })).toBe(false);
+  });
+
+  it("returns false when path is missing", () => {
+    expect(blockHasPath({ sections: [] })).toBe(false);
+  });
+
+  it("returns false for empty path strings", () => {
+    expect(blockHasPath({ path: "" })).toBe(false);
+  });
+
+  it("returns false for non-objects", () => {
+    expect(blockHasPath(null)).toBe(false);
+    expect(blockHasPath("/")).toBe(false);
+  });
+});
+
+describe("pickWinner", () => {
+  it("prefers a candidate with a real path over a zombie", () => {
+    const live = cand({ file: "live.json", hasPath: true });
+    const zombie = cand({ file: "zombie.json", hasPath: false, parsed: { path: null } });
+    expect(pickWinner(live, zombie)).toBe(live);
+    expect(pickWinner(zombie, live)).toBe(live);
+  });
+
+  it("prefers higher decode-pass count when path-status matches", () => {
+    // The lebiscuit reproduction case: a stale single-encoded leftover with a
+    // newer mtime and larger size loses to the bot's double-encoded fresh file.
+    const stale = cand({
+      file: "pages-Home%20-%20LB-618509.json",
+      passes: 1,
+      mtimeMs: 2_000_000,
+    });
+    const fresh = cand({
+      file: "pages-Home%2520-%2520LB-618509.json",
+      passes: 2,
+      mtimeMs: 1_000_000,
+    });
+    expect(pickWinner(stale, fresh)).toBe(fresh);
+  });
+
+  it("falls through to mtime when pass count ties", () => {
+    const older = cand({ file: "a.json", passes: 1, mtimeMs: 1 });
+    const newer = cand({ file: "b.json", passes: 1, mtimeMs: 2 });
+    expect(pickWinner(older, newer)).toBe(newer);
+  });
+
+  it("falls through to lex filename when everything else ties", () => {
+    const a = cand({ file: "a.json", passes: 0, mtimeMs: 5 });
+    const b = cand({ file: "b.json", passes: 0, mtimeMs: 5 });
+    expect(pickWinner(a, b)).toBe(a);
+    expect(pickWinner(b, a)).toBe(a);
+  });
+});
+
+describe("mergeCandidates", () => {
+  it("returns each candidate unchanged when there are no collisions", () => {
+    const a = cand({ file: "Header.json" });
+    const b = cand({ file: "Footer.json" });
+    const result = mergeCandidates([
+      { candidate: a, key: "Header" },
+      { candidate: b, key: "Footer" },
+    ]);
+    expect(result.collisions).toEqual([]);
+    expect(result.winners).toEqual({ Header: a, Footer: b });
+  });
+
+  it("records a collision and picks the winner", () => {
+    const stale = cand({ file: "pages-Home%20-%20LB-618509.json", passes: 1, mtimeMs: 5 });
+    const fresh = cand({ file: "pages-Home%2520-%2520LB-618509.json", passes: 2, mtimeMs: 1 });
+    const result = mergeCandidates([
+      { candidate: stale, key: "pages-Home - LB-618509" },
+      { candidate: fresh, key: "pages-Home - LB-618509" },
+    ]);
+    expect(result.winners["pages-Home - LB-618509"]).toBe(fresh);
+    expect(result.collisions).toEqual([
+      {
+        key: "pages-Home - LB-618509",
+        files: ["pages-Home%20-%20LB-618509.json", "pages-Home%2520-%2520LB-618509.json"],
+        winner: "pages-Home%2520-%2520LB-618509.json",
+      },
+    ]);
+  });
+
+  it("collapses three-way collisions into one record without dropping the winner", () => {
+    const a = cand({ file: "a.json", passes: 0, mtimeMs: 1 });
+    const b = cand({ file: "b.json", passes: 1, mtimeMs: 2 });
+    const c = cand({ file: "c.json", passes: 2, mtimeMs: 3 });
+    const result = mergeCandidates([
+      { candidate: a, key: "k" },
+      { candidate: b, key: "k" },
+      { candidate: c, key: "k" },
+    ]);
+    expect(result.winners.k).toBe(c);
+    expect(result.collisions).toHaveLength(1);
+    expect(result.collisions[0].winner).toBe("c.json");
+    // a, b, and c should all be tracked (a and b as ignored, c as winner).
+    expect(new Set(result.collisions[0].files)).toEqual(new Set(["a.json", "b.json", "c.json"]));
+  });
+
+  it("prefers the live page over a zombie even when zombie has more passes", () => {
+    const livePlain = cand({
+      file: "Home.json",
+      passes: 0,
+      hasPath: true,
+      parsed: { path: "/" },
+    });
+    const zombieEncoded = cand({
+      file: "Home%2520.json",
+      passes: 2,
+      hasPath: false,
+      parsed: { path: null },
+    });
+    const result = mergeCandidates([
+      { candidate: zombieEncoded, key: "Home" },
+      { candidate: livePlain, key: "Home" },
+    ]);
+    expect(result.winners.Home).toBe(livePlain);
+  });
+});

package/scripts/lib/blocks-dedupe.ts

@@ -0,0 +1,128 @@
+/**
+ * Pure helpers used by `generate-blocks.ts` to choose between multiple files
+ * that decode to the same logical CMS block key.
+ *
+ * Background: the live decofile snapshot lives under `.deco/blocks/`, with
+ * one file per block. The filename is `encodeURIComponent(<rawProdKey>) +
+ * ".json"`. The Deco admin sometimes serves URL-encoded keys (e.g.
+ * `pages-Home%20-%20LB-618509`), so a single block can land on disk with
+ * different filenames depending on which writer produced it:
+ *
+ *   - The `deco-sync-bot` (CI) encodes the raw prod key as-is, producing
+ *     `pages-Home%2520-%2520LB-618509.json` (two decode passes back to the
+ *     literal key).
+ *   - The legacy manual `sync-decofile.ts` decoded keys to literal first,
+ *     so it wrote `pages-Home%20-%20LB-618509.json` (one decode pass).
+ *
+ * Both files decode to the same logical key, so the block generator must
+ * pick one. Picking by file size is wrong (a shrunk live page gives a
+ * smaller JSON than the stale older snapshot, so size silently prefers
+ * stale); picking by mtime alone is wrong (fresh `git clone` writes all
+ * files with the clone time and erases temporal ordering).
+ */
+
+export interface Candidate {
+  file: string;
+  passes: number;
+  mtimeMs: number;
+  hasPath: boolean;
+  parsed: unknown;
+}
+
+/**
+ * Repeatedly URL-decode the basename of `filename` until no `%` sequence
+ * remains. Returns the fully-decoded canonical key plus the number of
+ * decode rounds it took. Higher pass count = the writer encoded a key
+ * that itself contained `%XX` sequences = bot scheme. See module-level
+ * comment for why this matters.
+ */
+export function decodeBlockNameWithPasses(filename: string): {
+  name: string;
+  passes: number;
+} {
+  let name = filename.replace(/\.json$/, "");
+  let passes = 0;
+  while (name.includes("%")) {
+    try {
+      const next = decodeURIComponent(name);
+      if (next === name) break;
+      name = next;
+      passes++;
+    } catch {
+      break;
+    }
+  }
+  return { name, passes };
+}
+
+export function decodeBlockName(filename: string): string {
+  return decodeBlockNameWithPasses(filename).name;
+}
+
+/**
+ * Tie-break two candidates that decode to the same key. Priority:
+ *   1. Block has a non-null `path`     — beats zombie/orphan entries.
+ *   2. More decode passes              — bot's "encode raw prod key"
+ *                                        scheme wins over legacy
+ *                                        "decode-then-encode" leftovers
+ *                                        when prod uses URL-encoded keys
+ *                                        (the only case that collides).
+ *   3. Newer mtime                     — last-write-wins for same scheme.
+ *   4. Lexicographic filename          — deterministic last resort.
+ */
+export function pickWinner(a: Candidate, b: Candidate): Candidate {
+  if (a.hasPath !== b.hasPath) return a.hasPath ? a : b;
+  if (a.passes !== b.passes) return a.passes > b.passes ? a : b;
+  if (a.mtimeMs !== b.mtimeMs) return a.mtimeMs > b.mtimeMs ? a : b;
+  return a.file < b.file ? a : b;
+}
+
+/** True iff a parsed block JSON looks like a live page (non-empty `.path`). */
+export function blockHasPath(parsed: unknown): boolean {
+  return (
+    typeof parsed === "object" &&
+    parsed !== null &&
+    "path" in parsed &&
+    typeof (parsed as { path?: unknown }).path === "string" &&
+    (parsed as { path: string }).path.length > 0
+  );
+}
+
+export interface CollisionRecord {
+  key: string;
+  files: string[];
+  winner: string;
+}
+
+export interface MergeResult {
+  winners: Record<string, Candidate>;
+  collisions: CollisionRecord[];
+}
+
+/**
+ * Reduce a list of candidates into one winner per decoded key, recording
+ * every collision so the caller can surface it as a build warning.
+ */
+export function mergeCandidates(
+  candidates: Array<{ candidate: Candidate; key: string }>,
+): MergeResult {
+  const winners: Record<string, Candidate> = {};
+  // Track every file that decoded to a given key so three-way (and beyond)
+  // collisions don't lose the eventual winner from the file list.
+  const filesByKey: Record<string, string[]> = {};
+  for (const { candidate, key } of candidates) {
+    if (!filesByKey[key]) filesByKey[key] = [];
+    const list = filesByKey[key];
+    if (!list.includes(candidate.file)) list.push(candidate.file);
+
+    const existing = winners[key];
+    winners[key] = existing ? pickWinner(existing, candidate) : candidate;
+  }
+
+  const collisions: CollisionRecord[] = [];
+  for (const [key, files] of Object.entries(filesByKey)) {
+    if (files.length < 2) continue;
+    collisions.push({ key, files, winner: winners[key].file });
+  }
+  return { winners, collisions };
+}

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);
+  });
+});

package/src/cms/sectionMixins.ts

@@ -74,3 +74,58 @@ export function compose(...mixins: SectionLoaderFn[]): SectionLoaderFn {
     return result;
   };
 }
+
+/**
+ * Wraps a section module's exported `loader` so it can be composed alongside
+ * mixins like {@link withDevice}, {@link withMobile}, {@link withSearchParam}.
+ *
+ * The `modImport` argument is a lazy factory (typically `() => import("~/sections/...")`)
+ * — the module is loaded on first call. If the module does not export a
+ * `loader`, the original `props` are returned unchanged (no-op).
+ *
+ * Why this exists: the migrator and many sites lifted from Fresh declare a
+ * `loader` export on the section file (often re-exported from the inner
+ * component). That loader sets things like `url: req.url`, runs platform
+ * invocations, or calls the section's domain logic. If the section is wired
+ * in `registerSectionLoaders` with mixin-only (e.g. `withSearchParam()`),
+ * the section's own loader is silently *replaced* — its work never runs and
+ * its returned props are dropped.
+ *
+ * Compose this helper FIRST in the chain so mixin-injected props
+ * (`device`, `currentSearchParam`, …) are available to the section's loader,
+ * then the section's loader has the final word over what is returned.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   compose,
+ *   withMobile,
+ *   withSearchParam,
+ *   withSectionLoader,
+ * } from "@decocms/start/cms";
+ *
+ * registerSectionLoaders({
+ *   "site/sections/Product/SearchContainerV2.tsx": compose(
+ *     withMobile(),
+ *     withSearchParam(),
+ *     withSectionLoader(() => import("~/sections/Product/SearchContainerV2")),
+ *   ),
+ * });
+ * ```
+ */
+export function withSectionLoader(
+  modImport: () => Promise<unknown>,
+): SectionLoaderFn {
+  return async (props, req) => {
+    const mod = (await modImport()) as { loader?: unknown } | undefined;
+    const loader = mod?.loader;
+    if (typeof loader !== "function") return props;
+    try {
+      const result = await (loader as SectionLoaderFn)(props, req);
+      return result ?? props;
+    } catch (error) {
+      console.error("[withSectionLoader] section loader threw:", error);
+      return props;
+    }
+  };
+}