@decocms/blocks-cli 7.46.1 → 7.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.46.1",
+  "version": "7.48.0",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -32,7 +32,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.46.1",
+    "@decocms/blocks": "7.48.0",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/migrate/icon-casing.test.ts

@@ -0,0 +1,63 @@
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { reconcileIconCasing } from "./phase-transform";
+import { createContext, type MigrationContext } from "./types";
+
+let dir: string;
+let ctx: MigrationContext;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "icon-casing-"));
+  mkdirSync(join(dir, "src", "components", "ui"), { recursive: true });
+  mkdirSync(join(dir, "src", "sections"), { recursive: true });
+  writeFileSync(
+    join(dir, "src", "components", "ui", "Icon.tsx"),
+    `export type AvailableIcons =\n  | "Close"\n  | "Menu"\n  | "ChevronDown";\n`,
+  );
+  ctx = createContext(dir);
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe("reconcileIconCasing", () => {
+  it("case-corrects <Icon id> to match the declared AvailableIcons", () => {
+    const f = join(dir, "src", "sections", "Drawer.tsx");
+    writeFileSync(f, `<Icon id="close" /> <Icon id="menu" /> <Icon id="Close" />`);
+    reconcileIconCasing(ctx);
+    const out = readFileSync(f, "utf8");
+    expect(out).toContain(`id="Close"`);
+    expect(out).toContain(`id="Menu"`);
+    expect(out).not.toContain(`id="close"`);
+    expect(out).not.toContain(`id="menu"`);
+  });
+
+  it("flags a used icon that is NOT in AvailableIcons (no blind rename)", () => {
+    const f = join(dir, "src", "sections", "Search.tsx");
+    writeFileSync(f, `<Icon id="search" />`);
+    reconcileIconCasing(ctx);
+    // left as-is
+    expect(readFileSync(f, "utf8")).toContain(`id="search"`);
+    // flagged for manual review, once
+    const flags = ctx.manualReviewItems.filter((m) => m.reason.includes(`id="search"`));
+    expect(flags).toHaveLength(1);
+    expect(flags[0]!.file).toBe("src/sections/Search.tsx");
+  });
+
+  it("only touches <Icon id>, not other id= attributes", () => {
+    const f = join(dir, "src", "sections", "Nav.tsx");
+    writeFileSync(f, `<div id="close-button"><Icon id="close" /></div>`);
+    reconcileIconCasing(ctx);
+    const out = readFileSync(f, "utf8");
+    expect(out).toContain(`<div id="close-button">`); // untouched
+    expect(out).toContain(`<Icon id="Close" />`); // corrected
+  });
+
+  it("no-op when the site declares no AvailableIcons", () => {
+    rmSync(join(dir, "src", "components", "ui", "Icon.tsx"));
+    const f = join(dir, "src", "sections", "X.tsx");
+    writeFileSync(f, `<Icon id="close" />`);
+    reconcileIconCasing(ctx);
+    expect(readFileSync(f, "utf8")).toContain(`id="close"`); // unchanged
+  });
+});

package/scripts/migrate/phase-analyze.ts

@@ -666,8 +666,16 @@ export function analyze(ctx: MigrationContext): void {
     console.log(`  Font: ${ctx.fontFamily}`);
   }
 
-  // Scan all files
+  // Scan all files. The root scan skips `src/` (SKIP_DIRS) — for a MODERN
+  // layout the code lives there, so scan `src/` separately with baseDir=src so
+  // its files categorize as if they were at root (`src/sections/X` → `sections/X`
+  // → section → targetPath `src/sections/X`). The root scan still handles config
+  // + static/ at the repo root.
   scanDir(ctx.sourceDir, ctx.sourceDir, ctx.files);
+  if (ctx.layout === "modern") {
+    const srcDir = path.join(ctx.sourceDir, "src");
+    if (fs.existsSync(srcDir)) scanDir(srcDir, srcDir, ctx.files);
+  }
 
   // Summary
   const byAction = { transform: 0, delete: 0, move: 0, scaffold: 0, "manual-review": 0 };

package/scripts/migrate/phase-scaffold.ts

