@decocms/start 1.2.5 → 1.2.7

package/scripts/migrate/phase-scaffold.ts

@@ -10,6 +10,15 @@ import { generateKnipConfig } from "./templates/knip-config.ts";
 import { generateRoutes } from "./templates/routes.ts";
 import { generateSetup } from "./templates/setup.ts";
 import { generateServerEntry } from "./templates/server-entry.ts";
+import { generateAppCss } from "./templates/app-css.ts";
+import { generateTypeFiles } from "./templates/types-gen.ts";
+import { generateUiComponents } from "./templates/ui-components.ts";
+import { generateHooks } from "./templates/hooks.ts";
+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 { extractTheme } from "./analyzers/theme-extractor.ts";
 
 function writeFile(ctx: MigrationContext, relPath: string, content: string) {
   const fullPath = path.join(ctx.sourceDir, relPath);
@@ -20,7 +29,6 @@ function writeFile(ctx: MigrationContext, relPath: string, content: string) {
     return;
   }
 
-  // Ensure directory exists
   const dir = path.dirname(fullPath);
   fs.mkdirSync(dir, { recursive: true });
 
@@ -29,6 +37,12 @@ function writeFile(ctx: MigrationContext, relPath: string, content: string) {
   ctx.scaffoldedFiles.push(relPath);
 }
 
+function writeMultiFile(ctx: MigrationContext, files: Record<string, string>) {
+  for (const [filePath, content] of Object.entries(files)) {
+    writeFile(ctx, filePath, content);
+  }
+}
+
 export function scaffold(ctx: MigrationContext): void {
   logPhase("Scaffold");
 
@@ -47,38 +61,41 @@ export function scaffold(ctx: MigrationContext): void {
     tabWidth: 2,
   }, null, 2) + "\n");
 
-  // Server entry files
-  const serverEntryFiles = generateServerEntry(ctx);
-  for (const [filePath, content] of Object.entries(serverEntryFiles)) {
-    writeFile(ctx, filePath, content);
-  }
+  // Server entry files (server.ts, worker-entry.ts, router.tsx, runtime.ts, context.ts)
+  writeMultiFile(ctx, generateServerEntry(ctx));
 
   // Route files
-  const routeFiles = generateRoutes(ctx);
-  for (const [filePath, content] of Object.entries(routeFiles)) {
-    writeFile(ctx, filePath, content);
-  }
+  writeMultiFile(ctx, generateRoutes(ctx));
 
-  // Setup
+  // Setup infrastructure
   writeFile(ctx, "src/setup.ts", generateSetup(ctx));
+  writeFile(ctx, "src/cache-config.ts", generateCacheConfig(ctx));
+  writeFile(ctx, "src/setup/commerce-loaders.ts", generateCommerceLoaders(ctx));
+  writeFile(ctx, "src/setup/section-loaders.ts", generateSectionLoaders(ctx));
 
-  // Styles
-  writeFile(ctx, "src/styles/app.css", generateAppCss(ctx));
+  // Theme extraction + Styles
+  const theme = extractTheme(ctx);
+  writeFile(ctx, "src/styles/app.css", generateAppCss(ctx, theme));
 
-  // SDK — signal shim (replaces @preact/signals)
-  writeFile(ctx, "src/sdk/signal.ts", generateSignalShim());
+  // Type definitions
+  writeMultiFile(ctx, generateTypeFiles(ctx));
 
-  // SDK — clx (class name joiner, with default export for compat)
-  writeFile(ctx, "src/sdk/clx.ts", generateClxShim());
+  // UI components (Image, Picture, Video)
+  writeMultiFile(ctx, generateUiComponents(ctx));
 
-  // SDK — debounce (replaces Deno std/async/debounce)
+  // Platform hooks (useCart, useUser, useWishlist)
+  writeMultiFile(ctx, generateHooks(ctx));
+
+  // SDK shims + generated utilities
+  writeFile(ctx, "src/sdk/signal.ts", generateSignalShim());
+  writeFile(ctx, "src/sdk/clx.ts", generateClxShim());
   writeFile(ctx, "src/sdk/debounce.ts", generateDebounceShim());
