@decocms/start 0.32.3 → 0.33.0

package/FRAMEWORK_TODO.md

@@ -0,0 +1,110 @@
+# @decocms/start — Framework TODO
+
+Issues discovered during the portal-davinci migration script development.
+
+---
+
+## Tier 0 — Blocking migrations
+
+### `setup.ts` should be framework-injected
+- **Current**: Every site has a `setup.ts` with identical boilerplate (import.meta.glob, registerSections, setBlocks, registerBuiltinMatchers)
+- **Ideal**: Site declares only its custom loaders/actions. Framework injects the rest via Vite plugin or a single `createSiteSetup()` call
+- **Impact**: Migration script has to scaffold this file. Any framework change requires re-migrating all sites
+
+### `SiteTheme` component missing from `@decocms/start` or `@decocms/apps`
+- **Current**: `apps/website/components/Theme.tsx` was removed. Migration script scaffolds a local replacement
+- **Ideal**: Export `SiteTheme` from `@decocms/start/components/Theme` or `@decocms/apps/commerce/components/Theme`
+- **Impact**: Every migrated site gets a local copy that diverges over time
+
+---
+
+## Tier 1 — Developer experience
+
+### `useScript(fn)` hydration mismatch warning
+- **Current**: `useScript` calls `fn.toString()` which produces different output in SSR vs client builds (minification, variable renaming)
+- **Warning**: `[useScript] Using fn.toString() for "setup". This may produce different output in SSR vs client builds`
+- **Ideal**: Provide `inlineScript()` that accepts a plain string constant, or make `useScript` stable across builds
+- **Impact**: Console noise in every dev session, potential hydration bugs in production
+
+### Route files are 100% boilerplate
+- **Files**: `__root.tsx`, `index.tsx`, `$.tsx`, `deco/meta.ts`, `deco/invoke.$.ts`, `deco/render.ts`
+- **Current**: Migration script scaffolds identical route files for every site
+- **Ideal**: Framework provides a `createDecoRoutes()` or auto-generates via Vite plugin. Site only customizes (e.g. GTM ID, site name)
+- **Impact**: Route files are copy-pasted across sites and diverge
+
+### `server.ts`, `worker-entry.ts`, `router.tsx` are boilerplate
+- **Current**: Every site has identical server infrastructure files
+- **Ideal**: Single function call like `createDecoServer()` / `createDecoRouter()`. Or auto-generated by Vite plugin
+- **Impact**: Sites copy these files and never update them when framework improves
+
+### `dev:clean` script should be built into framework
+- **Current**: Migration script adds `"dev:clean": "rm -rf node_modules/.vite .wrangler/state .tanstack && vite dev"`
+- **Ideal**: `@decocms/start` CLI command or Vite plugin hook that auto-cleans stale caches on startup
+- **Impact**: Developers hit mysterious caching bugs and don't know to clean
+
+---
+
+## Tier 2 — Quality & correctness
+
+### GTM/Analytics SDK is duplicated across sites
+- **Current**: Every site has a custom `Session.tsx` with identical analytics SDK (data-event listeners, data-gtm-event listeners, IntersectionObserver)
+- **Ideal**: `@decocms/start/analytics` exports a `<DecoAnalytics gtmId="GTM-XXX" />` component used in `__root.tsx`
+- **Impact**: Analytics bugs are fixed per-site instead of once in the framework
+
+### `useGTMEvent` hook is universal
+- **Current**: Sites have a local `sdk/useGTMEvent.ts` that creates `data-gtm-event` / `data-gtm-trigger` attributes
+- **Ideal**: Export from `@decocms/start/analytics/useGTMEvent`
+- **Impact**: Same utility duplicated in every site
+
+### Negative z-index (`-z-10`) breaks in Tailwind v4 stacking contexts
+- **Current**: Migration script auto-fixes `-z-N` → `z-0` on images and adds `relative z-10` to content siblings
+- **Root cause**: React/TanStack wraps sections in `<section>` elements that create new stacking contexts. Negative z-index gets trapped inside
+- **Ideal**: Document this pattern. Consider framework-level CSS reset that prevents section wrappers from creating stacking contexts (e.g. `section { isolation: auto; }`)
+- **Impact**: Every migrated site has background images that are invisible until manually fixed
+
+### Tailwind v3 → v4 opacity classes
+- **Current**: Migration script converts `bg-black bg-opacity-20` → `bg-black/20`
+- **Edge cases**: Non-adjacent opacity classes (e.g. `bg-black flex ... hover:bg-opacity-30`) are harder to detect
+- **Ideal**: Provide a lint rule or postcss plugin that warns about orphaned opacity classes
+- **Impact**: Subtle visual bugs that are hard to spot
+
+---
+
+## Tier 3 — Nice to have
+
+### `registerLayoutSections` auto-detection
+- **Current**: Migration script detects Header/Footer/Theme by name pattern and adds to `registerLayoutSections()`
+- **Ideal**: Framework auto-detects layout sections from CMS page structure (sections that appear on every page = layout)
+- **Impact**: New sections added as layout require manual setup.ts update
+
+### Icon loaders (`availableIcons.ts`, `icons.ts`) depend on deleted `static/adminIcons.ts`
+- **Current**: Migration script deletes these loaders entirely
+- **Ideal**: Framework provides a built-in icon discovery mechanism (scan `public/sprites.svg` at build time)
+- **Impact**: Admin loses icon picker functionality after migration
+
+### `import.meta.glob` section discovery could be smarter
+- **Current**: Glob `./sections/**/*.tsx` discovers all files, including utility exports
+- **Ideal**: Use a convention (e.g. default export = section) or a marker comment to distinguish sections from helpers
+- **Impact**: Non-section files in `sections/` directory get registered as CMS sections
+
+---
+
+## Discovered during migration (portal-davinci)
+
+| Issue | Where | Status |
+|-------|-------|--------|
+| `scriptAsDataURI` → `useScript` leaves malformed JSX | `fresh-apis.ts` | Fixed in script |
+| `.test()` then `.replace()` regex bug (lastIndex statefulness) | All transforms | Fixed in script |
+| `site/` → `~/` doesn't strip `.tsx` extension | `imports.ts` | Fixed in script |
+| `class` in destructuring/interface not converted to `className` | `jsx.ts` | Fixed in script |
+| `for=` → `htmlFor=` missing | `jsx.ts` | Fixed in script |
+| `tabindex` → `tabIndex` missing | `jsx.ts` | Fixed in script |
+| Multi-line `className={clx()}` z-index insertion fails | `tailwind.ts` | Fixed in script |
+| `src/` directory scanned as source → `src/src/` created | `phase-analyze.ts` | Fixed in script |
+| `package.json`/`package-lock.json` treated as source files | `phase-analyze.ts` | Fixed in script |
+| `constants.ts` not deleted | `phase-analyze.ts` | Fixed in script |
+| `deno-lint-ignore` in JSX comments not removed | `deno-isms.ts` | Fixed in script |
+| `useDevice` import not split from `useScript` module | `imports.ts` | Fixed in script |
+| `@decocms/start/worker` wrong path → `@decocms/start/sdk/workerEntry` | `server-entry.ts` | Fixed in script |
+| `SiteTheme` / `Font` import removed by catch-all rule | `imports.ts` | Fixed in script |
+| Bootstrap failures silently ignored | `migrate.ts` | Fixed in script |

