@decocms/start 1.6.2 → 1.7.0

package/scripts/migrate/phase-scaffold.ts

@@ -18,6 +18,7 @@ import { generateCommerceLoaders } from "./templates/commerce-loaders.ts";
 import { generateSectionLoaders } from "./templates/section-loaders.ts";
 import { generateCacheConfig } from "./templates/cache-config.ts";
 import { generateSdkFiles } from "./templates/sdk-gen.ts";
+import { generateLibUtils } from "./templates/lib-utils.ts";
 import { extractTheme } from "./analyzers/theme-extractor.ts";
 
 function writeFile(ctx: MigrationContext, relPath: string, content: string) {
@@ -67,6 +68,20 @@ export function scaffold(ctx: MigrationContext): void {
   // Route files
   writeMultiFile(ctx, generateRoutes(ctx));
 
+  // Secrets — extract env vars referenced by source AppContext
+  // Must be generated BEFORE commerce-loaders and section-loaders since
+  // those templates check for the secrets file to wire `...secrets` spreads.
+  writeFile(ctx, "src/utils/secrets.ts", generateSecrets(ctx));
+
+  // Apps
+  writeFile(ctx, "src/apps/site.ts", generateSiteApp(ctx));
+
+  // account.json is copied from source (if exists) or generated as fallback
+  if (!ctx.files.some((f) => f.path === "account.json" && f.action !== "delete")) {
+    const accountName = ctx.vtexAccount || ctx.siteName;
+    writeFile(ctx, "src/account.json", JSON.stringify(accountName));
+  }
+
   // Setup infrastructure
   writeFile(ctx, "src/setup.ts", generateSetup(ctx));
   writeFile(ctx, "src/cache-config.ts", generateCacheConfig(ctx));
@@ -90,10 +105,21 @@ export function scaffold(ctx: MigrationContext): void {
   writeFile(ctx, "src/sdk/signal.ts", generateSignalShim());
   writeFile(ctx, "src/sdk/clx.ts", generateClxShim());
   writeFile(ctx, "src/sdk/debounce.ts", generateDebounceShim());
+  writeFile(ctx, "src/sdk/logger.ts", generateLoggerStub());
   writeMultiFile(ctx, generateSdkFiles(ctx));
 
-  // Apps
-  writeFile(ctx, "src/apps/site.ts", generateSiteApp(ctx));
+  // VTEX utility wrappers (signature-compatible stubs for custom loaders)
+  writeMultiFile(ctx, generateLibUtils(ctx));
+
+  // Replace Context-based useDevice with SSR-safe useSyncExternalStore version.
+  // @decocms/start shell-renders sections in a separate React root without
+  // Device.Provider, so the old createContext pattern throws during SSR.
+  writeFile(ctx, "src/contexts/device.tsx", generateDeviceContext());
+
+  // Location matcher — server-side geolocation matching
+  if (hasLocationMatcher(ctx)) {
+    writeFile(ctx, "src/matchers/location.ts", generateLocationMatcher());
+  }
 
   // SiteTheme component (replaces apps/website/components/Theme.tsx)
   const usesSiteTheme = ctx.files.some((f) => {
@@ -204,6 +230,17 @@ export default clx;
 `;
 }
 
+function generateLoggerStub(): string {
+  return `export const logger = {
+  error: console.error,
+  warn: console.warn,
+  info: console.info,
+  debug: console.debug,
+  log: console.log,
+};
+`;
+}
+
 function generateDebounceShim(): string {
   return `/** Debounce a function call — drop-in replacement for Deno std/async/debounce */
 export function debounce<T extends (...args: any[]) => any>(
@@ -235,17 +272,102 @@ export default debounce;
 }
 
 function generateSignalShim(): string {
-  return `export { signal, type ReactiveSignal } from "@decocms/start/sdk/signal";
+  return `import { useState, useRef, useEffect, useMemo, useCallback } from "react";
+export { signal, type ReactiveSignal } from "@decocms/start/sdk/signal";
 
 /** Run a function immediately. Kept for legacy module-level side effects. */
 export function effect(fn: () => void | (() => void)): () => void {
   const cleanup = fn();
   return typeof cleanup === "function" ? cleanup : () => {};
 }
+
+/**
+ * React shim for @preact/signals' useSignal.
+ * Returns a mutable ref-like object with a .value property that triggers re-renders.
+ */
+export function useSignal<T>(initialValue: T): { value: T } {
+  const [value, setValue] = useState<T>(initialValue);
+  const ref = useRef(value);
+  ref.current = value;
+  return useMemo(
+    () => ({
+      get value() { return ref.current; },
+      set value(v: T) {
+        ref.current = v;
+        setValue(v);
+      },
+    }),
+    [],
+  );
+}
+
+/**
+ * React shim for @preact/signals' useComputed.
+ * Re-evaluates when deps change (but since we don't track signals, it runs every render).
+ */
+export function useComputed<T>(compute: () => T): { readonly value: T } {
+  const [value, setValue] = useState<T>(compute);
+  useEffect(() => { setValue(compute()); });
+  return useMemo(() => ({ get value() { return value; } }), [value]);
+}
+
+/**
+ * React shim for @preact/signals' useSignalEffect.
+ * Runs the callback as a useEffect (no automatic signal tracking).
+ */
+export function useSignalEffect(cb: () => void | (() => void)): void {
+  useEffect(cb);
+}
+`;
+}
+
+function generateDeviceContext(): string {
+  return `import { useSyncExternalStore } from "react";
+
+const MOBILE_QUERY = "(max-width: 767px)";
+
+function subscribe(cb: () => void) {
+  if (typeof window === "undefined") return () => {};
+  const mql = window.matchMedia(MOBILE_QUERY);
+  mql.addEventListener("change", cb);
+  return () => mql.removeEventListener("change", cb);
+}
+
+function getSnapshot(): boolean {
+  return window.matchMedia(MOBILE_QUERY).matches;
+}
+
+function getServerSnapshot(): boolean {
+  return false;
+}
+
+/**
+ * Reactive mobile detection based on viewport width via matchMedia.
+ * SSR defaults to desktop (false); hydrates to the real value on mount.
+ *
+ * For server-side device detection (UA-based), use the section loader
+ * pattern: registerSectionLoaders injects \`isMobile\` as a prop.
+ */
+export const useDevice = () => {
+  const isMobile = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+  return { isMobile };
+};
 `;
 }
 
 function generateSiteApp(ctx: MigrationContext): string {
+  // Try to read source site.ts to extract secrets and AppContext shape
+  const secretFields = extractSecretFields(ctx);
+
+  let secretImport = "";
+  let secretTypes = "";
+  if (secretFields.length > 0) {
+    secretImport = `\nimport type { Secret } from "~/utils/secrets";\n`;
+    secretTypes = secretFields.map((f) => `  ${f}: Secret;`).join("\n");
+  }
+
+  const vtexAccount = ctx.vtexAccount || ctx.siteName;
+
   return `export type Platform =
   | "vtex"
   | "vnda"
@@ -256,10 +378,177 @@ function generateSiteApp(ctx: MigrationContext): string {
   | "custom";
 
 export const _platform: Platform = "${ctx.platform}";
-
+${secretImport}
 export type AppContext = {
   device: "mobile" | "desktop" | "tablet";
-  platform: Platform;
+  platform: Platform;${secretTypes ? `\n${secretTypes}` : ""}${ctx.platform === "vtex" ? `\n  account: string;` : ""}
 };
 `;
 }
+
+function extractSecretFields(ctx: MigrationContext): string[] {
+  const siteAppPaths = [
+    path.join(ctx.sourceDir, "apps", "site.ts"),
+    path.join(ctx.sourceDir, "src", "apps", "site.ts"),
+  ];
+
+  for (const p of siteAppPaths) {
+    if (!fs.existsSync(p)) continue;
+    const content = fs.readFileSync(p, "utf-8");
+    const secretRe = /(\w+):\s*Secret\b/g;
+    const fields: string[] = [];
+    let match;
+    while ((match = secretRe.exec(content)) !== null) {
+      fields.push(match[1]);
+    }
+    return fields;
+  }
+  return [];
+}
+
+function generateSecrets(ctx: MigrationContext): string {
+  const fields = extractSecretFields(ctx);
+
+  if (fields.length === 0) {
+    return `export interface Secret {
+  get(): string;
+}
+
+function envSecret(envKey: string): Secret {
+  return {
+    get: () => (process.env[envKey] as string) ?? "",
+  };
+}
+
+export const secrets = {} as const;
+`;
+  }
+
+  const envKeyMap: Record<string, string> = {
+    GatewayApiKey: "GATEWAY_API_KEY",
+    topsortkey: "TOPSORT_KEY",
+    yourviewsToken: "YOURVIEWS_TOKEN",
+    pickuppointsAppKey: "PICKUPPOINTS_APP_KEY",
+    pickuppointsAppToken: "PICKUPPOINTS_APP_TOKEN",
+    SAPUser: "SAP_USER",
+    SAPPassword: "SAP_PASSWORD",
+  };
+
+  const entries = fields.map((f) => {
+    const envKey = envKeyMap[f] || f.replace(/([A-Z])/g, "_$1").toUpperCase();
+    return `  ${f}: envSecret("${envKey}"),`;
+  });
+
+  return `export interface Secret {
+  get(): string;
+}
+
+function envSecret(envKey: string): Secret {
+  return {
+    get: () => (process.env[envKey] as string) ?? "",
+  };
+}
+
+/**
+ * All site-level secrets, sourced from Cloudflare Worker env bindings
+ * (process.env is polyfilled by nodejs_compat).
+ *
+ * Local dev: .dev.vars
+ * Production: \`wrangler secret put <KEY>\`
+ */
+export const secrets = {
+${entries.join("\n")}
+} as const;
+`;
+}
+
+function hasLocationMatcher(ctx: MigrationContext): boolean {
+  const dirs = [
+    path.join(ctx.sourceDir, "matchers"),
+    path.join(ctx.sourceDir, "src", "matchers"),
+  ];
+  for (const dir of dirs) {
+    if (fs.existsSync(dir)) {
+      const files = fs.readdirSync(dir);
+      if (files.some((f) => f.includes("location"))) return true;
+    }
+  }
+  // Also check .deco/blocks for location matcher references
+  const blocksDir = path.join(ctx.sourceDir, ".deco", "blocks");
+  if (fs.existsSync(blocksDir)) {
+    for (const file of fs.readdirSync(blocksDir)) {
+      if (!file.endsWith(".json")) continue;
+      try {
+        const content = fs.readFileSync(path.join(blocksDir, file), "utf-8");
+        if (content.includes("website/matchers/location")) return true;
+      } catch { /* skip */ }
+    }
+  }
+  return false;
+}
+
+function generateLocationMatcher(): string {
+  return `/**
+ * Server-side location matcher for website/matchers/location.ts
+ *
+ * Reads CF geolocation data injected as internal cookies by worker-entry.ts
+ * (__cf_geo_region, __cf_geo_country, __cf_geo_city) to evaluate location
+ * rules server-side.
+ */
+
+import { registerMatcher } from "@decocms/start/cms";
+import type { MatcherContext } from "@decocms/start/cms";
+
+const COUNTRY_NAME_TO_CODE: Record<string, string> = {
+  Brasil: "BR",
+  Brazil: "BR",
+  Argentina: "AR",
+  Chile: "CL",
+  Colombia: "CO",
+  Uruguay: "UY",
+  Paraguay: "PY",
+  Peru: "PE",
+  "United States": "US",
+  Portugal: "PT",
+};
+
+interface LocationRule {
+  regionCode?: string;
+  country?: string;
+  city?: string;
+}
+
+function matchesRule(loc: LocationRule, region: string, country: string, city: string): boolean {
+  if (loc.country) {
+    const code = COUNTRY_NAME_TO_CODE[loc.country] ?? loc.country;
+    if (code !== country) return false;
+  }
+  if (loc.regionCode && loc.regionCode !== region) return false;
+  if (loc.city && loc.city.toLowerCase() !== city.toLowerCase()) return false;
+  return true;
+}
+
+export function registerLocationMatcher(): void {
+  registerMatcher(
+    "website/matchers/location.ts",
+    (rule: Record<string, unknown>, ctx: MatcherContext): boolean => {
+      const includeLocations = (rule.includeLocations as LocationRule[] | undefined) ?? [];
+      const excludeLocations = (rule.excludeLocations as LocationRule[] | undefined) ?? [];
+
+      const cookies = ctx.cookies ?? {};
+      const region = cookies.__cf_geo_region ? decodeURIComponent(cookies.__cf_geo_region) : "";
+      const country = cookies.__cf_geo_country ? decodeURIComponent(cookies.__cf_geo_country) : "";
+      const city = cookies.__cf_geo_city ? decodeURIComponent(cookies.__cf_geo_city) : "";
+
+      if (excludeLocations.some((loc) => matchesRule(loc, region, country, city))) {
+        return false;
+      }
+
+      if (includeLocations.length === 0) return true;
+
+      return includeLocations.some((loc) => matchesRule(loc, region, country, city));
+    },
+  );
+}
+`;
+}

package/scripts/migrate/phase-transform.ts

@@ -38,11 +38,11 @@ function applyTransforms(content: string, filePath: string, ctx?: MigrationConte
   }
 
   // Pipeline: imports → jsx → fresh-apis → dead-code → deno-isms → tailwind
-  const pipeline = [
-    { name: "imports", fn: transformImports },
+  const pipeline: Array<{ name: string; fn: (content: string) => TransformResult }> = [
+    { name: "imports", fn: (c) => transformImports(c, ctx?.islandWrapperTargets) },
     { name: "jsx", fn: transformJsx },
     { name: "fresh-apis", fn: transformFreshApis },
-    { name: "dead-code", fn: transformDeadCode },
+    { name: "dead-code", fn: (c) => transformDeadCode(c, ctx?.platform) },
     { name: "deno-isms", fn: transformDenoIsms },
     { name: "tailwind", fn: transformTailwind },
   ];
@@ -86,6 +86,17 @@ export function transform(ctx: MigrationContext): void {
     // Apply transforms
     const result = applyTransforms(content, absPath, ctx, record.path);
 
+    // Fix section re-exports from wrapper islands — point to the wrapped component
+    const resolvedTarget = (record as any).__resolvedReExportTarget;
+    if (resolvedTarget && result.content.includes("~/components/")) {
+      // The import transform rewrote $store/islands/X → ~/components/X
+      // but for wrapper islands, the actual component is at a different path
+      const reExportRe = /from\s+"~\/components\/[^"]+"/g;
+      result.content = result.content.replace(reExportRe, `from "${resolvedTarget}"`);
+      result.notes.push(`Re-export resolved to wrapper target: ${resolvedTarget}`);
+      result.changed = true;
+    }
+
     // Add manual review items
     for (const note of result.notes) {
       if (note.startsWith("[") && note.includes("MANUAL:")) {
@@ -115,6 +126,48 @@ export function transform(ctx: MigrationContext): void {
       });
     }
 
+    // Flag the legacy sections/Component.tsx dynamic-section loader.
+    // This file uses Deno-specific APIs (toFileUrl, import.meta.resolve)
+    // and the HTMX-driven `useComponent(component, props)` pattern, which
+    // do not run on Cloudflare Workers and have no equivalent in
+    // @decocms/start. The whole file must be deleted.
+    if (
+      /sections\/Component\.tsx?$/.test(record.path) ||
+      /sections\/Component\.tsx?$/.test(targetPath)
+    ) {
+      ctx.manualReviewItems.push({
+        file: targetPath,
+        reason:
+          "sections/Component.tsx (Deno HTMX dynamic-section loader) is incompatible with TanStack Start / Cloudflare Workers. " +
+          "DELETE this file and migrate every `useComponent(...)` call site to one of: " +
+          "(a) local React state for client-side toggles, " +
+          "(b) `createServerFn` + `useMutation` for server actions, or " +
+          "(c) a direct `invoke` call (`~/server/invoke`) for ad-hoc loaders. " +
+          "See: deco-to-tanstack-migration skill, 'useComponent / partial sections' section.",
+        severity: "error",
+      });
+    }
+
+    // Flag any import of useComponent — typically `import { useComponent } from "site/sections/Component.tsx"`.
+    // We also catch `from "../../sections/Component"` and similar relative variants.
+    if (
+      /\buseComponent\b/.test(result.content) &&
+      /from\s+["'][^"']*sections\/Component(?:\.tsx?)?["']/.test(result.content)
+    ) {
+      ctx.manualReviewItems.push({
+        file: targetPath,
+        reason:
+          "useComponent({ ... }) call site detected. This is the HTMX-style dynamic-section render pattern " +
+          "that ships HTML fragments and swaps them client-side. It does not work on TanStack Start. " +
+          "Recipes: " +
+          "(1) Self-contained UI toggles → keep state in React (`useState` + event handlers); " +
+          "(2) Form submissions / mutations → `createServerFn` + `useMutation` (see casaevideo-storefront for canonical examples); " +
+          "(3) Ad-hoc data fetches → call the loader/action via `~/server/invoke` and store results in `useState`. " +
+          "Remove the import after refactoring, then delete `src/sections/Component.tsx`.",
+        severity: "error",
+      });
+    }
+
     if (ctx.dryRun) {
       if (result.changed) {
         log(ctx, `[DRY] Would transform: ${record.path} → ${targetPath}`);

package/scripts/migrate/templates/app-css.ts

@@ -1,6 +1,109 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import type { MigrationContext } from "../types.ts";
 import type { ExtractedTheme } from "../analyzers/theme-extractor.ts";
 
+/**
+ * Find the original site's custom CSS file.
+ * Deco sites typically have their custom CSS in:
+ * - tailwind.css (root level, combined directives + custom)
+ * - static/tailwind.css (compiled output — skip this)
+ * - static-{brand}/tailwind.css (compiled output — skip this)
+ * - styles/*.css
+ */
+function findOriginalCss(ctx: MigrationContext): string | null {
+  // Prefer root tailwind.css (has custom CSS + directives)
+  const rootCss = path.join(ctx.sourceDir, "tailwind.css");
+  if (fs.existsSync(rootCss)) {
+    return fs.readFileSync(rootCss, "utf-8");
+  }
+
+  // Check for styles/ directory
+  const stylesDir = path.join(ctx.sourceDir, "styles");
+  if (fs.existsSync(stylesDir)) {
+    for (const file of fs.readdirSync(stylesDir)) {
+      if (file.endsWith(".css") && file !== "tailwind.css") {
+        return fs.readFileSync(path.join(stylesDir, file), "utf-8");
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extract custom CSS from the original site's CSS file.
+ * Strips TW3 directives (@tailwind base/components/utilities) and
+ * returns only the custom CSS (component overrides, @layer, @font-face, etc.)
+ */
+function extractCustomCss(rawCss: string): string {
+  return rawCss
+    // Remove Tailwind v3 directives (replaced by @import "tailwindcss")
+    .replace(/^@tailwind\s+(?:base|components|utilities)\s*;\s*$/gm, "")
+    // Remove empty lines left over
+    .replace(/^\s*\n/gm, "")
+    .trim();
+}
+
+/**
+ * Transform @apply directives for TW3→TW4 compatibility.
+ * The tailwind.ts transform handles className= attributes in JSX,
+ * but @apply inside CSS also needs class renames.
+ *
+ * Also converts @apply with custom brand/theme colors to native CSS
+ * properties when the utility class might not be registered in TW4.
+ */
+function transformApplyDirectives(css: string): string {
+  return css
+    .replace(/@apply\s+([^;]+);/g, (_match, classes: string) => {
+      let fixed = classes;
+      // flex-grow-0 → grow-0
+      fixed = fixed.replace(/\bflex-grow-0\b/g, "grow-0");
+      fixed = fixed.replace(/\bflex-grow\b/g, "grow");
+      fixed = fixed.replace(/\bflex-shrink-0\b/g, "shrink-0");
+      fixed = fixed.replace(/\bflex-shrink\b/g, "shrink");
+      // transform → removed (auto in v4)
+      fixed = fixed.replace(/\btransform\b(?!-none)/g, "");
+      fixed = fixed.replace(/\bfilter\b/g, "");
+      // ring → ring-3
+      fixed = fixed.replace(/\bring\b(?!-)/g, "ring-3");
+      // Clean up multiple spaces
+      fixed = fixed.replace(/\s{2,}/g, " ").trim();
+      return `@apply ${fixed};`;
+    });
+}
+
+/**
+ * Test if a value looks like oklch coordinates (space-separated numbers,
+ * possibly with `/` for alpha). Examples: "0.5 0.2 30", "0.8 0.15 120 / 0.5"
+ * This distinguishes oklch coordinate values from hex colors.
+ */
+function isOklchCoordinates(val: string): boolean {
+  const trimmed = val.trim();
+  // oklch coordinates: 2-3 space-separated numbers, possibly with / alpha
+  // e.g. "0.5 0.2 30" or "0.85 0.15 120 / 0.5"
+  return /^[\d.]+\s+[\d.]+\s+[\d.]+(\s*\/\s*[\d.]+)?$/.test(trimmed);
+}
+
+/**
+ * Extract the primary font family from @font-face declarations in CSS.
+ * Returns the first font-family name found, or null.
+ */
+function extractPrimaryFontFromCss(css: string): string | null {
+  const fontFaceRe = /@font-face\s*\{[^}]*font-family:\s*["']?([^"';]+)["']?\s*;/g;
+  const families = new Set<string>();
+  let match;
+  while ((match = fontFaceRe.exec(css)) !== null) {
+    families.add(match[1].trim());
+  }
+  if (families.size === 0) return null;
+  // Prefer non-icon fonts
+  const nonIcon = [...families].filter(
+    (f) => !/icon|awesome|material/i.test(f),
+  );
+  return nonIcon[0] || [...families][0];
+}
+
 export function generateAppCss(ctx: MigrationContext, theme?: ExtractedTheme): string {
   const sections: string[] = [];
 
@@ -36,7 +139,15 @@ ${colorLines}
 }`);
 
   // ── @theme block: Tailwind v3->v4 color migration ─────────────────
-  const fontFamily = theme?.fontFamily || ctx.fontFamily;
+  // Determine font family from theme, context, or original CSS @font-face
+  let fontFamily = theme?.fontFamily || ctx.fontFamily;
+  if (!fontFamily) {
+    const originalCssForFont = findOriginalCss(ctx);
+    if (originalCssForFont) {
+      const extracted = extractPrimaryFontFromCss(originalCssForFont);
+      if (extracted) fontFamily = extracted;
+    }
+  }
   let fontLine = "";
   if (fontFamily) {
     const firstFont = fontFamily.split(",")[0].trim().replace(/['"]/g, "");
@@ -55,6 +166,10 @@ ${colorLines}
   --color-inherit: inherit;${fontLine}`;
 
   // Add extracted theme variables to @theme
+  // Theme variables come from the CMS Theme section (.deco/blocks/Theme-*.json).
+  // The CMS sets CSS custom properties on :root at runtime, so @theme entries
+  // should reference var(--x) instead of hardcoding values. For oklch-formatted
+  // values (space-separated numbers like "0.5 0.2 30"), wrap with oklch().
   const vars = theme?.variables ?? {};
   if (Object.keys(vars).length > 0) {
     themeBlock += `\n`;
@@ -68,7 +183,22 @@ ${colorLines}
     for (const [prefix, entries] of Object.entries(grouped)) {
       themeBlock += `\n  /* ${prefix} */`;
       for (const [k, v] of entries) {
-        themeBlock += `\n  ${k}: ${v};`;
+        if (!k.startsWith("--color-") && !k.startsWith("--font-") && !k.startsWith("--breakpoint-")) {
+          const val = v.trim();
+          const isColor = /^#[0-9a-fA-F]{3,8}$/.test(val) ||
+            /^(rgb|hsl|oklch|oklab)\(/.test(val) ||
+            /^(transparent|currentColor|inherit)$/.test(val) ||
+            isOklchCoordinates(val);
+          if (isColor) {
+            const varName = k.replace(/^--/, "");
+            const colorKey = `--color-${varName}`;
+            if (isOklchCoordinates(val)) {
+              themeBlock += `\n  ${colorKey}: oklch(var(${k}));`;
+            } else {
+              themeBlock += `\n  ${colorKey}: var(${k});`;
+            }
+          }
+        }
       }
     }
   }
@@ -200,5 +330,22 @@ section[data-deferred="true"] {
   display: none;
 }`);
 
+  // ── Incorporate original site's custom CSS ────────────────────
+  // Instead of throwing away the site's CSS, we extract and append
+  // all custom rules (component overrides, @layer base, @font-face,
+  // typography utilities, feature-specific CSS, etc.)
+  const originalCss = findOriginalCss(ctx);
+  if (originalCss) {
+    const customCss = extractCustomCss(originalCss);
+    if (customCss) {
+      const transformed = transformApplyDirectives(customCss);
+      sections.push(`/* ═══════════════════════════════════════════════════════════════
+   Original site CSS (migrated from tailwind.css)
+   ═══════════════════════════════════════════════════════════════ */
+
+${transformed}`);
+    }
+  }
+
   return sections.join("\n\n") + "\n";
 }