@@ -387,7 +387,12 @@ export default debounce;
 
 function generateSignalShim(): string {
   return `import { useState, useRef, useEffect, useMemo, useCallback, useSyncExternalStore } from "react";
-export { signal, type ReactiveSignal } from "@decocms/blocks/sdk/signal";
+// Import locally (so \`ReactiveSignal\` is in scope for useSignalValue below) AND
+// re-export for consumers. A bare \`export { … } from\` re-export does NOT bind the
+// name locally — using it as a type then fails with "Cannot find name".
+import { signal, type ReactiveSignal } from "@decocms/blocks/sdk/signal";
+export { signal };
+export type { ReactiveSignal };
 
 /** Run a function immediately. Kept for legacy module-level side effects. */
 export function effect(fn: () => void | (() => void)): () => void {

package/scripts/migrate/phase-transform.ts

@@ -5,12 +5,15 @@ import type { MigrationContext, TransformResult, SectionMeta } from "./types";
 import { log, logPhase } from "./types";
 import { transformImports } from "./transforms/imports";
 import { transformJsx } from "./transforms/jsx";
+import { transformPicture } from "./transforms/picture";
+import { transformTimerTypes } from "./transforms/timer-types";
 import { transformFreshApis } from "./transforms/fresh-apis";
 import { transformCtxCompat } from "./transforms/ctx-compat";
 import { transformDenoIsms } from "./transforms/deno-isms";
 import { transformTailwind } from "./transforms/tailwind";
 import { transformDeadCode } from "./transforms/dead-code";
 import { transformHtmxOnEvents } from "./transforms/htmx-on-events";
+import { transformUseScriptHandlers } from "./transforms/use-script-handlers";
 import { createSectionConventionsTransform } from "./transforms/section-conventions";
 
 /** Map of section path → metadata, populated per-run */
@@ -67,10 +70,13 @@ function applyTransforms(content: string, filePath: string, ctx?: MigrationConte
     { name: "imports", fn: (c) => transformImports(c, ctx?.islandWrapperTargets) },
     { name: "jsx", fn: transformJsx },
     { name: "htmx-on-events", fn: transformHtmxOnEvents },
+    { name: "use-script-handlers", fn: transformUseScriptHandlers },
     { name: "fresh-apis", fn: transformFreshApis },
     { name: "ctx-compat", fn: transformCtxCompat },
     { name: "dead-code", fn: (c) => transformDeadCode(c, ctx?.platform) },
     { name: "deno-isms", fn: transformDenoIsms },
+    { name: "timer-types", fn: transformTimerTypes },
+    { name: "picture", fn: transformPicture },
     { name: "tailwind", fn: transformTailwind },
   ];
 
@@ -264,6 +270,74 @@ export function transform(ctx: MigrationContext): void {
   // the actual file and rewrite the import.
   if (!ctx.dryRun) {
     fixIslandImports(ctx);
+    reconcileIconCasing(ctx);
+  }
+}
+
+/**
+ * `<Icon id="close">` → `<Icon id="Close">`. Deco-fresh (Deno) didn't strictly
+ * typecheck, so sites often used lowercase icon ids that don't match their own
+ * PascalCase `AvailableIcons` union — the stricter TanStack typecheck then fails
+ * ("Type '\"close\"' is not assignable to type 'AvailableIcons'"). This
+ * case-corrects any `<Icon id="X">` whose name matches an AvailableIcons entry
+ * case-insensitively. Names with NO match (a genuinely missing icon) are left
+ * as-is and flagged for manual review — adding them to the type + sprite is a
+ * design decision, not a rename.
+ */
+export function reconcileIconCasing(ctx: MigrationContext): void {
+  const srcDir = path.join(ctx.sourceDir, "src");
+  if (!fs.existsSync(srcDir)) return;
+
+  const walk = (dir: string, visit: (file: string, content: string) => void) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".git") continue;
+        walk(path.join(dir, entry.name), visit);
+      } else if (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) {
+        visit(path.join(dir, entry.name), fs.readFileSync(path.join(dir, entry.name), "utf-8"));
+      }
+    }
+  };
+
+  // 1. Canonical icon names from the declared `AvailableIcons` union (if any).
+  const canonical = new Map<string, string>(); // lowercased → canonical casing
+  walk(srcDir, (_file, content) => {
+    const m = content.match(/export type AvailableIcons\s*=\s*([\s\S]*?);/);
+    if (m) for (const n of m[1].matchAll(/["']([A-Za-z0-9_-]+)["']/g)) canonical.set(n[1].toLowerCase(), n[1]);
+  });
+  if (canonical.size === 0) return;
+
+  // 2. Case-correct `<Icon id="X">` usages; flag unmatched names once per file.
+  const iconIdRe = /(<Icon\b[^>]*?\bid=["'])([A-Za-z0-9_-]+)(["'])/g;
+  let corrected = 0;
+  walk(srcDir, (file, content) => {
+    let modified = false;
+    const flagged = new Set<string>();
+    const next = content.replace(iconIdRe, (whole, pre, name, post) => {
+      const canon = canonical.get(name.toLowerCase());
+      if (canon) {
+        if (canon !== name) {
+          modified = true;
+          corrected++;
+          return `${pre}${canon}${post}`;
+        }
+        return whole;
+      }
+      if (!flagged.has(name)) {
+        flagged.add(name);
+        ctx.manualReviewItems.push({
+          file: path.relative(ctx.sourceDir, file).replace(/\\/g, "/"),
+          reason: `<Icon id="${name}"> is not in AvailableIcons — add it to the type in Icon.tsx and the sprite, or the icon renders blank.`,
+          severity: "warning",
+        });
+      }
+      return whole;
+    });
+    if (modified) fs.writeFileSync(file, next, "utf-8");
+  });
+
+  if (corrected > 0) {
+    console.log(`  Icon casing: corrected ${corrected} <Icon id> to match AvailableIcons`);
   }
 }
 

package/scripts/migrate/source-layout.test.ts

@@ -19,6 +19,26 @@ function makeFs(paths: string[]): FsLike {
   };
 }
 
+/**
+ * FsLike where each dir path is tagged as populated (has files) or empty.
+ * `dirsWithFiles` exist AND report `hasFiles: true`; `emptyDirs` exist but
+ * report `hasFiles: false` (leftover stubs).
+ */
+function makeFsWithFiles(dirsWithFiles: string[], emptyDirs: string[] = []): FsLike {
+  const norm = (p: string) => p.replace(/\\/g, "/");
+  const populated = new Set(dirsWithFiles.map(norm));
+  const empty = new Set(emptyDirs.map(norm));
+  return {
+    existsSync(p) {
+      const n = norm(p);
+      return populated.has(n) || empty.has(n);
+    },
+    hasFiles(p) {
+      return populated.has(norm(p));
+    },
+  };
+}
+
 const SITE = "/site";
 
 describe("detectSourceLayout — classic layout", () => {
@@ -64,6 +84,29 @@ describe("detectSourceLayout — mixed layout", () => {
   });
 });
 
+describe("detectSourceLayout — empty leftover dirs (hasFiles)", () => {
+  it("ignores an EMPTY root sections/ next to a populated src/sections/ → modern", () => {
+    // The real portal-davinci case: leftover empty `sections/` + real `src/sections/`.
+    const fs = makeFsWithFiles(["/site/src/sections"], ["/site/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("modern");
+  });
+
+  it("ignores an EMPTY src/sections/ next to a populated root sections/ → classic", () => {
+    const fs = makeFsWithFiles(["/site/sections"], ["/site/src/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("classic");
+  });
+
+  it("still flags genuinely mixed (both populated) as mixed", () => {
+    const fs = makeFsWithFiles(["/site/sections", "/site/src/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("mixed");
+  });
+
+  it("empty dirs on both sides → empty", () => {
+    const fs = makeFsWithFiles([], ["/site/sections", "/site/src/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("empty");
+  });
+});
+
 describe("detectSourceLayout — empty layout", () => {
   it("returns empty when neither root nor src/ has recognised dirs", () => {
     const fs = makeFs(["/site/package.json", "/site/README.md"]);

package/scripts/migrate/source-layout.ts

@@ -31,19 +31,46 @@ const RECOGNISED_DIRS = ["sections", "islands", "components", "loaders", "action
 
 export interface FsLike {
   existsSync(p: string): boolean;
+  /**
+   * True when `p` is a directory containing at least one FILE (recursively).
+   * An empty leftover dir (e.g. a `sections/` stub next to a populated
+   * `src/sections/`) must NOT count as a layout, or it triggers a false
+   * "mixed layout" abort. Optional so existing `{ existsSync }` stubs keep
+   * working — when absent, mere existence counts (previous behaviour).
+   */
+  hasFiles?(p: string): boolean;
 }
 
-const realFs: FsLike = { existsSync: fs.existsSync };
+/** Recursively: does this dir hold at least one file? Empty dirs → false. */
+function realHasFiles(p: string): boolean {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(p, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const e of entries) {
+    if (e.isFile()) return true;
+    if (e.isDirectory() && realHasFiles(path.join(p, e.name))) return true;
+  }
+  return false;
+}
+
+const realFs: FsLike = { existsSync: fs.existsSync, hasFiles: realHasFiles };
 
 /**
  * Classify the source directory's layout. Pure function — accepts
  * a `FsLike` so unit tests can stub the disk without mocking node:fs.
  */
 export function detectSourceLayout(sourceDir: string, fsAdapter: FsLike = realFs): SourceLayout {
-  const hasRootDir = RECOGNISED_DIRS.some((d) => fsAdapter.existsSync(path.join(sourceDir, d)));
-  const hasSrcDir = RECOGNISED_DIRS.some((d) =>
-    fsAdapter.existsSync(path.join(sourceDir, "src", d)),
-  );
+  // A recognised dir only "counts" if it exists AND holds files — an empty
+  // leftover `sections/` next to a populated `src/sections/` is not a real
+  // second layout and must not trigger a "mixed" abort. Falls back to mere
+  // existence when the adapter doesn't implement hasFiles (old test stubs).
+  const counts = (p: string): boolean =>
+    fsAdapter.existsSync(p) && (fsAdapter.hasFiles ? fsAdapter.hasFiles(p) : true);
+  const hasRootDir = RECOGNISED_DIRS.some((d) => counts(path.join(sourceDir, d)));
+  const hasSrcDir = RECOGNISED_DIRS.some((d) => counts(path.join(sourceDir, "src", d)));
 
   if (hasRootDir && hasSrcDir) return "mixed";
   if (hasSrcDir) return "modern";

package/scripts/migrate/transforms/jsx-class-type.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { transformJsx } from "./jsx";
+
+describe("transformJsx — class in type annotations", () => {
+  it("renames an INLINE `class?:` type property (mid-line)", () => {
+    const src = `function P({ height, className: _c }: { height: string; class?: string }) {}`;
+    const out = transformJsx(src).content;
+    expect(out).toContain("className?: string");
+    expect(out).not.toContain("class?: string");
+    // the destructuring rename is preserved
+    expect(out).toContain("className: _c");
+  });
+
+  it("still renames a line-start `class?:` in an interface", () => {
+    const out = transformJsx(`interface Props {\n  class?: string;\n}`).content;
+    expect(out).toContain("className?: string");
+  });
+
+  it("renames `class?:` inside a union member", () => {
+    const out = transformJsx(`type T = { a: 1 } | { class?: number };`).content;
+    expect(out).toContain("className?: number");
+  });
+
+  it("does NOT touch a runtime `class:` value (no `?`)", () => {
+    const out = transformJsx(`const x = { class: "btn" };`).content;
+    expect(out).toContain(`class: "btn"`);
+  });
+});

package/scripts/migrate/transforms/jsx.ts

@@ -195,6 +195,16 @@ export function transformJsx(content: string): TransformResult {
     notes.push("Replaced 'class' in interface definitions with 'className'");
   }
 
+  // `class?:` MID-LINE, inside an INLINE type literal
+  // (e.g. `{ height: string; class?: string }`). The `?` marks it as a type
+  // property — runtime objects never use `?:` — so this can't hit a real
+  // `class:` value. The line-start rule above misses the inline form.
+  if (/[{;,|(]\s*class\?\s*:/.test(result)) {
+    result = result.replace(/([{;,|(]\s*)class(\?\s*:)/g, "$1className$2");
+    changed = true;
+    notes.push("Replaced inline 'class?:' type property with 'className?:'");
+  }
+
   // Remove `alt` prop from non-img elements (<a>, <iframe>, <div>, etc.)
   // In React, `alt` is only valid on <img>, <input type="image">, <area>
   const altOnNonImgRegex = /(<(?:a|iframe|div|span|button|section)\s[^>]*?)\s+alt=(?:\{[^}]*\}|"[^"]*"|'[^']*')/g;

package/scripts/migrate/transforms/picture.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { transformPicture } from "./picture";
+
+const CLASSIC = `<Picture preload className="grid-pos">
+  <Source src={image.mobile} width={360} height={120} media="(max-width: 767px)" />
+  <Source src={image.desktop} width={1440} height={200} media="(min-width: 767px)" />
+  <img className="w-full" src={image.desktop} alt={image.alt ?? title} />
+</Picture>`;
+
+describe("transformPicture", () => {
+  it("converts <Source>+<img> children into sources[] + top-level props", () => {
+    const { content, changed, notes } = transformPicture(CLASSIC);
+    expect(changed).toBe(true);
+    expect(content).toContain("sources={[");
+    // both sources, values unwrapped into an object literal
+    expect(content).toContain(
+      `{ src: image.mobile, width: 360, height: 120, media: "(max-width: 767px)" }`,
+    );
+    expect(content).toContain(`{ src: image.desktop, width: 1440, height: 200, media:`);
+    // required-for-typecheck props lifted from the <img> fallback
+    expect(content).toContain("src={image.desktop}");
+    expect(content).toContain("width={1440}");
+    expect(content).toContain("alt={image.alt ?? title}");
+    // self-closing, children gone
+    expect(content).not.toContain("<Source");
+    expect(content).not.toContain("</Picture>");
+    expect(notes.some((n) => n.includes("sources[]"))).toBe(true);
+  });
+
+  it("does not emit a duplicate className (Picture's own wins)", () => {
+    const { content } = transformPicture(CLASSIC);
+    expect((content.match(/className=/g) ?? []).length).toBe(1);
+    expect(content).toContain(`className="grid-pos"`);
+    expect(content).not.toContain(`"w-full"`);
+  });
+
+  it("lifts the <img> className when the Picture declares none", () => {
+    const input = `<Picture preload><Source src={a} width={10} media="m" /><img className="w" src={a} alt={t} /></Picture>`;
+    expect(transformPicture(input).content).toContain(`className="w"`);
+  });
+
+  it("leaves a prop-based Picture (no <Source> children) untouched", () => {
+    const already = `<Picture sources={x} src={y} width={10} />`;
+    const { content, changed } = transformPicture(already);
+    expect(changed).toBe(false);
+    expect(content).toBe(already);
+  });
+
+  it("handles a Picture with no <img> fallback (top props from last Source)", () => {
+    const input = `<Picture><Source src={a} width={800} media="all" /></Picture>`;
+    const { content } = transformPicture(input);
+    expect(content).toContain("sources={[{ src: a, width: 800, media: \"all\" }]}");
+    expect(content).toContain("src={a}");
+    expect(content).toContain("width={800}");
+  });
+});

package/scripts/migrate/transforms/picture.ts

@@ -0,0 +1,95 @@
+/**
+ * Picture API migration: children → props.
+ *
+ * Deco-fresh's `<Picture>` wrapped `<Source>` + an `<img>` fallback as CHILDREN.
+ * The new `@decocms/blocks` `Picture` is prop-based — `PictureProps` requires a
+ * `sources: PictureSourceProps[]` array plus `src`/`width` (from ImageProps).
+ * The children still render (`children ?? sources`) so a naive keep-children
+ * approach both fails the typecheck AND double-renders (children + the bottom
+ * `<Image>`). This transform converts the classic shape:
+ *
+ *   <Picture ATTRS>
+ *     <Source src={a} width={360} media="..." />
+ *     <Source src={b} width={1440} media="..." />
+ *     <img src={b} alt={x} className="..." />
+ *   </Picture>
+ *
+ * into the prop form:
+ *
+ *   <Picture ATTRS
+ *     sources={[{ src: a, width: 360, media: "..." }, { src: b, width: 1440, media: "..." }]}
+ *     src={b} width={1440} alt={x} className="..." />
+ *
+ * Only Pictures with `<Source>` children are touched; a Picture already using
+ * `sources={...}` props is left as-is.
+ */
+
+import type { TransformResult } from "../types";
+
+/** Parse a JSX tag's attribute string into name → raw value (`{expr}` / `"str"` / boolean). */
+function parseAttrs(attrStr: string): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  const re = /([A-Za-z_][\w-]*)(?:\s*=\s*(\{[^{}]*\}|"[^"]*"|'[^']*'))?/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(attrStr)) !== null) {
+    if (m[1]) attrs[m[1]] = m[2] ?? "";
+  }
+  return attrs;
+}
+
+/** Unwrap a raw JSX value for an object-literal field: `{image.x}` → `image.x`, `"s"` → `"s"`. */
+function unwrap(v: string): string {
+  return v.startsWith("{") && v.endsWith("}") ? v.slice(1, -1) : v;
+}
+
+export function transformPicture(content: string): TransformResult {
+  const notes: string[] = [];
+  let changed = false;
+
+  const result = content.replace(
+    /<Picture(\s[^>]*?)?>([\s\S]*?)<\/Picture>/g,
+    (whole, attrStr: string | undefined, inner: string) => {
+      const sourceMatches = [...inner.matchAll(/<Source\s+([^/>]*?)\/>/g)];
+      if (sourceMatches.length === 0) return whole; // not the children pattern
+
+      const sources = sourceMatches.map((mm) => parseAttrs(mm[1]));
+      const imgMatch = inner.match(/<img\s+([^/>]*?)\/>/);
+      const img = imgMatch ? parseAttrs(imgMatch[1]) : {};
+      const last = sources[sources.length - 1]!;
+
+      // sources={[{ src, width, height, media, sizes }, ...]}
+      const srcArr = sources
+        .map((s) => {
+          const fields = (["src", "width", "height", "media", "sizes"] as const)
+            .filter((k) => s[k] !== undefined)
+            .map((k) => `${k}: ${unwrap(s[k]!)}`);
+          return `{ ${fields.join(", ")} }`;
+        })
+        .join(", ");
+
+      // The required-for-typecheck props (src/width/height/alt) come from the
+      // <img> fallback, else the last <Source>.
+      const pick = (k: string): string | undefined => img[k] ?? last[k];
+      const top: string[] = [];
+      for (const k of ["src", "width", "height", "alt"] as const) {
+        const v = pick(k);
+        if (v !== undefined && v !== "") top.push(`${k}=${v}`);
+      }
+      // className/loading: only lift from the <img> if the <Picture> doesn't
+      // already declare it — otherwise we'd emit a duplicate attribute (React
+      // keeps the last, silently dropping the Picture's own classes).
+      const pictureAttrs = parseAttrs(attrStr ?? "");
+      for (const k of ["className", "loading"] as const) {
+        if (img[k] !== undefined && img[k] !== "" && pictureAttrs[k] === undefined) {
+          top.push(`${k}=${img[k]}`);
+        }
+      }
+
+      changed = true;
+      notes.push(`Picture: ${sources.length} <Source> children → sources[] props`);
+      return `<Picture${attrStr ?? ""} sources={[${srcArr}]} ${top.join(" ")} />`;
+    },
+  );
+
+  return { content: result, changed, notes };
+}

package/scripts/migrate/transforms/timer-types.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { transformTimerTypes } from "./timer-types";
+
+describe("transformTimerTypes", () => {
+  it("retypes a `number` handle assigned setTimeout", () => {
+    const r = transformTimerTypes(`let hideTimeout: number;\nhideTimeout = setTimeout(() => {}, 100);`);
+    expect(r.changed).toBe(true);
+    expect(r.content).toContain("let hideTimeout: ReturnType<typeof setTimeout>");
+  });
+
+  it("retypes a setInterval handle", () => {
+    const r = transformTimerTypes(`let poll: number;\npoll = setInterval(fn, 1000);`);
+    expect(r.content).toContain("let poll: ReturnType<typeof setInterval>");
+  });
+
+  it("leaves an unrelated numeric variable alone", () => {
+    const r = transformTimerTypes(`let count: number;\ncount = 5;\nlet t: number;\nt = setTimeout(f, 1);`);
+    expect(r.content).toContain("let count: number");
+    expect(r.content).toContain("let t: ReturnType<typeof setTimeout>");
+  });
+
+  it("handles the window.setTimeout form", () => {
+    const r = transformTimerTypes(`let x: number;\nx = window.setTimeout(f, 1);`);
+    expect(r.content).toContain("let x: ReturnType<typeof setTimeout>");
+  });
+
+  it("is a no-op when the handle is never assigned a timer", () => {
+    expect(transformTimerTypes(`let y: number;`).changed).toBe(false);
+  });
+});

package/scripts/migrate/transforms/timer-types.ts

@@ -0,0 +1,48 @@
+/**
+ * `let x: number = setTimeout(...)` typing fix.
+ *
+ * Deco-fresh (Deno DOM types) had `setTimeout`/`setInterval` return `number`, so
+ * sites typed their handles `let hideTimeout: number`. Under Node/TanStack types
+ * they return `NodeJS.Timeout`, so the assignment fails ("Type 'Timeout' is not
+ * assignable to type 'number'"). Rather than `window.setTimeout` (unsafe in
+ * server `.ts`), retype the DECLARATION to `ReturnType<typeof setTimeout>` — the
+ * portable handle type, correct in both browser and worker/node.
+ *
+ * Only a `let|const|var NAME: number` declaration whose NAME is assigned a
+ * `setTimeout(` / `setInterval(` elsewhere in the file is retyped; a plain
+ * numeric variable is never touched.
+ */
+
+import type { TransformResult } from "../types";
+
+export function transformTimerTypes(content: string): TransformResult {
+  const notes: string[] = [];
+  let changed = false;
+  let result = content;
+
+  for (const kind of ["setTimeout", "setInterval"] as const) {
+    // Names assigned this timer: `NAME = setTimeout(` (and `= window.setTimeout(`).
+    const assigned = new Set<string>();
+    for (const m of content.matchAll(
+      new RegExp(`\\b([A-Za-z_$][\\w$]*)\\s*=\\s*(?:window\\.)?${kind}\\s*\\(`, "g"),
+    )) {
+      assigned.add(m[1]!);
+    }
+
+    for (const name of assigned) {
+      // Retype only the declaration's `: number` (allowing `| undefined`/`| null`).
+      const declRe = new RegExp(
+        `\\b(let|const|var)(\\s+${name}\\s*:\\s*)number\\b`,
+        "g",
+      );
+      const next = result.replace(declRe, `$1$2ReturnType<typeof ${kind}>`);
+      if (next !== result) {
+        result = next;
+        changed = true;
+        notes.push(`Timer type: ${name}: number → ReturnType<typeof ${kind}>`);
+      }
+    }
+  }
+
+  return { content: result, changed, notes };
+}

package/scripts/migrate/transforms/use-script-handlers.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { transformUseScriptHandlers } from "./use-script-handlers";
+
+describe("transformUseScriptHandlers", () => {
+  it("rewrites an identifier callback + args to an arrow", () => {
+    const r = transformUseScriptHandlers(`<button onClick={useScript(onClick, -1)} />`);
+    expect(r.changed).toBe(true);
+    expect(r.content).toContain(`onClick={() => onClick(-1)}`);
+  });
+
+  it("handles a no-arg identifier callback", () => {
+    const r = transformUseScriptHandlers(`<button onClick={useScript(handleClick)} />`);
+    expect(r.content).toContain(`onClick={() => handleClick()}`);
+  });
+
+  it("handles multiple args and any onEvent name", () => {
+    const r = transformUseScriptHandlers(`<a onMouseEnter={useScript(prefetch, id, "x")} />`);
+    expect(r.content).toContain(`onMouseEnter={() => prefetch(id, "x")}`);
+  });
+
+  it("leaves an INLINE arrow untouched (per-site closure → manual)", () => {
+    const src = `<button onClick={useScript(({ x }) => { doThing(x); })} />`;
+    const r = transformUseScriptHandlers(src);
+    expect(r.changed).toBe(false);
+    expect(r.content).toBe(src);
+  });
+
+  it("leaves an arg with nested parens untouched (safety)", () => {
+    const src = `<button onClick={useScript(fn, foo(x))} />`;
+    expect(transformUseScriptHandlers(src).changed).toBe(false);
+  });
+
+  it("does not touch a non-handler useScript call", () => {
+    const src = `const s = useScript(fn, 1);`;
+    expect(transformUseScriptHandlers(src).changed).toBe(false);
+  });
+});

package/scripts/migrate/transforms/use-script-handlers.ts

@@ -0,0 +1,36 @@
+/**
+ * `useScript` in React event handlers → a plain arrow.
+ *
+ * Deco-fresh's `useScript(fn, ...args)` serialized `fn` to a client-side script
+ * STRING (hydration-free interactivity), so `onClick={useScript(onClick, -1)}`
+ * passed a string to `onClick`. React wants a FUNCTION and the stricter TanStack
+ * typecheck fails ("Type 'string' is not assignable to MouseEventHandler").
+ * Hydrated React just calls the function directly:
+ *
+ *   onClick={useScript(onClick, -1)}   →   onClick={() => onClick(-1)}
+ *
+ * Only the SIMPLE, unambiguous shape is rewritten — an identifier callback plus
+ * literal args (no nested parens/braces). An INLINE arrow
+ * (`useScript(({x}) => {…})`) depends on how the closure was serialized and is a
+ * per-site call, so it's left for the `htmx-residue` audit + manual rewrite.
+ */
+
+import type { TransformResult } from "../types";
+
+export function transformUseScriptHandlers(content: string): TransformResult {
+  const notes: string[] = [];
+  let changed = false;
+
+  // onEvent={useScript(IDENT[, simple args])} — IDENT is a bare identifier /
+  // member expr; args contain no nested parens or braces (keeps it safe).
+  const re = /\b(on[A-Z]\w+)=\{useScript\(\s*([A-Za-z_$][\w$.]*)\s*((?:,[^{}()]*)?)\)\}/g;
+
+  const result = content.replace(re, (_whole, event: string, fn: string, argsRaw: string) => {
+    const args = argsRaw.replace(/^\s*,\s*/, "").trim();
+    changed = true;
+    notes.push(`useScript handler: ${event}={useScript(${fn}…)} → () => ${fn}(…)`);
+    return `${event}={() => ${fn}(${args})}`;
+  });
+
+  return { content: result, changed, notes };
+}

package/scripts/migrate/types.ts

@@ -132,6 +132,12 @@ export interface LoaderInfo {
 
 export interface MigrationContext {
   sourceDir: string;
+  /**
+   * Source directory layout: `"classic"` (sections/ at root) or `"modern"`
+   * (src/sections/). Drives whether the analyzer also scans `src/`. Set in
+   * migrate.ts after detection; defaults to `"classic"`.
+   */
+  layout: import("./source-layout").SourceLayout;
   siteName: string;
   platform: Platform;
   /** VTEX account name (e.g. "casaevideonewio") — extracted from source code */
@@ -219,6 +225,7 @@ export function createContext(
 ): MigrationContext {
   return {
     sourceDir,
+    layout: "classic",
     siteName: "",
     platform: "custom",
     vtexAccount: null,

package/scripts/migrate.ts

@@ -157,18 +157,21 @@ async function main() {
     config: siteConfig,
   });
 
-  // Phase 0: Source-layout detection (early-abort for unsupported layouts).
-  // The analyzer assumes a classic root layout (sections/, islands/, ...);
-  // running it on a modern src/ layout silently yields a near-empty
-  // migration. Detect-and-abort here so the user gets an actionable error
-  // before we touch any files.
+  // Phase 0: Source-layout detection. `classic` (root sections/) and `modern`
+  // (src/sections/) are both supported — the analyzer scans src/ natively for
+  // modern layouts. Only genuinely ambiguous (`mixed`) or unrecognizable
+  // (`empty`) layouts abort with an actionable error before we touch files.
   const layout = detectSourceLayout(sourceDir);
-  if (layout !== "classic") {
+  ctx.layout = layout;
+  if (layout === "mixed" || layout === "empty") {
     console.error(red(`Error: ${layout} source layout`));
     console.error("");
     console.error(explainNonClassicLayout(layout, sourceDir));
     process.exit(2);
   }
+  if (layout === "modern") {
+    console.log(`  Source layout: modern (src/) — scanning src/ natively`);
+  }
 
   try {
     // Phase 1: Analyze source