docs(migration-skill): farmrio-storefront wave — gotchas #52-#73, learnings-staging convention

[hugo-ccabral]

Summary

Consolidates the farmrio-storefront Fresh→TanStack migration's staged learnings (migration/learnings/, ~69 completed targets, coverage-verified against the live ledger) into this skill's reference docs, per the epic's own consolidation target (T40).

22 new numbered gotchas (#52–#73), each carrying Severity, Symptom, Root cause, Fix (with code), a discovery rg/grep command, and empirical farmrio evidence (file counts, byte deltas, before/after numbers, cross-refs). Distributed into the existing topic files rather than one new dump file, matching this repo's own index-per-topic convention:

File	New gotchas	Headline finding
async-rendering.md	#52–54, #73	Dead 3-arg ctx section loaders — 28-file sweep, one was a site-wide dead cookie-consent banner
hydration-fixes.md	#55–58	DeferredSectionWrapper skeleton remount/CLS (cross-ref #448) + a content-refresh-safe Lazy.tsx unwrap pattern
vtex-commerce.md	#59–64	CMS multivariate-flag resolver only recognizes 2 of 7 real resolveTypes — silently drops content (blocker)
css-styling.md	#65–67	Theme-conversion DaisyUI slot mismapping + v5's silent dark-theme bundling
worker-cloudflare.md	#68–71	Device-segmented edge-cache poisoning via SWR revalidation (novel); server-only secrets reachable from client bundle via the invoke dispatch table (security)
storefront-patterns.md	#72	sitemap.xml not auto-wired

references/migration-learnings-staging.md (new file) proposes the index-per-target-file learnings convention as the starting pattern for the next migration's own staging area — citing this epic's own flat LEARNINGS.md (282,249 bytes / 3,875 lines / 103 entries, costing target sessions 60k+ tokens just to search before it was restructured mid-epic on 2026-07-30) as the empirical case for adopting it from day one instead. Linked from SKILL.md's reference index.

Two gotchas (#55, #59) reference upstream PRs/issues already filed from this same migration: decocms/blocks#448 (DeferredSectionWrapper fix, open) and decocms/blocks#391 (URL param coercion, referenced by #61).

Codemod / audit-rule proposals for packages/blocks-cli

Proposal only (per this migration's own DoD, implementation is a bonus, not required) — each was hit ≥3 times independently across the farmrio migration:

1. Dead-arity section-loader detector — AST walk for 3-arg (props, req, ctx) loader exports, cross-referenced against registerSectionLoaders calls and each file's real __resolveType (not its file path) in blocks.gen.json. Would have caught all 28 candidate files in gotcha fix(migrate): ts-ignore → ts-expect-error + HTMX detection #52 at migration time.
2. typeof X === "function" guard sweep — flag this pattern on any value that originates from CMS section resolution (gotcha feat: unified cache profile system with SWR + SIE #54); recurred independently in 6+ files across the epic.
3. Controlled-input-missing-onChange sweep — checked={...} JSX prop with no sibling onChange (gotcha fix: wrap worker fetch in RequestContext.run() #58); found and fixed independently 3 separate times.
4. LoadingFallback wrapper-function → literal-alias codemod — rewrite export function LoadingFallback(props) { return <X {...props}/>; } to export const LoadingFallback = X; (gotcha feat: Chrome Performance trace comparison script #56).
5. Redirect self-loop lint rule — flag any blocks.gen.json redirect block where normalize(from) === normalize(to) after case-folding (gotcha fix(seo): always emit <meta name="robots"> in CMS page head #60); found 3 live instances across 2 targets once the check existed as an ad-hoc script.
6. Image-dimension backfill from source headers — generic migration-time step parsing real JPEG/PNG dimensions from each unique image URL's own file header and writing width/height back into CMS content, instead of leaving every un-dimensioned image to hit the CLS-safety-net fallback one page at a time (gotcha feat(otel): auto-instrument Workers via OTEL env vars #67).
7. deco-post-cleanup --strict comment/string-literal awareness — several existing audit rules (deco-cx-runtime-api, style-string-props, htmx-residue) are literal-substring scans with no AST/JSX awareness, so they false-positive on matches inside comments or inside a dangerouslySetInnerHTML HTML string. Farmrio counts: 7 comment-only false positives on one rule, 4 on another, 4-of-6 on a third.

Parity-destined findings

Filed separately against decocms/parity (issue, cross-linked from migration/learnings/INDEX.md in farmrio-storefront) rather than bundled into this PR — covers --fail-on requiring --ci, --pages not scoping flows, a banner-aspect-ratio check double-counting infinite-carousel clones, a lazy-section-presence heuristic incompatible with TanStack's transport, and LLM visual-diff hallucination on downscaled full-page screenshots.

Test plan

• Docs-only change — no code paths affected, nothing to typecheck or build
• Every new gotcha cross-checked against the current gotchas.md numbering (fix: add ./apps/autoconfig to package.json exports #51 was the prior max, confirmed via grep -rn "^## #\?[0-9]" *.md)
• Every code snippet reproduced from the source learnings files, not invented — cross-checked against the cited migration/learnings/T<ID>.md file in deco-sites/farmrio-storefront

🤖 Generated with Claude Code

---

Summary by cubic

Consolidates Farm Rio Fresh→TanStack migration learnings into this skill and adds 22 numbered gotchas (#52–#73). Also documents an index-per-target-file staging convention to keep future migrations fast and cheap.

• Adds gotchas across async/rendering, hydration, VTEX commerce, CSS/DaisyUI, Worker/Cloudflare, and storefront patterns, covering issues like pre-#305 3‑arg loader pitfalls, DeferredSectionWrapper CLS, multivariate resolver gaps, sitemap wiring, cache behavior, and a client-bundle secret leak. Cross‑refs: decocms/blocks#448 and decocms/blocks#391.
• Introduces references/migration-learnings-staging.md and links it from SKILL.md to replace flat learnings with an index-per-target approach.

Doc updates since review

• fix(migrate): ts-ignore → ts-expect-error + HTMX detection #52: Clarifies that @decocms/blocks now supports an optional 3rd ctx arg when registered; positions the fix as a ctx‑free alternative for pre‑#305 or unregistered loaders.
• feat: add ?asJson query param support to worker entry #61: Splits discovery into two valid rg commands.
• fix: update migration templates and auto-run app middleware #63: Corrects variant‑trim filter to use priceComponentType (not @type), ensuring installment entries are removed.
• fix(migrate): add VTEX/Shopify/commerce import rewrite rules #65: Adds runnable discovery steps (grep + jq) for DaisyUI slot mapping.
• feat: lightweight site template — framework extractions #66: Flags the dark‑theme auto‑bundling gotcha as DaisyUI v5‑only.
• fix(workerEntry): unblock edge caching from Set-Cookie, CDN headers, static assets #72: Adds a worker-entry.ts wiring example for /sitemap.xml and fixes the import path to @decocms/apps-vtex.

^{Written for commit 919eb12. Summary will update on new commits.}

[JonasJesus42]

Review — 6 issues found in gotchas #52–#73. No merge blocker, but a few points need fixing before the skill misleads future migrators.

[JonasJesus42]

#52 — description and Fix are outdated

The text says SectionLoaderFn takes 2 args and ctx is always undefined. That does not match the current code:

• packages/blocks/src/cms/sectionLoaders.ts:28 → ctx?: SectionLoaderContext (3-arg, optional)
• sectionLoaders.ts:433 → withPageContext passes buildSectionLoaderContext(req) as the third arg

In practice, 3-arg loaders using ctx.device already work as long as they are registered via registerSectionLoader. The Fix below telling the migrator to "rewrite to ctx-free" will cause them to remove code that was already correct.

Suggestion: add a status note at the top — e.g. "Framework updated: ctx is now properly passed; the Fix below is the safe ctx-free fallback for loaders that prefer to avoid ctx dependency."

[JonasJesus42]

#61 — broken shell regex (unbalanced parentheses)

The discovery command does not execute — Number.isFinite(rawPage and Number.isFinite(props\. open ( with no closing ) before the |:

# current (does not compile)
rg "props\.\w+ ?? .*[Pp]age|Number.isFinite(rawPage|Number.isFinite(props\." packages/apps-vtex/src

Suggestion: split into two valid rg calls:

rg "props\.\w+ \?\? .*[Pp]age" packages/apps-vtex/src
rg "Number\.isFinite\(props\." packages/apps-vtex/src

[JonasJesus42]

#63 — filter matches a type name that never appears in the data

buildPriceSpecification (gotcha #35, line ~110 in this same file) creates installment entries as:

{ "@type": "UnitPriceSpecification", priceComponentType: "https://schema.org/Installment" }

But the filter here checks p["@type"] !== "InstallmentPriceSpecification" — a type name that never appears in the data. Every entry passes the filter unchanged, so the payload is never trimmed and the goal of gotcha #63 is silently unmet.

Correct fix:

priceSpecification: o.priceSpecification?.filter(
  (p) => p.priceComponentType !== "https://schema.org/Installment"
),

[JonasJesus42]

#65 — discovery command is prose, not a shell command

This is the only gotcha among the 22 new ones without an executable bash code block — every other gotcha has a rg/grep one-liner. A minimal suggestion:

# generated CSS color vars
grep -oE "\-\-color-[a-z0-9-]+" dist/**/*.css | sort -u

# source theme keys (compare manually against the list above)
jq -r ".. | objects | select(has(\"mainColors\")) | .mainColors | keys[]" \
  .deco/blocks/*.json 2>/dev/null | sort -u

[JonasJesus42]

#66 — references DaisyUI v5 while the rest of the file is v4

The file header and existing gotchas (#37, #43, #65) consistently reference DaisyUI v4. This gotcha documents v5 behavior and uses v5 config syntax (@plugin "daisyui" { themes: light --default; }). A migrator working on a v4 project will be confused.

Suggestion: add a one-liner at the top of the section — e.g. "Applies when the migrated site targets DaisyUI v5. See #37 for the v4 equivalent" — to make clear this is not a contradiction with the rest of the file.

[JonasJesus42]

#72 — HIGH/SEO severity gotcha with no code example for the fix

Every other BLOCKER/HIGH gotcha across the files includes a working snippet. The fix text says "wire createVtexSitemapProxy() plus a /sitemap/deco.xml route as an extraSitemaps entry" but shows no code. The JSDoc in packages/apps-vtex/src/utils/sitemap.ts:213 already has the example ready:

import { createVtexSitemapProxy } from "@decocms/apps/vtex/utils/sitemap";

const proxySitemap = createVtexSitemapProxy({
  extraSitemaps: ["/sitemap/deco.xml"], // CMS-managed sitemap
});

createDecoWorkerEntry(serverEntry, {
  proxyHandler: async (request, url) => {
    const sitemap = await proxySitemap(request, url);
    if (sitemap) return sitemap;
    // ... rest of proxyHandler
    return null;
  },
});

Also: running curl -sI <candidate>/sitemap.xml early in the migration (before manual QA) catches this before it is forgotten.