+  writeMultiFile(ctx, generateSdkFiles(ctx));
 
   // 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 {
@@ -112,10 +129,6 @@ export interface Props {
   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(" ")} }\`
@@ -143,57 +156,6 @@ 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" {
-  name: "light";
-  default: true;
-  color-scheme: light;
-
-${colorLines}
-}
-
-@theme {
-  --color-*: initial;
-  --color-white: #fff;
-  --color-black: #000;
-  --color-transparent: transparent;
-  --color-current: currentColor;
-  --color-inherit: inherit;${ctx.fontFamily ? `\n  --font-sans: "${ctx.fontFamily}", ui-sans-serif, system-ui, sans-serif;` : ""}
-}
-
-/* View transitions */
-@view-transition {
-  navigation: auto;
-}
-`;
-}
-
 function generateGitignore(): string {
   return `# Dependencies
 node_modules/
@@ -224,9 +186,6 @@ vite.config.timestamp_*
 # Deco CMS
 .deco/metadata/*
 
-# Bun lock file (if using npm, keep package-lock.json instead)
-# package-lock.json
-
 # IDE
 .vscode/
 .idea/
@@ -276,66 +235,13 @@ export default debounce;
 }
 
 function generateSignalShim(): string {
-  return `import { Store } from "@tanstack/store";
-import { useSyncExternalStore, useMemo, useEffect } from "react";
-
-export interface Signal<T> {
-  readonly store: Store<T>;
-  value: T;
-  peek(): T;
-  subscribe(fn: () => void): () => void;
-}
-
-export function signal<T>(initialValue: T): Signal<T> {
-  const store = new Store<T>(initialValue);
-  return {
-    store,
-    get value() { return store.state; },
-    set value(v: T) { store.setState(() => v); },
-    peek() { return store.state; },
-    subscribe(fn) {
-      // @tanstack/store@0.9.x returns { unsubscribe: Function },
-      // NOT a plain function. React's useSyncExternalStore cleanup
-      // expects a bare function — unwrap it.
-      const sub = store.subscribe(() => fn());
-      return typeof sub === "function" ? sub : sub.unsubscribe;
-    },
-  };
-}
-
-export function useSignal<T>(initialValue: T): Signal<T> {
-  const sig = useMemo(() => signal(initialValue), []);
-  useSyncExternalStore(
-    (cb) => sig.subscribe(cb),
-    () => sig.value,
-    () => sig.value,
-  );
-  return sig;
-}
-
-export function useComputed<T>(fn: () => T): Signal<T> {
-  const sig = useMemo(() => signal(fn()), [fn]);
-  return sig;
-}
-
-export function computed<T>(fn: () => T): Signal<T> {
-  return signal(fn());
-}
+  return `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 : () => {};
 }
-
-export function batch(fn: () => void): void {
-  fn();
-}
-
-export function useSignalEffect(fn: () => void | (() => void)): void {
-  useEffect(fn);
-}
-
-export type { Signal as ReadonlySignal };
 `;
 }
 

package/scripts/migrate/phase-transform.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { MigrationContext, TransformResult } from "./types.ts";
+import type { MigrationContext, TransformResult, SectionMeta } from "./types.ts";
 import { log, logPhase } from "./types.ts";
 import { transformImports } from "./transforms/imports.ts";
 import { transformJsx } from "./transforms/jsx.ts";
@@ -8,11 +8,25 @@ import { transformFreshApis } from "./transforms/fresh-apis.ts";
 import { transformDenoIsms } from "./transforms/deno-isms.ts";
 import { transformTailwind } from "./transforms/tailwind.ts";
 import { transformDeadCode } from "./transforms/dead-code.ts";