package/package.json

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

package/scripts/migrate/phase-analyze.ts

@@ -346,6 +346,53 @@ function extractSiteName(sourceDir: string): string {
   return dirName;
 }
 
+function extractThemeFromCms(sourceDir: string): { colors: Record<string, string>; fontFamily: string | null } {
+  const colors: Record<string, string> = {};
+  let fontFamily: string | null = null;
+
+  // Look for Theme config in .deco/blocks/
+  const blocksDir = path.join(sourceDir, ".deco", "blocks");
+  if (!fs.existsSync(blocksDir)) return { colors, fontFamily };
+
+  const files = fs.readdirSync(blocksDir);
+  for (const file of files) {
+    if (!file.endsWith(".json")) continue;
+    try {
+      const content = fs.readFileSync(path.join(blocksDir, file), "utf-8");
+      if (!content.includes("mainColors") && !content.includes("Theme")) continue;
+
+      const data = JSON.parse(content);
+      // Direct Theme block (e.g. Deco.json with __resolveType: "site/sections/Theme/Theme.tsx")
+      if (data.mainColors) {
+        Object.assign(colors, data.mainColors);
+        if (data.complementaryColors) {
+          Object.assign(colors, data.complementaryColors);
+        }
+      }
+      // Font
+      if (data.font?.fonts?.[0]?.family) {
+        fontFamily = data.font.fonts[0].family;
+      }
+      // Check sections array (page blocks may contain Theme)
+      if (data.sections) {
+        for (const section of data.sections) {
+          if (section.__resolveType?.includes("Theme") && section.mainColors) {
+            Object.assign(colors, section.mainColors);
+            if (section.complementaryColors) {
+              Object.assign(colors, section.complementaryColors);
+            }
+            if (section.font?.fonts?.[0]?.family) {
+              fontFamily = section.font.fonts[0].family;
+            }
+          }
+        }
+      }
+    } catch {}
+  }
+
+  return { colors, fontFamily };
+}
+
 export function analyze(ctx: MigrationContext): void {
   logPhase("Analyze");
 
@@ -365,9 +412,20 @@ export function analyze(ctx: MigrationContext): void {
   ctx.platform = extractPlatform(ctx.sourceDir);
   ctx.gtmId = extractGtmId(ctx.sourceDir);
 
+  // Extract theme colors and font from CMS
+  const theme = extractThemeFromCms(ctx.sourceDir);
+  ctx.themeColors = theme.colors;
+  ctx.fontFamily = theme.fontFamily;
+
   console.log(`  Site: ${ctx.siteName}`);
   console.log(`  Platform: ${ctx.platform}`);
   console.log(`  GTM ID: ${ctx.gtmId || "none"}`);
+  if (Object.keys(ctx.themeColors).length > 0) {
+    console.log(`  Theme: ${Object.keys(ctx.themeColors).length} colors from CMS`);
+  }
+  if (ctx.fontFamily) {
+    console.log(`  Font: ${ctx.fontFamily}`);
+  }
 
   // Scan all files
   scanDir(ctx.sourceDir, ctx.sourceDir, ctx.files);

package/scripts/migrate/phase-report.ts

@@ -114,6 +114,35 @@ export function report(ctx: MigrationContext): void {
   );
   lines.push("");
 
+  // Known Issues
+  lines.push("## Known Issues (Tailwind v3 → v4 + React)");
+  lines.push("");
+  lines.push("### Negative z-index on background images");
+  lines.push("");
+  lines.push("The migration script automatically converts `-z-{n}` to `z-0` on `<img>` and `<Image>` elements.");
+  lines.push("However, if you have **non-image elements** with negative z-index (e.g. `-z-10` on a `<div>` used as a background layer), they may become invisible.");
+  lines.push("");
+  lines.push("**Why it breaks:** In TanStack Start/React, section wrappers (`<section>`) or parent elements can create");
+  lines.push("CSS stacking contexts (via `animation`, `transform`, `will-change`, `filter`, `isolation`, etc.).");
+  lines.push("A child with negative z-index gets trapped inside that stacking context and renders behind the parent's background — making it invisible.");
+  lines.push("");
+  lines.push("**How to fix:**");
+  lines.push("1. Replace `-z-{n}` with `z-0` on the background element");
+  lines.push("2. Content siblings render on top naturally via DOM order (they come after in the HTML)");
+  lines.push("3. If needed, add `relative z-10` to content siblings to ensure they stay above");
+  lines.push("");
+  lines.push("**How to detect:** Search for remaining negative z-index: `grep -rn '\\-z-' src/ --include='*.tsx'`");
+  lines.push("");
+  lines.push("### Opacity utility classes");
+  lines.push("");
+  lines.push("Tailwind v4 removed `bg-opacity-{n}`, `text-opacity-{n}`, etc. The script converts them to");
+  lines.push("the modifier syntax (e.g. `bg-black bg-opacity-20` → `bg-black/20`). If a color and its opacity");
+  lines.push("are not in the same className string (e.g. set via different conditional branches), the script");
+  lines.push("flags them for manual review.");
+  lines.push("");
+  lines.push("**How to detect:** `grep -rn 'opacity-' src/ --include='*.tsx'`");
+  lines.push("");
+
   // Framework findings
   lines.push("## Framework Findings");
   lines.push("");

package/scripts/migrate/phase-scaffold.ts

@@ -68,6 +68,21 @@ export function scaffold(ctx: MigrationContext): void {
   // Apps
   writeFile(ctx, "src/apps/site.ts", generateSiteApp(ctx));
 
+  // SiteTheme component (replaces apps/website/components/Theme.tsx)
+  // Check if any source file uses SiteTheme
+  const usesSiteTheme = ctx.files.some((f) => {
+    if (f.action === "delete") return false;
+    try {
+      const content = fs.readFileSync(f.absPath, "utf-8");
+      return content.includes("SiteTheme");
+    } catch {
+      return false;
+    }
+  });
+  if (usesSiteTheme) {
+    writeFile(ctx, "src/components/ui/Theme.tsx", generateSiteThemeComponent());
+  }
+
   // Create public/ directory
   if (!ctx.dryRun) {
     fs.mkdirSync(path.join(ctx.sourceDir, "public"), { recursive: true });
@@ -76,7 +91,74 @@ export function scaffold(ctx: MigrationContext): void {
   console.log(`  Scaffolded ${ctx.scaffoldedFiles.length} files`);
 }
 
-function generateAppCss(_ctx: MigrationContext): string {
+function generateSiteThemeComponent(): string {
+  return `export interface Font {
+  family: string;
+  styleSheet?: string;
+}
+
+export interface Props {
+  colorScheme?: "light" | "dark" | "any";
+  fonts?: Font[];
+  variables?: Array<{ name: string; value: string }>;
+}
+
+/**
+ * SiteTheme — injects CSS custom properties and font stylesheets into the page.
+ * This replaces the old apps/website/components/Theme.tsx from the Deno stack.
+ */
+export default function SiteTheme({ variables, fonts, colorScheme }: Props) {
+  const cssVars = variables?.length
+    ? \`:root { \${variables.map((v) => \`\${v.name}: \${v.value};\`).join(" ")} }\`
+    : "";
+
+  const colorSchemeCss = colorScheme && colorScheme !== "any"
+    ? \`:root { color-scheme: \${colorScheme}; }\`
+    : "";
+
+  const css = [cssVars, colorSchemeCss].filter(Boolean).join("\\n");
+
+  return (
+    <>
+      {fonts?.map((font) =>
+        font.styleSheet ? (
+          <link key={font.family} rel="stylesheet" href={font.styleSheet} />
+        ) : null
+      )}
+      {css && <style dangerouslySetInnerHTML={{ __html: css }} />}
+    </>
+  );
+}
+
+export { type Font as SiteThemeFont };
+`;
+}
+
+function generateAppCss(ctx: MigrationContext): string {
+  const c = ctx.themeColors;
+  // Map CMS color names to DaisyUI v5 CSS variables
+  const colors: Record<string, string> = {
+    "--color-primary": c["primary"] || "#6B21A8",
+    "--color-secondary": c["secondary"] || "#141414",
+    "--color-accent": c["tertiary"] || "#FFF100",
+    "--color-neutral": c["neutral"] || "#393939",
+    "--color-base-100": c["base-100"] || "#FFFFFF",
+    "--color-base-200": c["base-200"] || "#F3F3F3",
+    "--color-base-300": c["base-300"] || "#868686",
+    "--color-info": c["info"] || "#006CA1",
+    "--color-success": c["success"] || "#007552",
+    "--color-warning": c["warning"] || "#F8D13A",
+    "--color-error": c["error"] || "#CF040A",
+  };
+  // Add content colors if specified
+  if (c["primary-content"]) colors["--color-primary-content"] = c["primary-content"];
+  if (c["secondary-content"]) colors["--color-secondary-content"] = c["secondary-content"];
+  if (c["base-content"]) colors["--color-base-content"] = c["base-content"];
+
+  const colorLines = Object.entries(colors)
+    .map(([k, v]) => `  ${k}: ${v};`)
+    .join("\n");
+
   return `@import "tailwindcss";
 @plugin "daisyui";
 @plugin "daisyui/theme" {
@@ -84,18 +166,7 @@ function generateAppCss(_ctx: MigrationContext): string {
   default: true;
   color-scheme: light;
 
-  /* TODO: Extract theme colors from the old Theme section's CMS config */
-  --color-primary: #6B21A8;
-  --color-secondary: #141414;
-  --color-accent: #FFF100;
-  --color-neutral: #393939;
-  --color-base-100: #FFFFFF;
-  --color-base-200: #F3F3F3;
-  --color-base-300: #868686;
-  --color-info: #006CA1;
-  --color-success: #007552;
-  --color-warning: #F8D13A;
-  --color-error: #CF040A;
+${colorLines}
 }
 
 @theme {
@@ -104,7 +175,7 @@ function generateAppCss(_ctx: MigrationContext): string {
   --color-black: #000;
   --color-transparent: transparent;
   --color-current: currentColor;
-  --color-inherit: inherit;
+  --color-inherit: inherit;${ctx.fontFamily ? `\n  --font-sans: "${ctx.fontFamily}", ui-sans-serif, system-ui, sans-serif;` : ""}
 }
 
 /* View transitions */

package/scripts/migrate/phase-verify.ts

@@ -230,6 +230,22 @@ const checks: Check[] = [
       return true;
     },
   },
+  {
+    name: "No negative z-index on non-image elements",
+    severity: "warning",
+    fn: (ctx) => {
+      const srcDir = path.join(ctx.sourceDir, "src");
+      if (!fs.existsSync(srcDir)) return true;
+      // Find -z-{n} that are NOT on img/Image elements (those are auto-fixed to z-0)
+      const bad = findFilesWithPattern(srcDir, /(?<!<(?:img|Image)[^>]*)-z-\d+/);
+      if (bad.length > 0) {
+        console.log(`    Negative z-index on non-image elements: ${bad.join(", ")}`);
+        console.log(`    These may be invisible due to stacking contexts. Replace with z-0 or positive z-index.`);
+        return false;
+      }
+      return true;
+    },
+  },
   {
     name: "No imports to deleted static files",
     severity: "error",

package/scripts/migrate/templates/routes.ts

@@ -147,7 +147,10 @@ ${gtmScript}
   return (
     <html lang="pt-BR" data-theme="light" suppressHydrationWarning>
       <head>
-        <HeadContent />
+        <HeadContent />${ctx.fontFamily ? `
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
+        <link href="https://fonts.googleapis.com/css2?family=${encodeURIComponent(ctx.fontFamily)}:wght@400;500;600;700&display=swap" rel="stylesheet" />` : ""}
       </head>
       <body className="bg-base-200 text-base-content" suppressHydrationWarning>
         <script dangerouslySetInnerHTML={{ __html: DECO_EVENTS_BOOTSTRAP }} />

package/scripts/migrate/templates/setup.ts

@@ -1,6 +1,36 @@
 import type { MigrationContext } from "../types.ts";
 
-export function generateSetup(_ctx: MigrationContext): string {
+export function generateSetup(ctx: MigrationContext): string {
+  // Detect layout sections (Header, Footer, Theme) from source files
+  const layoutSections: string[] = [];
+  for (const f of ctx.files) {
+    if (f.category !== "section" || f.action === "delete") continue;
+    const name = f.path.replace(/^sections\//, "").replace(/\.tsx$/, "");
+    const lower = name.toLowerCase();
+    if (lower.includes("header") || lower.includes("footer") || lower.includes("theme")) {
+      layoutSections.push(`site/sections/${name}.tsx`);
+    }
+  }
+  // Also check islands that became sections
+  for (const f of ctx.files) {
+    if (f.category !== "island") continue;
+    const name = f.path.replace(/^islands\//, "").replace(/\.tsx$/, "");
+    const lower = name.toLowerCase();
+    if (lower.includes("header") || lower.includes("footer") || lower.includes("theme")) {
+      layoutSections.push(`site/sections/${name}.tsx`);
+    }
+  }
+
+  const layoutRegistration = layoutSections.length > 0
+    ? `\n// -- Layout Sections (cached across navigations) --
+registerLayoutSections([
+${layoutSections.map((s) => `  "${s}",`).join("\n")}
+]);\n`
+    : "";
+
+  const layoutImport = layoutSections.length > 0
+    ? "\n  registerLayoutSections," : "";
+
   return `/**
  * Site setup — registers all sections, loaders and matchers with the CMS.
  *
@@ -9,7 +39,7 @@ export function generateSetup(_ctx: MigrationContext): string {
  */
 import { blocks as generatedBlocks } from "./server/cms/blocks.gen";
 import {
-  registerSections,
+  registerSections,${layoutImport}
   setBlocks,
 } from "@decocms/start/cms";
 import { registerBuiltinMatchers } from "@decocms/start/matchers/builtins";
@@ -28,7 +58,7 @@ for (const [path, loader] of Object.entries(sectionGlob)) {
   sections["site/" + path.slice(2)] = loader;
 }
 registerSections(sections);
-
+${layoutRegistration}
 // -- Matchers --
 registerBuiltinMatchers();
 `;

package/scripts/migrate/transforms/imports.ts

@@ -29,6 +29,7 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   [/^"apps\/website\/components\/Image\.tsx"$/, `"@decocms/apps/commerce/components/Image"`],
   [/^"apps\/website\/components\/Picture\.tsx"$/, `"@decocms/apps/commerce/components/Picture"`],
   [/^"apps\/website\/components\/Video\.tsx"$/, `"@decocms/apps/commerce/components/Video"`],
+  [/^"apps\/website\/components\/Theme\.tsx"$/, `"~/components/ui/Theme"`],
   [/^"apps\/commerce\/types\.ts"$/, `"@decocms/apps/commerce/types"`],
 
   // Apps — catch-all (things like apps/website/mod.ts, apps/vtex/mod.ts, etc.)

package/scripts/migrate/transforms/tailwind.ts

@@ -312,6 +312,52 @@ function hasOrderIssues(classes: string[]): boolean {
   return false;
 }
 
+// ── Fix opacity modifier classes within a class list ────────────
+// Handles non-adjacent cases like: "bg-black/50 flex ... hover:bg-opacity-30"
+// Finds the base color class and merges the opacity into it.
+function fixOrphanedOpacity(classList: string[]): { result: string[]; changes: string[] } {
+  const changes: string[] = [];
+  const prefixes = ["bg", "text", "border", "ring", "divide", "placeholder"];
+
+  // Find base color classes: bg-{color} or bg-{color}/{opacity}
+  const colorClasses: Record<string, { color: string; prefix: string }> = {};
+  for (const cls of classList) {
+    for (const pfx of prefixes) {
+      const match = cls.match(new RegExp(`^${pfx}-(\\w[\\w-]*?)(?:\\/(\\d+))?$`));
+      if (match && match[1] !== "opacity") {
+        colorClasses[pfx] = { color: match[1], prefix: pfx };
+      }
+    }
+  }
+
+  // Replace orphaned opacity classes with proper merged versions
+  const result: string[] = [];
+  for (const cls of classList) {
+    const opMatch = cls.match(/^((?:hover:|focus:|active:)*)(\w+)-opacity-(\d+)$/);
+    if (!opMatch) {
+      result.push(cls);
+      continue;
+    }
+
+    const modifier = opMatch[1]; // "hover:" or ""
+    const prefix = opMatch[2]; // "bg", "text", etc.
+    const opacity = opMatch[3]; // "20", "50", etc.
+
+    const base = colorClasses[prefix];
+    if (!base) {
+      result.push(cls); // No base color found, keep as-is
+      continue;
+    }
+
+    const opacityStr = opacity === "100" ? "" : `/${opacity}`;
+    const replacement = `${modifier}${prefix}-${base.color}${opacityStr}`;
+    result.push(replacement);
+    changes.push(`Merged ${cls} → ${replacement}`);
+  }
+
+  return { result, changes };
+}
+
 // ── Fix a className string ──────────────────────────────────────
 function fixClassNameString(classes: string): { fixed: string; changes: string[] } {
   const changes: string[] = [];
@@ -340,7 +386,14 @@ function fixClassNameString(classes: string): { fixed: string; changes: string[]
     return fixed;
   });
 
-  // 3. Fix responsive ordering
+  // 3. Fix orphaned opacity classes (non-adjacent to color class)
+  const opacityFix = fixOrphanedOpacity(classList);
+  if (opacityFix.changes.length > 0) {
+    classList = opacityFix.result;
+    changes.push(...opacityFix.changes);
+  }
+
+  // 4. Fix responsive ordering
   if (hasOrderIssues(classList)) {
     const reordered = fixResponsiveOrder(classList);
     if (reordered.join(" ") !== classList.join(" ")) {
@@ -352,6 +405,213 @@ function fixClassNameString(classes: string): { fixed: string; changes: string[]
   return { fixed: classList.join(" "), changes };
 }
 
+// ── Fix negative z-index on background images ──────────────────
+// In Tailwind v3, `-z-10` on an absolute image inside a relative parent worked
+// to push the image behind the parent's content. In Tailwind v4 + React,
+// stacking contexts from wrappers (section elements, animation, etc.) can trap
+// the negative z-index, making the image invisible.
+// Fix: replace `-z-{n}` with `z-0` on images. Since the image comes first in DOM,
+// content siblings (which have z-index: auto) render on top naturally.
+const NEG_Z_ON_IMAGE_REGEX = /\b-z-\d+\b/g;
+
+function fixNegativeZIndex(content: string): { content: string; changed: boolean; notes: string[] } {
+  const notes: string[] = [];
+  let changed = false;
+  let result = content;
+
+  // Step 1: Replace -z-{n} with z-0 on img/Image elements + add inset-0
+  result = result.replace(
+    /<(?:img|Image)\b[\s\S]*?(?:\/>|>)/g,
+    (tag) => {
+      if (!/-z-\d+/.test(tag)) return tag;
+      let fixed = tag.replace(/(?<=\s|"|`)-z-(\d+)\b/g, (m) => {
+        changed = true;
+        notes.push(`Background image: replaced ${m} with z-0`);
+        return "z-0";
+      });
+      // Add inset-0 if not present (ensures absolute image covers parent)
+      if (fixed.includes("absolute") && !fixed.includes("inset-0")) {
+        fixed = fixed.replace(/\babsolute\b/, "absolute inset-0");
+        notes.push("Added inset-0 to absolute background image");
+      }
+      return fixed;
+    },
+  );
+
+  // Step 2: When parent div has backgroundColor inline style + child img with z-0,
+  // extract backgroundColor into a separate overlay div and bump content to z-20.
+  // Use a simple two-pass approach to avoid JSX nesting issues:
+  //   a) Extract and remove backgroundColor from parent div
+  //   b) Insert overlay div before the content div (after the image conditional block)
+  if (changed && /style=\{\{[^}]*backgroundColor/.test(result)) {
+    const bgMatch = result.match(/style=\{\{\s*backgroundColor:\s*"([^"]+)"\s*\}\}/);
+    if (bgMatch) {
+      const bgValue = bgMatch[1];
+
+      // Remove the style attribute from the parent div
+      result = result.replace(/\s*style=\{\{\s*backgroundColor:\s*"[^"]+"\s*\}\}/, "");
+
+      // Insert overlay div. Find the closing of the image conditional block:
+      // Pattern: )} followed by whitespace then <div
+      // This handles {imageBg && (<Image ... />)}  <div content>
+      let insertedOverlay = false;
+
+      // Try pattern: )} then <div (conditional image)
+      if (/\)\}\s*\n\s*<div/.test(result)) {
+        result = result.replace(
+          /(\)\})([\s\n]*)(<div\b)/,
+          (m, closing, ws, divTag) => {
+            if (insertedOverlay) return m;
+            insertedOverlay = true;
+            return `${closing}${ws}{/* Overlay */}\n      <div className="absolute inset-0 z-10" style={{ backgroundColor: "${bgValue}" }} />${ws}${divTag}`;
+          },
+        );
+      }
+
+      // Try pattern: /> then <div (direct image, no conditional)
+      if (!insertedOverlay && /\/>\s*\n\s*<div/.test(result)) {
+        result = result.replace(
+          /(\/>\s*\n)([\s]*)(<div\b)/,
+          (m, closing, ws, divTag) => {
+            if (insertedOverlay) return m;
+            insertedOverlay = true;
+            return `${closing}${ws}{/* Overlay */}\n${ws}<div className="absolute inset-0 z-10" style={{ backgroundColor: "${bgValue}" }} />\n${ws}${divTag}`;
+          },
+        );
+      }
+
+      if (insertedOverlay) {
+        // Bump the first content div after the overlay to z-20.
+        // Find the overlay marker, then the next className= string after it.
+        const overlayMarker = `style={{ backgroundColor: "${bgValue}" }} />`;
+        const overlayIdx = result.indexOf(overlayMarker);
+        if (overlayIdx !== -1) {
+          const afterOverlay = result.substring(overlayIdx + overlayMarker.length);
+          // Find first className= after overlay (handles both className="..." and className={clx("...")})
+          const classMatch = afterOverlay.match(/className=(?:\{clx\(\s*)?[""`]([^""`]*)/);
+          if (classMatch && classMatch[1] && !/z-\d+/.test(classMatch[1])) {
+            const originalClass = classMatch[1];
+            const fixedClass = `relative z-20 ${originalClass}`;
+            // Replace only the first occurrence after the overlay
+            const beforeOverlay = result.substring(0, overlayIdx + overlayMarker.length);
+            const fixed = afterOverlay.replace(originalClass, fixedClass);
+            result = beforeOverlay + fixed;
+          }
+        }
+        notes.push(`Extracted backgroundColor overlay: ${bgValue}`);
+      }
+    }
+  }
+
+  // Step 3: For content divs that are siblings of z-0 images,
+  // add `relative z-10` so content renders above the background image.
+  // Uses a line-by-line approach to avoid regex issues with JSX nesting.
+  if (changed) {
+    const lines = result.split("\n");
+    let foundZ0Image = false;
+    let needsContentZIndex = false;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // Detect start of an image element (may span multiple lines)
+      if (/<(?:img|Image)\b/.test(line)) {
+        foundZ0Image = true;
+        if (/\bz-0\b/.test(line)) {
+          needsContentZIndex = true;
+        }
+        continue;
+      }
+      // Detect z-0 on a subsequent line of the image element
+      if (foundZ0Image && !needsContentZIndex && /\bz-0\b/.test(line)) {
+        needsContentZIndex = true;
+        continue;
+      }
+      // Detect end of multi-line image element (self-closing />)
+      if (foundZ0Image && !needsContentZIndex && /\/>/.test(line)) {
+        // Image closed without z-0, reset
+        foundZ0Image = false;
+        continue;
+      }
+
+      // When we hit the closing of an Image block, start looking for content div
+      if (foundZ0Image && /\)\}/.test(line)) {
+        // The conditional image block closed, content div should be next
+        continue;
+      }
+
+      // Skip overlay divs we inserted
+      if (/Overlay/.test(line)) continue;
+      if (/absolute inset-0 z-10/.test(line)) continue;
+
+      // Find the first content div after the image
+      if (needsContentZIndex && /^\s*<div\b/.test(line)) {
+        // Check if this div already has a z-index
+        if (/z-\d+/.test(line)) {
+          needsContentZIndex = false;
+          foundZ0Image = false;
+          continue;
+        }
+        // Also check the next few lines for z-index (multi-line className)
+        let hasZ = false;
+        for (let j = i; j < Math.min(i + 5, lines.length); j++) {
+          if (/z-\d+/.test(lines[j])) { hasZ = true; break; }
+          if (/>/.test(lines[j]) && j !== i) break;
+        }
+        if (hasZ) {
+          needsContentZIndex = false;
+          foundZ0Image = false;
+          continue;
+        }
+
+        // Add relative z-10 to the className — may be on this line or a subsequent one
+        let classLine = i;
+        for (let k = i; k < Math.min(i + 4, lines.length); k++) {
+          if (/className=/.test(lines[k])) {
+            classLine = k;
+            break;
+          }
+        }
+
+        if (/className="/.test(lines[classLine])) {
+          lines[classLine] = lines[classLine].replace(/className="/, 'className="relative z-10 ');
+          notes.push("Added relative z-10 to content div sibling of background image");
+        } else if (/className=\{clx\(/.test(lines[classLine])) {
+          // clx( may have its first string on the same line or the next
+          if (/className=\{clx\(\s*"/.test(lines[classLine])) {
+            lines[classLine] = lines[classLine].replace(/className=\{clx\(\s*"/, 'className={clx("relative z-10 ');
+          } else {
+            // First string argument is on the next line
+            for (let k = classLine + 1; k < Math.min(classLine + 3, lines.length); k++) {
+              if (/^\s*"/.test(lines[k])) {
+                lines[k] = lines[k].replace(/^(\s*)"/, '$1"relative z-10 ');
+                break;
+              }
+            }
+          }
+          notes.push("Added relative z-10 to content div sibling of background image");
+        } else if (/className=\{`/.test(lines[classLine])) {
+          lines[classLine] = lines[classLine].replace(/className=\{`/, 'className={`relative z-10 ');
+          notes.push("Added relative z-10 to content div sibling of background image");
+        }
+
+        needsContentZIndex = false;
+        foundZ0Image = false;
+      }
+    }
+
+    result = lines.join("\n");
+  }
+
+  // Step 4: Flag remaining -z-{n} on non-image elements for manual review
+  const remainingNegZ = result.match(/(?<=\s|"|`)-z-\d+/g);
+  if (remainingNegZ) {
+    notes.push(`MANUAL: ${remainingNegZ.length} remaining negative z-index usage(s) — may need manual fix for stacking context issues`);
+  }
+
+  return { content: result, changed, notes };
+}
+
 /**
  * Transform Tailwind classes in a file.
  *
@@ -366,6 +626,76 @@ export function transformTailwind(content: string): TransformResult {
   let changed = false;
   let result = content;
 
+  // ── Fix negative z-index on background images ──────────────────
+  const zFix = fixNegativeZIndex(result);
+  if (zFix.changed) {
+    result = zFix.content;
+    changed = true;
+    notes.push(...zFix.notes);
+  }
+
+  // ── Fix opacity utility pattern (Tailwind v4 breaking change) ──
+  // bg-black bg-opacity-20 → bg-black/20
+  // border-white border-opacity-20 → border-white/20
+  // text-gray-600 text-opacity-50 → text-gray-600/50
+  //
+  // The pattern is: {prefix}-{color} {prefix}-opacity-{N} → {prefix}-{color}/{N}
+  // prefix can be: bg, text, border, ring, divide, placeholder
+  if (/(?:bg|text|border|ring|divide|placeholder)-opacity-\d+/.test(result)) {
+    // Match: bg-{color} bg-opacity-{N}
+    result = result.replace(
+      /\b(bg-[\w-]+?)\s+bg-opacity-(\d+)/g,
+      "$1/$2",
+    );
+    // Match: text-{color} text-opacity-{N}
+    result = result.replace(
+      /\b(text-[\w-]+?)\s+text-opacity-(\d+)/g,
+      "$1/$2",
+    );
+    // Match: border-{color} border-opacity-{N}
+    result = result.replace(
+      /\b(border-[\w-]+?)\s+border-opacity-(\d+)/g,
+      "$1/$2",
+    );
+    // Match: ring-{color} ring-opacity-{N}
+    result = result.replace(
+      /\b(ring-[\w-]+?)\s+ring-opacity-(\d+)/g,
+      "$1/$2",
+    );
+    // Match: divide-{color} divide-opacity-{N}
+    result = result.replace(
+      /\b(divide-[\w-]+?)\s+divide-opacity-(\d+)/g,
+      "$1/$2",
+    );
+    // Match: placeholder-{color} placeholder-opacity-{N}
+    result = result.replace(
+      /\b(placeholder-[\w-]+?)\s+placeholder-opacity-(\d+)/g,
+      "$1/$2",
+    );
+    // Handle hover:/focus:/active: prefixed opacity (e.g. hover:bg-opacity-100)
+    result = result.replace(
+      /\b((?:hover:|focus:|active:)(?:bg|text|border|ring)-[\w-]+?)\s+(?:hover:|focus:|active:)(?:bg|text|border|ring)-opacity-(\d+)/g,
+      "$1/$2",
+    );
+    // Handle hover:bg-opacity-N when bg-{color}/{N} already exists
+    // e.g. "bg-white/80 hover:bg-opacity-100" → "bg-white/80 hover:bg-white"
+    // e.g. "bg-black/60 hover:bg-opacity-50" → "bg-black/60 hover:bg-black/50"
+    result = result.replace(
+      /\b(bg|text|border|ring)-([\w-]+?)\/(\d+)\s+((?:hover:|focus:|active:)+)\1-opacity-(\d+)/g,
+      (_m, prefix, color, _baseOp, modifier, hoverOp) => {
+        const opacityStr = hoverOp === "100" ? "" : `/${hoverOp}`;
+        return `${prefix}-${color}/${_baseOp} ${modifier}${prefix}-${color}${opacityStr}`;
+      },
+    );
+
+    // Handle standalone orphaned opacity classes that weren't caught
+    if (/(?:bg|text|border|ring)-opacity-\d+/.test(result)) {
+      notes.push("MANUAL: Some *-opacity-N classes remain — color class may not be adjacent");
+    }
+    changed = true;
+    notes.push("Converted *-opacity-N to modifier syntax (e.g. bg-black/20)");
+  }
+
   // Match className="...", className={`...`}, class="..."
   const patterns = [
     /(?<=className\s*=\s*")([^"]+)(?=")/g,

package/scripts/migrate/types.ts

@@ -75,6 +75,11 @@ export interface MigrationContext {
   /** npm dependencies discovered from inline npm: imports in source files */
   discoveredNpmDeps: Record<string, string>;
 
+  /** Theme colors extracted from .deco/blocks CMS config */
+  themeColors: Record<string, string>;
+  /** Font family from CMS config */
+  fontFamily: string | null;
+
   /** All categorized source files */
   files: FileRecord[];
 
@@ -118,6 +123,8 @@ export function createContext(
     gtmId: null,
     importMap: {},
     discoveredNpmDeps: {},
+    themeColors: {},
+    fontFamily: null,
     files: [],
     scaffoldedFiles: [],
     transformedFiles: [],