@decocms/start 0.32.0 → 0.32.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "0.32.0",
+  "version": "0.32.2",
   "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

@@ -43,6 +43,9 @@ const SKIP_DIRS = new Set([
   "static",
   ".context",
   "scripts",
+  "src",
+  "public",
+  ".tanstack",
 ]);
 
 const SKIP_FILES = new Set([
@@ -52,6 +55,8 @@ const SKIP_FILES = new Set([
   "LICENSE",
   "browserslist",
   "bw_stats.json",
+  "package.json",
+  "package-lock.json",
 ]);
 
 /** Files that are generated and should be deleted */
@@ -70,6 +75,12 @@ const SDK_DELETE = new Set([
   "sdk/usePlatform.tsx",
 ]);
 
+/** Loaders that depend on deleted admin tooling */
+const LOADER_DELETE = new Set([
+  "loaders/availableIcons.ts",
+  "loaders/icons.ts",
+]);
+
 /** Root config/infra files to delete */
 const ROOT_DELETE = new Set([
   "main.ts",
@@ -79,11 +90,39 @@ const ROOT_DELETE = new Set([
   "tailwind.css",
   "tailwind.config.ts",
   "runtime.ts",
+  "constants.ts",
   "fresh.gen.ts",
   "manifest.gen.ts",
   "fresh.config.ts",
+  "browserslist",
+  "bw_stats.json",
+]);
+
+/** Static files that are code/tooling, not assets — should be deleted */
+const STATIC_DELETE = new Set([
+  "static/adminIcons.ts",
+  "static/generate-icons.ts",
+  "static/tailwind.css",
 ]);
 
+/**
+ * Scan file content for inline npm: imports and return { name: version } pairs.
+ * Matches patterns like: from "npm:fuse.js@7.0.0"
+ */
+function extractInlineNpmDeps(content: string): Record<string, string> {
+  const deps: Record<string, string> = {};
+  const regex = /from\s+["']npm:(@?[^@"']+)(?:@([^"']+))?["']/g;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    const name = match[1];
+    const version = match[2] || "*";
+    // Skip framework deps
+    if (name.startsWith("preact") || name.startsWith("@preact/")) continue;
+    deps[name] = `^${version}`;
+  }
+  return deps;
+}
+
 function detectPatterns(content: string): DetectedPattern[] {
   const patterns: DetectedPattern[] = [];
   for (const [name, regex] of PATTERN_DETECTORS) {
@@ -154,6 +193,14 @@ function decideAction(
     return { action: "delete", notes: "Rewritten from scratch" };
   }
 
+  // Loaders that depend on deleted admin tooling
+  if (LOADER_DELETE.has(relPath)) {
+    return {
+      action: "delete",
+      notes: "Admin icon loader — depends on deleted static/adminIcons.ts",
+    };
+  }
+
   // SDK files to delete
   if (SDK_DELETE.has(relPath)) {
     return {
@@ -192,6 +239,11 @@ function decideAction(
     };
   }
 
+  // Static code/tooling files → delete
+  if (STATIC_DELETE.has(relPath)) {
+    return { action: "delete", notes: "Code/tooling file, not an asset" };
+  }
+
   // Static files → move
   if (category === "static") {
     const publicPath = relPath.replace("static/", "public/");
@@ -329,6 +381,21 @@ export function analyze(ctx: MigrationContext): void {
     byCategory[f.category] = (byCategory[f.category] || 0) + 1;
   }
 
+  // Scan all source files for inline npm: imports
+  for (const f of ctx.files) {
+    if (f.action === "delete") continue;
+    const ext = path.extname(f.path);
+    if (![".ts", ".tsx"].includes(ext)) continue;
+    try {
+      const content = fs.readFileSync(f.absPath, "utf-8");
+      const deps = extractInlineNpmDeps(content);
+      Object.assign(ctx.discoveredNpmDeps, deps);
+    } catch {}
+  }
+  if (Object.keys(ctx.discoveredNpmDeps).length > 0) {
+    log(ctx, `Discovered npm deps from source: ${JSON.stringify(ctx.discoveredNpmDeps)}`);
+  }
+
   console.log(`\n  Files found: ${ctx.files.length}`);
   console.log(`  By category: ${JSON.stringify(byCategory)}`);
   console.log(`  By action: ${JSON.stringify(byAction)}`);

package/scripts/migrate/phase-cleanup.ts

@@ -43,6 +43,12 @@ const WRAPPER_FILES_TO_DELETE = [
   "sections/Session.tsx",
 ];
 
+/** Loaders that depend on deleted admin tooling */
+const LOADER_FILES_TO_DELETE = [
+  "loaders/availableIcons.ts",
+  "loaders/icons.ts",
+];
+
 function deleteFileIfExists(ctx: MigrationContext, relPath: string) {
   const fullPath = path.join(ctx.sourceDir, relPath);
   if (!fs.existsSync(fullPath)) return;
@@ -185,6 +191,9 @@ export function cleanup(ctx: MigrationContext): void {
   for (const file of WRAPPER_FILES_TO_DELETE) {
     deleteFileIfExists(ctx, file);
   }
+  for (const file of LOADER_FILES_TO_DELETE) {
+    deleteFileIfExists(ctx, file);
+  }
 
   // 3. Delete directories
   console.log("  Deleting old directories...");

package/scripts/migrate/phase-verify.ts

@@ -186,23 +186,83 @@ const checks: Check[] = [
       return true;
     },
   },
+  {
+    name: "No .ts/.tsx extensions in relative import paths",
+    severity: "warning",
+    fn: (ctx) => {
+      const srcDir = path.join(ctx.sourceDir, "src");
+      if (!fs.existsSync(srcDir)) return true;
+      // Match relative imports with .ts/.tsx extensions
+      const bad = findFilesWithPattern(srcDir, /from\s+["'](?:\.\.?\/|~\/)[^"']*\.tsx?["']/);
+      if (bad.length > 0) {
+        console.log(`    Still has .ts/.tsx extensions in imports: ${bad.join(", ")}`);
+        return false;
+      }
+      return true;
+    },
+  },
+  {
+    name: "No for= in JSX (should be htmlFor=)",
+    severity: "warning",
+    fn: (ctx) => {
+      const srcDir = path.join(ctx.sourceDir, "src");
+      if (!fs.existsSync(srcDir)) return true;
+      const bad = findFilesWithPattern(srcDir, /<label[^>]*\sfor\s*=/);
+      if (bad.length > 0) {
+        console.log(`    Still has for= in JSX: ${bad.join(", ")}`);
+        return false;
+      }
+      return true;
+    },
+  },
+  {
+    name: "No relative imports to deleted SDK files",
+    severity: "error",
+    fn: (ctx) => {
+      const srcDir = path.join(ctx.sourceDir, "src");
+      if (!fs.existsSync(srcDir)) return true;
+      // Only match relative imports (../ or ./) to deleted SDK files, not @decocms/* package imports
+      const bad = findFilesWithPattern(srcDir, /from\s+["'](?:\.\.?\/)[^"']*\/sdk\/(?:clx|useId|useOffer|useVariantPossiblities|usePlatform)["']/);
+      if (bad.length > 0) {
+        console.log(`    Still has relative imports to deleted SDK files: ${bad.join(", ")}`);
+        return false;
+      }
+      return true;
+    },
+  },
+  {
+    name: "No imports to deleted static files",
+    severity: "error",
+    fn: (ctx) => {
+      const srcDir = path.join(ctx.sourceDir, "src");
+      if (!fs.existsSync(srcDir)) return true;
+      const bad = findFilesWithPattern(srcDir, /from\s+["'][^"']*static\/adminIcons/);
+      if (bad.length > 0) {
+        console.log(`    Still has imports to static/adminIcons: ${bad.join(", ")}`);
+        return false;
+      }
+      return true;
+    },
+  },
 ];
 
 function findFilesWithPattern(
   dir: string,
   pattern: RegExp,
   results: string[] = [],
+  baseDir?: string,
 ): string[] {
+  const root = baseDir ?? dir;
   const entries = fs.readdirSync(dir, { withFileTypes: true });
   for (const entry of entries) {
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name === ".git") continue;
-      findFilesWithPattern(fullPath, pattern, results);
+      if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "server") continue;
+      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)) {
-        results.push(path.relative(dir, fullPath));
+        results.push(path.basename(fullPath));
       }
     }
   }

package/scripts/migrate/templates/package-json.ts

@@ -1,6 +1,37 @@
 import type { MigrationContext } from "../types.ts";
 
+/**
+ * Extract npm dependencies from deno.json import map.
+ * Entries like `"fuse.js": "npm:fuse.js@7.0.0"` become `"fuse.js": "^7.0.0"`.
+ */
+function extractNpmDeps(importMap: Record<string, string>): Record<string, string> {
+  const deps: Record<string, string> = {};
+  for (const [key, value] of Object.entries(importMap)) {
+    if (!value.startsWith("npm:")) continue;
+    // Skip preact, deco, and other framework deps we handle ourselves
+    if (key.startsWith("preact") || key.startsWith("@preact/")) continue;
+    if (key.startsWith("@deco/")) continue;
+    if (key === "daisyui") continue; // we pin our own version
+
+    const raw = value.slice(4); // remove "npm:"
+    const atIdx = raw.lastIndexOf("@");
+    if (atIdx <= 0) {
+      deps[raw] = "*";
+    } else {
+      const name = raw.slice(0, atIdx);
+      const version = raw.slice(atIdx + 1);
+      deps[name] = `^${version}`;
+    }
+  }
+  return deps;
+}
+
 export function generatePackageJson(ctx: MigrationContext): string {
+  const siteDeps = {
+    ...extractNpmDeps(ctx.importMap),
+    ...ctx.discoveredNpmDeps,
+  };
+
   const pkg = {
     name: ctx.siteName,
     version: "0.1.0",
@@ -21,12 +52,18 @@ export function generatePackageJson(ctx: MigrationContext): string {
       format: 'prettier --write "src/**/*.{ts,tsx}"',
       "format:check": 'prettier --check "src/**/*.{ts,tsx}"',
       knip: "knip",
+      clean:
+        "rm -rf node_modules .cache dist .wrangler/state node_modules/.vite && npm install",
+      "tailwind:lint":
+        "tsx node_modules/@decocms/start/scripts/tailwind-lint.ts",
+      "tailwind:fix":
+        "tsx node_modules/@decocms/start/scripts/tailwind-lint.ts --fix",
     },
     author: "deco.cx",
     license: "MIT",
     dependencies: {
       "@decocms/apps": "^0.25.2",
-      "@decocms/start": "^0.31.1",
+      "@decocms/start": "^0.32.0",
       "@tanstack/react-query": "5.90.21",
       "@tanstack/react-router": "1.166.7",
       "@tanstack/react-start": "1.166.8",
@@ -35,6 +72,7 @@ export function generatePackageJson(ctx: MigrationContext): string {
       "colorjs.io": "^0.6.1",
       react: "^19.2.4",
       "react-dom": "^19.2.4",
+      ...siteDeps,
     },
     devDependencies: {
       "@cloudflare/vite-plugin": "^1.27.0",
@@ -48,6 +86,7 @@ export function generatePackageJson(ctx: MigrationContext): string {
       knip: "^5.61.2",
       prettier: "^3.5.3",
       tailwindcss: "^4.2.1",
+      "ts-morph": "^27.0.2",
       tsx: "^4.19.4",
       typescript: "^5.9.3",
       vite: "^7.3.1",

package/scripts/migrate/templates/routes.ts

@@ -71,7 +71,7 @@ function NavigationProgress() {
 function StableOutlet() {
   const isLoading = useRouterState({ select: (s) => s.isLoading });
   const ref = useRef<HTMLDivElement>(null);
-  const savedHeight = useRef<number | undefined>();
+  const savedHeight = useRef<number | undefined>(undefined);
 
   useEffect(() => {
     if (isLoading && ref.current) {

package/scripts/migrate/templates/server-entry.ts

@@ -22,7 +22,7 @@ export default createStartHandler(defaultStreamHandler);
 `;
 }
 
-function generateWorkerEntry(ctx: MigrationContext): string {
+function generateWorkerEntry(_ctx: MigrationContext): string {
   return `/**
  * Cloudflare Worker entry point.
  *
@@ -30,13 +30,28 @@ function generateWorkerEntry(ctx: MigrationContext): string {
  * around the TanStack Start handler. Add proxy logic, security headers, or
  * A/B testing as needed.
  */
-import { createDecoWorkerEntry } from "@decocms/start/worker";
-
-const handler = createDecoWorkerEntry({
-  siteName: "${ctx.siteName}",
+import "./setup";
+import handler, { createServerEntry } from "@tanstack/react-start/server-entry";
+import { createDecoWorkerEntry } from "@decocms/start/sdk/workerEntry";
+import {
+  handleMeta,
+  handleDecofileRead,
+  handleDecofileReload,
+  handleRender,
+  corsHeaders,
+} from "@decocms/start/admin";
+
+const serverEntry = createServerEntry({ fetch: handler.fetch });
+
+export default createDecoWorkerEntry(serverEntry, {
+  admin: {
+    handleMeta,
+    handleDecofileRead,
+    handleDecofileReload,
+    handleRender,
+    corsHeaders,
+  },
 });
-
-export default handler;
 `;
 }
 

package/scripts/migrate/templates/setup.ts

@@ -7,8 +7,18 @@ export function generateSetup(_ctx: MigrationContext): string {
  * This file is imported by router.tsx at startup.
  * It uses import.meta.glob to lazily discover all section components.
  */
-import { registerSections } from "@decocms/start/cms";
-import { registerMatcher } from "@decocms/start/matchers";
+import { blocks as generatedBlocks } from "./server/cms/blocks.gen";
+import {
+  registerSections,
+  setBlocks,
+} from "@decocms/start/cms";
+import { registerBuiltinMatchers } from "@decocms/start/matchers/builtins";
+
+// -- CMS Blocks --
+// The Vite plugin intercepts the blocks.gen import and injects .deco/blocks/ data.
+if (typeof document === "undefined") {
+  setBlocks(generatedBlocks);
+}
 
 // -- Section Registry --
 // Discovers all .tsx files under src/sections/ and registers them as CMS blocks.
@@ -16,17 +26,6 @@ const sectionModules = import.meta.glob("./sections/**/*.tsx");
 registerSections(sectionModules);
 
 // -- Matchers --
-// Register any custom matchers here.
-// Example: registerMatcher("device", deviceMatcher);
-
-// -- Loader Cache --
-// Register cached loaders here if needed.
-// Example:
-// import { createCachedLoader } from "@decocms/start/loaders";
-// registerLoader("productList", createCachedLoader(vtexProductList, { ttl: 60_000 }));
-
-// -- CMS Blocks --
-// Load generated blocks at module level so they're available for resolution.
-import "./server/cms/blocks.gen";
+registerBuiltinMatchers();
 `;
 }

package/scripts/migrate/transforms/deno-isms.ts

@@ -14,33 +14,28 @@ export function transformDenoIsms(content: string): TransformResult {
   let result = content;
 
   // Remove deno-lint-ignore comments (single line and file-level)
-  const denoLintRegex = /^\s*\/\/\s*deno-lint-ignore[^\n]*\n?/gm;
-  if (denoLintRegex.test(result)) {
-    result = result.replace(denoLintRegex, "");
+  // Also handle JSX comment form: {/* deno-lint-ignore ... */}
+  if (/deno-lint-ignore/.test(result)) {
+    result = result.replace(/^\s*\/\/\s*deno-lint-ignore[^\n]*\n?/gm, "");
+    result = result.replace(/\s*\{\/\*\s*deno-lint-ignore[^*]*\*\/\}\s*/g, " ");
     changed = true;
     notes.push("Removed deno-lint-ignore comments");
   }
 
   // Remove npm: prefix in import specifiers that weren't caught by imports transform
-  const npmPrefixRegex = /(from\s+["'])npm:([^"'@][^"']*)(["'])/g;
-  if (npmPrefixRegex.test(result)) {
+  if (/from\s+["']npm:/.test(result)) {
+    // npm:pkg@version → pkg (strip version)
     result = result.replace(
-      /(from\s+["'])npm:([^"'@][^"']*)(["'])/g,
+      /(from\s+["'])npm:(@?[^@"']+)@[^"']*(["'])/g,
       "$1$2$3",
     );
-    changed = true;
-    notes.push("Removed npm: prefix from imports");
-  }
-
-  // npm:pkg@version → pkg (strip version too)
-  const npmVersionRegex = /(from\s+["'])npm:(@?[^@"']+)@[^"']*(["'])/g;
-  if (npmVersionRegex.test(result)) {
+    // npm:pkg → pkg (no version)
     result = result.replace(
-      /(from\s+["'])npm:(@?[^@"']+)@[^"']*(["'])/g,
+      /(from\s+["'])npm:([^"'@][^"']*)(["'])/g,
       "$1$2$3",
     );
     changed = true;
-    notes.push("Removed npm: prefix and version from imports");
+    notes.push("Removed npm: prefix from imports");
   }
 
   // Remove Deno.* API usages — flag for manual review

package/scripts/migrate/transforms/fresh-apis.ts

@@ -1,5 +1,53 @@
 import type { TransformResult } from "../types.ts";
 
+/**
+ * Fix JSX after scriptAsDataURI → useScript replacement.
+ *
+ * Transforms patterns like:
+ *   <script dangerouslySetInnerHTML={{ __html: useScript(fn, { ...props, x })}
+ *     defer
+ *   />
+ * Into:
+ *   <script dangerouslySetInnerHTML={{ __html: useScript(fn, { ...props, x }) }}
+ *   />
+ *
+ * The key issue: the original `src={scriptAsDataURI(...)}` has one closing `}`,
+ * but `dangerouslySetInnerHTML={{ __html: useScript(...) }}` needs two closing `}}`.
+ * We also need to remove stray attrs like `defer` that sit between the call and `/>`.
+ */
+function rebalanceScriptDataUri(code: string): string {
+  const marker = "dangerouslySetInnerHTML={{ __html: useScript(";
+  let idx = code.indexOf(marker);
+
+  while (idx !== -1) {
+    const start = idx + marker.length;
+    // Find the balanced closing paren for useScript(
+    let depth = 1;
+    let i = start;
+    while (i < code.length && depth > 0) {
+      if (code[i] === "(") depth++;
+      else if (code[i] === ")") depth--;
+      i++;
+    }
+    // i is now right after the matching ) of useScript(...)
+    // We expect `}` next (closing the old src={...})
+    // We need to replace everything from ) to /> with `) }} />`
+    // and remove any stray attributes like `defer`, `type="module"`, etc.
+    const afterParen = code.substring(i);
+    const closingMatch = afterParen.match(/^\s*\}\s*\n?\s*([\s\S]*?)\s*\/>/);
+    if (closingMatch) {
+      const endOffset = i + closingMatch[0].length;
+      // i is already past the closing ), so just add the }} and />
+      const replacement = ` }}\n    />`;
+      code = code.substring(0, i) + replacement + code.substring(endOffset);
+    }
+
+    idx = code.indexOf(marker, idx + 1);
+  }
+
+  return code;
+}
+
 /**
  * Removes or replaces Fresh-specific APIs:
  *
@@ -15,8 +63,7 @@ export function transformFreshApis(content: string): TransformResult {
   let result = content;
 
   // asset("/path") → "/path" and asset(`/path`) → `/path`
-  const assetCallRegex = /\basset\(\s*(`[^`]+`|"[^"]+"|'[^']+')\s*\)/g;
-  if (assetCallRegex.test(result)) {
+  if (/\basset\(/.test(result)) {
     result = result.replace(
       /\basset\(\s*(`[^`]+`|"[^"]+"|'[^']+')\s*\)/g,
       (_match, path) => {
@@ -104,6 +151,66 @@ export function transformFreshApis(content: string): TransformResult {
     );
   }
 
+  // scriptAsDataURI → useScript with dangerouslySetInnerHTML
+  // scriptAsDataURI is a Fresh pattern that returns a data: URI for <script src=...>.
+  // In React/TanStack, useScript returns a string for dangerouslySetInnerHTML.
+  //
+  // Before: <script src={scriptAsDataURI(fn, arg1, arg2)} defer />
+  // After:  <script dangerouslySetInnerHTML={{ __html: useScript(fn, arg1, arg2) }} />
+  if (result.includes("scriptAsDataURI")) {
+    // Ensure useScript is imported
+    if (
+      !result.includes('"@decocms/start/sdk/useScript"') &&
+      !result.includes("'@decocms/start/sdk/useScript'")
+    ) {
+      result = `import { useScript } from "@decocms/start/sdk/useScript";\n${result}`;
+    }
+
+    // Transform src={scriptAsDataURI(...)} into dangerouslySetInnerHTML={{ __html: useScript(...) }}
+    // We need to match balanced parens to capture the full argument list.
+    result = result.replace(
+      /\bsrc=\{scriptAsDataURI\(/g,
+      "dangerouslySetInnerHTML={{ __html: useScript(",
+    );
+
+    // Now close the pattern: find the matching )} and replace with ) }}
+    // The pattern after replacement is: dangerouslySetInnerHTML={{ __html: useScript(...)}<maybe whitespace and other attrs>
+    // We need to find the closing )} that ends the JSX expression
+    result = rebalanceScriptDataUri(result);
+
+    // Replace any remaining standalone scriptAsDataURI references
+    result = result.replace(/\bscriptAsDataURI\b/g, "useScript");
+
+    changed = true;
+    notes.push("Replaced scriptAsDataURI with useScript + dangerouslySetInnerHTML");
+  }
+
+  // allowCorsFor — not available in @decocms/start, remove usage
+  if (result.includes("allowCorsFor")) {
+    result = result.replace(
+      /^import\s+\{[^}]*\ballowCorsFor\b[^}]*\}\s+from\s+["'][^"']+["'];?\s*\n?/gm,
+      "",
+    );
+    // Remove allowCorsFor calls
+    result = result.replace(/\ballowCorsFor\b\([^)]*\);?\s*\n?/g, "");
+    changed = true;
+    notes.push("Removed allowCorsFor (not needed in TanStack)");
+  }
+
+  // ctx.response.headers → not available, flag
+  if (result.includes("ctx.response")) {
+    notes.push("MANUAL: ctx.response usage found — FnContext in @decocms/start does not have response object");
+  }
+
+  // { crypto } from "@std/crypto" → use globalThis.crypto (Web Crypto API)
+  // The import is already removed by imports transform, but `crypto` references
+  // need to be prefixed with globalThis if they'd shadow the global
+  if (result.match(/^import\s+\{[^}]*\bcrypto\b/m)) {
+    // Import already removed by imports transform, so just ensure bare `crypto` works
+    // No action needed — globalThis.crypto is available in Workers + Node 20+
+    notes.push("INFO: @std/crypto replaced with globalThis.crypto (Web Crypto API)");
+  }
+
   // Clean up blank lines
   result = result.replace(/\n{3,}/g, "\n\n");
 

package/scripts/migrate/transforms/imports.ts

@@ -25,7 +25,7 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   [/^"@deco\/deco"$/, `"@decocms/start"`],
 
   // Apps — widgets & components
-  [/^"apps\/admin\/widgets\.ts"$/, `"@decocms/start/admin/widgets"`],
+  [/^"apps\/admin\/widgets\.ts"$/, `"@decocms/start/types/widgets"`],
   [/^"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"`],
@@ -37,13 +37,41 @@ const IMPORT_RULES: Array<[RegExp, string | null]> = [
   // Deco old CDN imports
   [/^"deco\/([^"]+)"$/, null],
 
-  // Std lib — not needed in Node
+  // Std lib — not needed in Node (Deno std lib)
   [/^"std\/([^"]+)"$/, null],
+  [/^"@std\/crypto"$/, null], // Use globalThis.crypto instead
+
+  // site/sdk/* → framework equivalents (before the catch-all site/ → ~/ rule)
+  [/^"site\/sdk\/clx(?:\.tsx?)?.*"$/, `"@decocms/start/sdk/clx"`],
+  [/^"site\/sdk\/useId(?:\.tsx?)?.*"$/, `"react"`],
+  [/^"site\/sdk\/useOffer(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/useOffer"`],
+  [/^"site\/sdk\/useVariantPossiblities(?:\.tsx?)?.*"$/, `"@decocms/apps/commerce/sdk/useVariantPossibilities"`],
+  [/^"site\/sdk\/usePlatform(?:\.tsx?)?.*"$/, null],
 
   // site/ → ~/
   [/^"site\/(.+)"$/, `"~/$1"`],
 ];
 
+/**
+ * Relative import rewrites for SDK files that are deleted during migration.
+ * These are matched against the resolved import path (after ../.. resolution).
+ * The key is the ending of the import path, the value is the replacement specifier.
+ */
+const RELATIVE_SDK_REWRITES: Array<[RegExp, string]> = [
+  // sdk/clx → @decocms/start/sdk/clx
+  [/(?:\.\.\/)*sdk\/clx(?:\.tsx?)?$/, "@decocms/start/sdk/clx"],
+  // sdk/useId → react (useId is built-in in React 19)
+  [/(?:\.\.\/)*sdk\/useId(?:\.tsx?)?$/, "react"],
+  // sdk/useOffer → @decocms/apps/commerce/sdk/useOffer
+  [/(?:\.\.\/)*sdk\/useOffer(?:\.tsx?)?$/, "@decocms/apps/commerce/sdk/useOffer"],
+  // sdk/useVariantPossiblities → @decocms/apps/commerce/sdk/useVariantPossibilities
+  [/(?:\.\.\/)*sdk\/useVariantPossiblities(?:\.tsx?)?$/, "@decocms/apps/commerce/sdk/useVariantPossibilities"],
+  // sdk/usePlatform → remove entirely
+  [/(?:\.\.\/)*sdk\/usePlatform(?:\.tsx?)?$/, ""],
+  // static/adminIcons → deleted (icon loaders need rewriting)
+  [/(?:\.\.\/)*static\/adminIcons(?:\.ts)?$/, ""],
+];
+
 /**
  * Rewrites import specifiers in a file.
  *
@@ -67,6 +95,36 @@ export function transformImports(content: string): TransformResult {
     /^(export\s+(?:type\s+)?\{[^}]*\}\s+from\s+)("[^"]+"|'[^']+')(;?\s*)$/gm;
   const sideEffectImportRegex = /^(import\s+)("[^"]+"|'[^']+')(;?\s*)$/gm;
 
+  /**
+   * Post-process: split @deco/deco/hooks imports.
+   * In the old stack, @deco/deco/hooks exported useDevice, useScript, useSection, etc.
+   * In @decocms/start, useDevice is at @decocms/start/sdk/useDevice.
+   * After import rewriting, we need to split lines like:
+   *   import { useDevice, useScript } from "@decocms/start/sdk/useScript"
+   * into:
+   *   import { useDevice } from "@decocms/start/sdk/useDevice"
+   *   import { useScript } from "@decocms/start/sdk/useScript"
+   */
+  function splitDecoHooksImports(code: string): string {
+    return code.replace(
+      /^(import\s+(?:type\s+)?\{)([^}]*\buseDevice\b[^}]*)(\}\s+from\s+["']@decocms\/start\/sdk\/useScript["'];?)$/gm,
+      (_match, _prefix, importList, _suffix) => {
+        const items = importList.split(",").map((s: string) => s.trim()).filter(Boolean);
+        const deviceItems = items.filter((s: string) => s.includes("useDevice"));
+        const otherItems = items.filter((s: string) => !s.includes("useDevice"));
+
+        const lines: string[] = [];
+        if (deviceItems.length > 0) {
+          lines.push(`import { ${deviceItems.join(", ")} } from "@decocms/start/sdk/useDevice";`);
+        }
+        if (otherItems.length > 0) {
+          lines.push(`import { ${otherItems.join(", ")} } from "@decocms/start/sdk/useScript";`);
+        }
+        return lines.join("\n");
+      },
+    );
+  }
+
   function rewriteSpecifier(specifier: string): string | null {
     // Remove quotes for matching
     const inner = specifier.slice(1, -1);
@@ -75,7 +133,26 @@ export function transformImports(content: string): TransformResult {
       if (pattern.test(`"${inner}"`)) {
         if (replacement === null) return null;
         // Apply regex replacement
-        return `"${inner}"`.replace(pattern, replacement);
+        let result = `"${inner}"`.replace(pattern, replacement);
+        // Strip .ts/.tsx extensions from the rewritten path if it's a relative/alias import
+        const resultInner = result.slice(1, -1);
+        if (
+          (resultInner.startsWith("~/") || resultInner.startsWith("./") || resultInner.startsWith("../")) &&
+          (resultInner.endsWith(".ts") || resultInner.endsWith(".tsx"))
+        ) {
+          result = `"${resultInner.replace(/\.tsx?$/, "")}"`;
+        }
+        return result;
+      }
+    }
+
+    // Relative imports pointing to deleted SDK files → framework equivalents
+    if (inner.startsWith("./") || inner.startsWith("../")) {
+      for (const [pattern, replacement] of RELATIVE_SDK_REWRITES) {
+        if (pattern.test(inner)) {
+          if (replacement === "") return null; // remove the import
+          return `"${replacement}"`;
+        }
       }
     }
 
@@ -125,6 +202,14 @@ export function transformImports(content: string): TransformResult {
   result = result.replace(reExportLineRegex, processLine);
   result = result.replace(sideEffectImportRegex, processLine);
 
+  // Split @deco/deco/hooks imports that contain useDevice
+  const afterSplit = splitDecoHooksImports(result);
+  if (afterSplit !== result) {
+    result = afterSplit;
+    changed = true;
+    notes.push("Split useDevice into separate import from @decocms/start/sdk/useDevice");
+  }
+
   // Clean up blank lines left by removed imports (collapse multiple to one)
   result = result.replace(/\n{3,}/g, "\n\n");
 

package/scripts/migrate/transforms/jsx.ts

@@ -17,8 +17,7 @@ export function transformJsx(content: string): TransformResult {
 
   // class= → className= in JSX attributes
   // Match class= that's preceded by whitespace and inside a JSX tag
-  const classAttrRegex = /(<[a-zA-Z][^>]*?\s)class(\s*=)/g;
-  if (classAttrRegex.test(result)) {
+  if (/(<[a-zA-Z][^>]*?\s)class(\s*=)/.test(result)) {
     result = result.replace(
       /(<[a-zA-Z][^>]*?\s)class(\s*=)/g,
       "$1className$2",
@@ -28,9 +27,8 @@ export function transformJsx(content: string): TransformResult {
   }
 
   // Also handle class= at the start of a line in JSX (multi-line attributes)
-  const standaloneClassRegex = /^(\s+)class(\s*=)/gm;
-  if (standaloneClassRegex.test(result)) {
-    result = result.replace(standaloneClassRegex, "$1className$2");
+  if (/^(\s+)class(\s*=)/m.test(result)) {
+    result = result.replace(/^(\s+)class(\s*=)/gm, "$1className$2");
     changed = true;
   }
 
@@ -41,15 +39,46 @@ export function transformJsx(content: string): TransformResult {
     notes.push("Replaced onInput= with onChange=");
   }
 
-  // ComponentChildren → React.ReactNode
+  // for= → htmlFor= in JSX (label elements)
+  if (/(<(?:label|Label)[^>]*?\s)for(\s*=)/.test(result)) {
+    result = result.replace(
+      /(<(?:label|Label)[^>]*?\s)for(\s*=)/g,
+      "$1htmlFor$2",
+    );
+    changed = true;
+    notes.push("Replaced for= with htmlFor= on label elements");
+  }
+  // Also handle for= at the start of a line in multi-line JSX attributes
+  if (/^\s+for\s*=\s*\{/m.test(result)) {
+    result = result.replace(/^(\s+)for(\s*=\s*\{)/gm, "$1htmlFor$2");
+    changed = true;
+  }
+
+  // ComponentChildren → ReactNode (named import, not React.ReactNode)
   if (result.includes("ComponentChildren")) {
-    result = result.replace(/\bComponentChildren\b/g, "React.ReactNode");
-    // Add React import if not present
-    if (!result.includes('from "react"') && !result.includes("from 'react'")) {
-      result = `import React from "react";\n${result}`;
+    result = result.replace(/\bComponentChildren\b/g, "ReactNode");
+    // Add ReactNode import if not already imported
+    if (
+      !result.match(/\bReactNode\b.*from\s+["']react["']/) &&
+      !result.match(/from\s+["']react["'].*\bReactNode\b/)
+    ) {
+      // Check if there's already a react import we can extend
+      const reactImportMatch = result.match(
+        /^(import\s+(?:type\s+)?\{)([^}]*?)(\}\s+from\s+["']react["'];?)$/m,
+      );
+      if (reactImportMatch) {
+        const [fullMatch, prefix, existing, suffix] = reactImportMatch;
+        const items = existing.trim();
+        result = result.replace(
+          fullMatch,
+          `${prefix}${items ? `${items}, ` : ""}type ReactNode${suffix}`,
+        );
+      } else {
+        result = `import type { ReactNode } from "react";\n${result}`;
+      }
     }
     changed = true;
-    notes.push("Replaced ComponentChildren with React.ReactNode");
+    notes.push("Replaced ComponentChildren with ReactNode");
   }
 
   // JSX.SVGAttributes<SVGSVGElement> → React.SVGAttributes<SVGSVGElement>
@@ -96,6 +125,52 @@ export function transformJsx(content: string): TransformResult {
     "",
   );
 
+  // tabindex → tabIndex in JSX
+  if (/\btabindex\s*=/.test(result)) {
+    result = result.replace(/\btabindex(\s*=)/g, "tabIndex$1");
+    changed = true;
+    notes.push("Replaced tabindex with tabIndex");
+  }
+
+  // frameBorder → frameBorder (already camelCase, but just in case)
+  // referrerpolicy → referrerPolicy
+  if (result.includes("referrerpolicy=")) {
+    result = result.replace(/referrerpolicy=/g, "referrerPolicy=");
+    changed = true;
+    notes.push("Replaced referrerpolicy with referrerPolicy");
+  }
+
+  // allowFullScreen={true} is fine in React, but allowfullscreen is not
+  if (result.includes("allowfullscreen")) {
+    result = result.replace(/\ballowfullscreen\b/g, "allowFullScreen");
+    changed = true;
+  }
+
+  // `class` as a prop name in destructuring patterns → `className`
+  // Matches: { class: someVar } or { class, } or { ..., class: x } in function params
+  if (/[{,]\s*class\s*[,}:]/.test(result)) {
+    // class: varName → className: varName (anywhere in destructuring)
+    result = result.replace(
+      /([{,]\s*)class(\s*:\s*\w+)/g,
+      "$1className$2",
+    );
+    // class, → className, (shorthand, anywhere in destructuring)
+    result = result.replace(
+      /([{,]\s*)class(\s*[,}])/g,
+      "$1className$2",
+    );
+    changed = true;
+    notes.push("Replaced 'class' prop in destructuring with 'className'");
+  }
+
+  // `class` in interface/type definitions → className
+  // Matches: class?: string; or class: string;
+  if (/^\s+class\??\s*:/m.test(result)) {
+    result = result.replace(/^(\s+)class(\??\s*:)/gm, "$1className$2");
+    changed = true;
+    notes.push("Replaced 'class' in interface definitions with 'className'");
+  }
+
   // Ensure React import exists if we introduced React.* references
   if (
     (result.includes("React.") || result.includes("React,")) &&

package/scripts/migrate/types.ts

@@ -72,6 +72,9 @@ export interface MigrationContext {
   /** deno.json import map entries */
   importMap: Record<string, string>;
 
+  /** npm dependencies discovered from inline npm: imports in source files */
+  discoveredNpmDeps: Record<string, string>;
+
   /** All categorized source files */
   files: FileRecord[];
 
@@ -114,6 +117,7 @@ export function createContext(
     platform: "custom",
     gtmId: null,
     importMap: {},
+    discoveredNpmDeps: {},
     files: [],
     scaffoldedFiles: [],
     transformedFiles: [],

package/src/types/widgets.ts

@@ -11,3 +11,4 @@ export type RichText = string;
 export type Secret = string;
 export type Color = string;
 export type ButtonWidget = string;
+export type TextArea = string;