+import { transformSectionConventions } from "./transforms/section-conventions.ts";
+
+/** Map of section path → metadata, populated per-run */
+let sectionMetaMap: Map<string, SectionMeta> | null = null;
+
+function getSectionMeta(ctx: MigrationContext, relPath: string): SectionMeta | undefined {
+  if (!sectionMetaMap) {
+    sectionMetaMap = new Map();
+    for (const m of ctx.sectionMetas) {
+      sectionMetaMap.set(m.path, m);
+    }
+  }
+  return sectionMetaMap.get(relPath);
+}
 
 /**
  * Apply all transforms to a file's content in the correct order.
  */
-function applyTransforms(content: string, filePath: string): TransformResult {
+function applyTransforms(content: string, filePath: string, ctx?: MigrationContext, relPath?: string): TransformResult {
   const allNotes: string[] = [];
   let currentContent = content;
   let anyChanged = false;
@@ -42,6 +56,17 @@ function applyTransforms(content: string, filePath: string): TransformResult {
     }
   }
 
+  // Section conventions (sync/eager/layout/cache) — only for section files
+  if (ctx && relPath && relPath.startsWith("sections/")) {
+    const meta = getSectionMeta(ctx, relPath);
+    const result = transformSectionConventions(currentContent, meta);
+    if (result.changed) {
+      anyChanged = true;
+      currentContent = result.content;
+      allNotes.push(...result.notes.map((n) => `[section-conventions] ${n}`));
+    }
+  }
+
   return { content: currentContent, changed: anyChanged, notes: allNotes };
 }
 
@@ -59,7 +84,7 @@ export function transform(ctx: MigrationContext): void {
     const content = fs.readFileSync(absPath, "utf-8");
 
     // Apply transforms
-    const result = applyTransforms(content, absPath);
+    const result = applyTransforms(content, absPath, ctx, record.path);
 
     // Add manual review items
     for (const note of result.notes) {

package/scripts/migrate/phase-verify.ts

@@ -22,8 +22,19 @@ const REQUIRED_FILES = [
   "src/runtime.ts",
   "src/context.ts",
   "src/setup.ts",
+  "src/cache-config.ts",
+  "src/setup/commerce-loaders.ts",
+  "src/setup/section-loaders.ts",
   "src/styles/app.css",
   "src/apps/site.ts",
+  "src/hooks/useCart.ts",
+  "src/hooks/useUser.ts",
+  "src/hooks/useWishlist.ts",
+  "src/types/widgets.ts",
+  "src/types/deco.ts",
+  "src/types/commerce-app.ts",
+  "src/components/ui/Image.tsx",
+  "src/components/ui/Picture.tsx",
   "src/routes/__root.tsx",
   "src/routes/index.tsx",
   "src/routes/$.tsx",
@@ -38,8 +49,8 @@ const MUST_NOT_EXIST = [
   "manifest.gen.ts",
   "dev.ts",
   "main.ts",
-  "islands/BlogFeed.tsx",
   "routes/_app.tsx",
+  "routes/_middleware.ts",
 ];
 
 const checks: Check[] = [
@@ -261,14 +272,16 @@ const checks: Check[] = [
     },
   },
   {
-    name: "No dead cache/cacheKey exports",
+    name: "No dead cache/cacheKey exports (old SWR system)",
     severity: "warning",
     fn: (ctx) => {
       const srcDir = path.join(ctx.sourceDir, "src");
       if (!fs.existsSync(srcDir)) return true;
-      const bad = findFilesWithPattern(srcDir, /^export\s+const\s+(?:cache|cacheKey)\s*=/m);
+      // Only flag the OLD cache patterns: cache = "stale-while-revalidate" or cache = { maxAge: ... }
+      // NOT the new-stack section convention: cache = "listing" / "product" / "search" / "static"
+      const bad = findFilesWithPattern(srcDir, /^export\s+const\s+cacheKey\s*=/m);
       if (bad.length > 0) {
-        console.log(`    Dead exports found (old cache system): ${bad.join(", ")}`);
+        console.log(`    Dead cacheKey exports found: ${bad.join(", ")}`);
         return false;
       }
       return true;
@@ -339,6 +352,110 @@ const checks: Check[] = [
       return true;
     },
   },
+  {
+    name: "No @deco/deco imports in src/",
+    severity: "error",
+    fn: (ctx) => {
+      const srcDir = path.join(ctx.sourceDir, "src");
+      if (!fs.existsSync(srcDir)) return true;
+      const bad = findFilesWithPattern(srcDir, /from\s+["']@deco\/deco/);
+      if (bad.length > 0) {
+        console.log(`    Still has @deco/deco imports: ${bad.join(", ")}`);
+        return false;
+      }
+      return true;
+    },
+  },
+  {
+    name: "No apps/ imports in src/ (should be @decocms/apps or ~/)",
+    severity: "error",
+    fn: (ctx) => {
+      const srcDir = path.join(ctx.sourceDir, "src");
+      if (!fs.existsSync(srcDir)) return true;
+      const bad = findFilesWithPattern(srcDir, /from\s+["']apps\//);
+      if (bad.length > 0) {
+        console.log(`    Still has apps/ imports: ${bad.join(", ")}`);
+        return false;
+      }
+      return true;
+    },
+  },
+  {
+    name: "Setup infrastructure is complete",
+    severity: "error",
+    fn: (ctx) => {
+      const setupFiles = [
+        "src/setup.ts",
+        "src/cache-config.ts",
+        "src/setup/commerce-loaders.ts",
+        "src/setup/section-loaders.ts",
+      ];
+      const missing = setupFiles.filter(
+        (f) => !fs.existsSync(path.join(ctx.sourceDir, f)),
+      );
+      if (missing.length > 0) {
+        console.log(`    Missing setup infrastructure: ${missing.join(", ")}`);
+        return false;
+      }
+      return true;
+    },
+  },
+  {
+    name: "No islands/ directory (should be eliminated)",
+    severity: "warning",
+    fn: (ctx) => {
+      const islandsDir = path.join(ctx.sourceDir, "src", "islands");
+      if (fs.existsSync(islandsDir)) {
+        try {
+          const files = fs.readdirSync(islandsDir, { recursive: true });
+          const tsxFiles = (files as string[]).filter((f: string) => f.endsWith(".tsx") || f.endsWith(".ts"));
+          if (tsxFiles.length > 0) {
+            console.log(`    src/islands/ still has ${tsxFiles.length} files — should be moved to components/`);
+            return false;
+          }
+        } catch {}
+      }
+      return true;
+    },
+  },
+  {
+    name: "Hooks are scaffolded",
+    severity: "warning",
+    fn: (ctx) => {
+      const hookFiles = [
+        "src/hooks/useCart.ts",
+        "src/hooks/useUser.ts",
+        "src/hooks/useWishlist.ts",
+      ];
+      const missing = hookFiles.filter(
+        (f) => !fs.existsSync(path.join(ctx.sourceDir, f)),
+      );
+      if (missing.length > 0) {
+        console.log(`    Missing hooks: ${missing.join(", ")}`);
+        return false;
+      }
+      return true;
+    },
+  },
+  {
+    name: "Type files are scaffolded",
+    severity: "warning",
+    fn: (ctx) => {
+      const typeFiles = [
+        "src/types/widgets.ts",
+        "src/types/deco.ts",
+        "src/types/commerce-app.ts",
+      ];
+      const missing = typeFiles.filter(
+        (f) => !fs.existsSync(path.join(ctx.sourceDir, f)),
+      );
+      if (missing.length > 0) {
+        console.log(`    Missing type files: ${missing.join(", ")}`);
+        return false;
+      }
+      return true;
+    },
+  },
 ];
 
 function findFilesWithPattern(
@@ -356,7 +473,12 @@ function findFilesWithPattern(
       findFilesWithPattern(fullPath, pattern, results, root);
     } else if (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) {
       const content = fs.readFileSync(fullPath, "utf-8");
-      if (pattern.test(content)) {
+      // Only test non-comment lines
+      const uncommented = content
+        .split("\n")
+        .filter((line) => !line.trimStart().startsWith("//") && !line.trimStart().startsWith("*"))
+        .join("\n");
+      if (pattern.test(uncommented)) {
         results.push(path.basename(fullPath));
       }
     }

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

@@ -0,0 +1,204 @@
+import type { MigrationContext } from "../types.ts";
+import type { ExtractedTheme } from "../analyzers/theme-extractor.ts";
+
+export function generateAppCss(ctx: MigrationContext, theme?: ExtractedTheme): string {
+  const sections: string[] = [];
+
+  // ── DaisyUI theme plugin ──────────────────────────────────────────
+  const daisyColors = theme?.daisyUiColors ?? {};
+  const c = ctx.themeColors;
+
+  const semanticColors: Record<string, string> = {
+    "--color-primary": daisyColors["--color-primary"] || c["primary"] || "#B10200",
+    "--color-secondary": daisyColors["--color-secondary"] || c["secondary"] || "#141414",
+    "--color-accent": daisyColors["--color-accent"] || c["tertiary"] || "#FFF100",
+    "--color-neutral": daisyColors["--color-neutral"] || c["neutral"] || "#393939",
+    "--color-base-100": daisyColors["--color-base-100"] || c["base-100"] || "#FFFFFF",
+    "--color-base-200": daisyColors["--color-base-200"] || c["base-200"] || "#F3F3F3",
+    "--color-base-300": daisyColors["--color-base-300"] || c["base-300"] || "#868686",
+    "--color-info": daisyColors["--color-info"] || c["info"] || "#006CA1",
+    "--color-success": daisyColors["--color-success"] || c["success"] || "#007552",
+    "--color-warning": daisyColors["--color-warning"] || c["warning"] || "#F8D13A",
+    "--color-error": daisyColors["--color-error"] || c["error"] || "#CF040A",
+  };
+
+  const colorLines = Object.entries(semanticColors)
+    .map(([k, v]) => `  ${k}: ${v};`)
+    .join("\n");
+
+  sections.push(`@import "tailwindcss";
+@plugin "daisyui";
+@plugin "daisyui/theme" {
+  name: "light";
+  default: true;
+  color-scheme: light;
+${colorLines}
+}`);
+
+  // ── @theme block: Tailwind v3->v4 color migration ─────────────────
+  const fontFamily = theme?.fontFamily || ctx.fontFamily;
+  let fontLine = "";
+  if (fontFamily) {
+    const firstFont = fontFamily.split(",")[0].trim().replace(/['"]/g, "");
+    fontLine = `\n  --font-sans: "${firstFont}", ui-sans-serif, system-ui, sans-serif;`;
+  }
+
+  let themeBlock = `/* Tailwind v4: reset default palette (old sites replaced it entirely via theme.colors)
+   then re-add only the colors used by this site. */
+@theme {
+  --color-*: initial;
+
+  --color-white: #fff;
+  --color-black: #000;
+  --color-transparent: transparent;
+  --color-current: currentColor;
+  --color-inherit: inherit;${fontLine}`;
+
+  // Add extracted theme variables to @theme
+  const vars = theme?.variables ?? {};
+  if (Object.keys(vars).length > 0) {
+    themeBlock += `\n`;
+    const grouped: Record<string, Array<[string, string]>> = {};
+    for (const [k, v] of Object.entries(vars)) {
+      const prefix = k.replace(/^--/, "").split("-").slice(0, 2).join("-");
+      if (!grouped[prefix]) grouped[prefix] = [];
+      grouped[prefix].push([k, v]);
+    }
+
+    for (const [prefix, entries] of Object.entries(grouped)) {
+      themeBlock += `\n  /* ${prefix} */`;
+      for (const [k, v] of entries) {
+        themeBlock += `\n  ${k}: ${v};`;
+      }
+    }
+  }
+
+  // Gray scale compat (Tailwind v3 had gray-50..gray-950 by default)
+  themeBlock += `
+
+  /* Gray scale (Tailwind v3 default, required for bg-gray-*, text-gray-*, etc.) */
+  --color-gray-50: #f9fafb;
+  --color-gray-100: #f3f4f6;
+  --color-gray-200: #e5e7eb;
+  --color-gray-300: #d1d5db;
+  --color-gray-400: #9ca3af;
+  --color-gray-500: #6b7280;
+  --color-gray-600: #4b5563;
+  --color-gray-700: #374151;
+  --color-gray-800: #1f2937;
+  --color-gray-900: #111827;
+  --color-gray-950: #030712;
+}`;
+  sections.push(themeBlock);
+
+  // ── DaisyUI v5 compat ─────────────────────────────────────────────
+  sections.push(`/* DaisyUI v5: flatten depth/noise to match v4 look */
+:root {
+  --depth: 0;
+  --noise: 0;
+}`);
+
+  // ── :root theme variables ─────────────────────────────────────────
+  if (Object.keys(vars).length > 0) {
+    let rootBlock = `:root {\n`;
+    for (const [k, v] of Object.entries(vars)) {
+      rootBlock += `  ${k}: ${v};\n`;
+    }
+    if (fontFamily) {
+      const firstFont = fontFamily.split(",")[0].trim().replace(/['"]/g, "");
+      rootBlock += `  --font-family: ${firstFont}, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;\n`;
+    }
+    rootBlock += `}`;
+    sections.push(rootBlock);
+  }
+
+  // ── DaisyUI v5 carousel overflow fix ──────────────────────────────
+  sections.push(`/* DaisyUI v5 removed carousel overflow — re-add for horizontal scroll */
+.carousel {
+  -webkit-overflow-scrolling: touch;
+  overflow-x: auto;
+  scroll-snap-type: x mandatory;
+  scroll-behavior: smooth;
+}
+
+.carousel > * {
+  scroll-snap-align: start;
+}
+
+ul.carousel,
+ol.carousel {
+  list-style: none;
+  padding: 0;
+}`);
+
+  // ── Container utility (v3 -> v4 migration) ────────────────────────
+  sections.push(`/* Container: replaces Tailwind v3 container plugin config */
+@utility container {
+  margin-inline: auto;
+  padding-inline: 1rem;
+  width: 100%;
+
+  @media (width >= 640px) { max-width: 640px; }
+  @media (width >= 768px) { max-width: 768px; }
+  @media (width >= 1024px) { max-width: 1024px; }
+  @media (width >= 1280px) { max-width: 1280px; }
+  @media (width >= 1536px) { max-width: 1536px; }
+}`);
+
+  // ── Deferred section visibility ───────────────────────────────────
+  sections.push(`/* Deferred section visibility — reduces layout shift while loading */
+section[data-deferred="true"] {
+  content-visibility: auto;
+  contain-intrinsic-size: auto 300px;
+}
+
+.deferred-section {
+  content-visibility: auto;
+  contain-intrinsic-size: auto 300px;
+}`);
+
+  // ── View transitions ──────────────────────────────────────────────
+  sections.push(`@view-transition {
+  navigation: auto;
+}`);
+
+  // ── Base layer resets ─────────────────────────────────────────────
+  sections.push(`@layer base {
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+
+  body {
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+
+  img,
+  picture,
+  video,
+  canvas,
+  svg {
+    display: block;
+    max-width: 100%;
+  }
+
+  /* Drawer / modal scroll lock */
+  body:has(dialog[open]),
+  body:has(.drawer-toggle:checked) {
+    overflow: hidden;
+  }
+}`);
+
+  // ── Scrollbar utility ─────────────────────────────────────────────
+  sections.push(`.scrollbar-none {
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+}
+.scrollbar-none::-webkit-scrollbar {
+  display: none;
+}`);
+
+  return sections.join("\n\n") + "\n";
+}