@decocms/blocks-cli 8.0.0 → 8.1.0-next.0

package/scripts/migrate/transforms/ctx-compat.test.ts

@@ -57,6 +57,43 @@ describe("transformCtxCompat", () => {
     expect(r.content).toContain("ctx?: AppContext");
   });
 
+  // The scanner walks raw characters, so without a literal/comment guard it
+  // rewrote `ctx.` inside strings too — patching the call site correctly while
+  // silently corrupting the message next to it.
+  it("does not rewrite ctx inside string literals", () => {
+    const r = transformCtxCompat(withLoader("  console.log('ctx.device:', ctx.device);"));
+    expect(r.content).toContain("'ctx.device:'");
+    expect(r.content).toContain("console.log('ctx.device:', ctx?.device)");
+  });
+
+  it("does not rewrite ctx inside double-quoted strings or escaped quotes", () => {
+    const r = transformCtxCompat(
+      withLoader('  const s = "he said \\"ctx.device\\""; return ctx.device;'),
+    );
+    expect(r.content).toContain('"he said \\"ctx.device\\""');
+    expect(r.content).toContain("return ctx?.device");
+  });
+
+  it("does not rewrite ctx inside comments", () => {
+    const r = transformCtxCompat(
+      withLoader("  // don't touch ctx.device here\n  /* nor ctx.invoke */\n  return ctx.device;"),
+    );
+    expect(r.content).toContain("// don't touch ctx.device here");
+    expect(r.content).toContain("/* nor ctx.invoke */");
+    expect(r.content).toContain("return ctx?.device");
+  });
+
+  it("does not rewrite template text but DOES rewrite ${} interpolation", () => {
+    const r = transformCtxCompat(withLoader("  const u = `ctx.device is ${ctx.vtex.account}`;"));
+    // literal text stays, the interpolated expression is real code
+    expect(r.content).toContain("`ctx.device is ${ctx?.vtex?.account}`");
+  });
+
+  it("handles nested template literals", () => {
+    const r = transformCtxCompat(withLoader("  const u = `a${`b${ctx.device}`}c`;"));
+    expect(r.content).toContain("`a${`b${ctx?.device}`}c`");
+  });
+
   it("does not match identifiers that merely contain ctx", () => {
     const src = withLoader("  const c = canvasCtx.foo;\n  const d = a.ctx.bar;");
     const r = transformCtxCompat(src);

package/scripts/migrate/transforms/ctx-compat.ts

@@ -11,7 +11,7 @@ import type { TransformResult } from "../types";
  * *non-optional* deep read like `ctx.salesforce.cartExtension[0]` still throws
  * — and `withSectionLoader`'s try/catch would swallow it, dropping the
  * section's props (blank render). The hand-fixed reference migration
- * (`granadobr-tanstack`) solves this by optional-chaining every `ctx` read.
+ * (a production storefront) solves this by optional-chaining every `ctx` read.
  *
  * This codemod reproduces that: every `ctx.` member-access chain becomes an
  * optional chain (`ctx?.a?.b?.[0]`). Optional chaining short-circuits to
@@ -112,7 +112,99 @@ export function transformCtxCompat(content: string): TransformResult {
   let i = 0;
   let count = 0;
 
+  // Contexts we are inside of, innermost last. Without this the scanner walks
+  // raw characters and happily rewrites `ctx.` inside string literals and
+  // comments: `console.log('ctx.device:', ctx.device)` became
+  // `console.log('ctx?.device:', ctx?.device)` — the call site correctly
+  // patched, the message silently corrupted.
+  //
+  // A template literal pushes "template" (its text is data), and a `${` inside
+  // one pushes "expr" (real code, where rewriting must resume) — so
+  // `` `${ctx.device}` `` is still rewritten while `` `ctx.device` `` is not.
+  //
+  // Regex literals are deliberately NOT tracked: telling `/re/` from division
+  // needs real parsing, and guessing wrong would consume live code. A `ctx.`
+  // inside a regex in a loader is vanishingly rare next to that risk.
+  const stack: ("template" | "expr")[] = [];
+
   while (i < content.length) {
+    const inTemplateText = stack[stack.length - 1] === "template";
+
+    if (inTemplateText) {
+      if (content[i] === "\\") {
+        out += content.slice(i, i + 2);
+        i += 2;
+        continue;
+      }
+      if (content[i] === "`") {
+        stack.pop();
+        out += content[i];
+        i += 1;
+        continue;
+      }
+      if (content.startsWith("${", i)) {
+        stack.push("expr");
+        out += "${";
+        i += 2;
+        continue;
+      }
+      out += content[i];
+      i += 1;
+      continue;
+    }
+
+    // Line comment — copy to end of line.
+    if (content.startsWith("//", i)) {
+      const nl = content.indexOf("\n", i);
+      const end = nl === -1 ? content.length : nl;
+      out += content.slice(i, end);
+      i = end;
+      continue;
+    }
+
+    // Block comment — copy to the closing delimiter.
+    if (content.startsWith("/*", i)) {
+      const close = content.indexOf("*/", i + 2);
+      const end = close === -1 ? content.length : close + 2;
+      out += content.slice(i, end);
+      i = end;
+      continue;
+    }
+
+    // Single/double quoted string — copy to the unescaped closing quote.
+    if (content[i] === "'" || content[i] === '"') {
+      const quote = content[i];
+      let j = i + 1;
+      while (j < content.length) {
+        if (content[j] === "\\") {
+          j += 2;
+          continue;
+        }
+        if (content[j] === quote || content[j] === "\n") {
+          j += 1;
+          break;
+        }
+        j += 1;
+      }
+      out += content.slice(i, j);
+      i = j;
+      continue;
+    }
+
+    if (content[i] === "`") {
+      stack.push("template");
+      out += content[i];
+      i += 1;
+      continue;
+    }
+
+    if (content[i] === "}" && stack[stack.length - 1] === "expr") {
+      stack.pop();
+      out += content[i];
+      i += 1;
+      continue;
+    }
+
     const isCtxToken =
       content.startsWith("ctx", i) &&
       !isIdentChar(content[i - 1]) &&

package/scripts/migrate/transforms/htmx-on-events.test.ts

@@ -224,7 +224,7 @@ describe("transformHtmxOnEvents — idempotency + edge cases", () => {
   });
 });
 
-describe("transformHtmxOnEvents — als-shaped fixtures", () => {
+describe("transformHtmxOnEvents — htmx-shaped fixtures", () => {
   it("AddToBagButton: hx-on-click + Fresh useScript → onClick + TODO", () => {
     const src = `import { useScript } from "site/sdk/useScript.ts";
 

package/scripts/migrate/transforms/htmx-on-events.ts

@@ -61,8 +61,8 @@ const STANDARD_EVENT_MAP: Record<string, string> = {
  * handler bodies reference Fresh-only globals (`useScript`,
  * `globalThis.window.STOREFRONT`, `STOREFRONT.*`). The comment is the
  * only file-level annotation the codemod emits — per-occurrence
- * comments would balloon the diff for a 88-rename file like
- * als-storefront's hot paths. It is detected by an idempotency check
+ * comments would balloon the diff for an 88-rename file like a
+ * production storefront's hot paths. It is detected by an idempotency check
  * so re-running the codemod does not double-inject.
  */
 const TODO_MARKER = "// MIGRATION TODO (codemod: htmx-on-event-rename):";

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/tailwind-renames.test.ts

@@ -35,3 +35,32 @@ describe("renameToken", () => {
     expect(renameToken("md:bg-red-500")).toBe("md:bg-red-500");
   });
 });
+
+import { detectDaisyUiV5StructuralIssues } from "./tailwind-renames";
+
+describe("detectDaisyUiV5StructuralIssues", () => {
+  it("detects menu-compact removal", () => {
+    const findings = detectDaisyUiV5StructuralIssues(`<ul className="menu menu-compact">`);
+    expect(findings.some((f) => f.message.includes("menu-compact"))).toBe(true);
+  });
+
+  it("detects tab-bordered removal", () => {
+    const findings = detectDaisyUiV5StructuralIssues(`<a className="tab tab-bordered">`);
+    expect(findings.some((f) => f.message.includes("tab-bordered"))).toBe(true);
+  });
+
+  it("detects bare alert in className without a color modifier", () => {
+    const findings = detectDaisyUiV5StructuralIssues(`<div className="alert">`);
+    expect(findings.some((f) => f.message.includes("alert"))).toBe(true);
+  });
+
+  it("does not flag alert when a color modifier is present", () => {
+    const findings = detectDaisyUiV5StructuralIssues(`<div className="alert alert-info">`);
+    expect(findings.some((f) => f.message.includes("alert default styling"))).toBe(false);
+  });
+
+  it("does not flag alert() JS function calls as a DaisyUI alert", () => {
+    const findings = detectDaisyUiV5StructuralIssues(`window.alert("something went wrong");`);
+    expect(findings.some((f) => f.message.includes("alert default styling"))).toBe(false);
+  });
+});

package/scripts/migrate/transforms/tailwind-renames.ts

@@ -79,6 +79,8 @@ export const CLASS_RENAMES: Record<string, string> = {
 export const DAISYUI_RENAMES: Record<string, string> = {
   "badge-ghost": "badge-soft",
   "card-compact": "card-sm",
+  "card-normal": "card-md",
+  "tabs-boxed": "tabs-box",
 };
 
 /**
@@ -183,6 +185,38 @@ export function detectDaisyUiV5StructuralIssues(content: string): GotchaFinding[
     });
   }
 
+  if (/\bmenu-compact\b/.test(content)) {
+    findings.push({
+      gotcha: 37,
+      message:
+        "DaisyUI v4 `menu-compact` was removed in v5 with no drop-in class — use `menu-sm` for a smaller menu or remove the modifier.",
+    });
+  }
+
+  if (/\btab-bordered\b/.test(content)) {
+    findings.push({
+      gotcha: 37,
+      message:
+        "DaisyUI v4 `tab-bordered` was removed in v5 — use `tabs-bordered` on the `tabs` wrapper instead of a modifier on each `tab` element.",
+    });
+  }
+
+  // Detect bare `alert` without a color modifier — DaisyUI v5 changed the
+  // default alert background; alerts without alert-info/success/warning/error
+  // may appear with no background color.
+  // Scoped to className= / class= attribute values to avoid matching the JS
+  // global `alert()` function, variable names, or comments in the same file.
+  if (
+    /className=["'][^"']*\balert\b[^"']*["']/.test(content) &&
+    !/\balert-(?:info|success|warning|error)\b/.test(content)
+  ) {
+    findings.push({
+      gotcha: 37,
+      message:
+        "DaisyUI v5 changed `alert` default styling — a bare `alert` without a color modifier (alert-info/success/warning/error) may render with no background. Add an explicit color modifier or use `alert-soft` for a neutral variant.",
+    });
+  }
+
   return findings;
 }
 

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,9 +132,15 @@ 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 */
+  /** VTEX account name (e.g. "acme") — extracted from source code */
   vtexAccount: string | null;
   gtmId: string | null;
 
@@ -156,6 +162,8 @@ export interface MigrationContext {
   themeColors: Record<string, string>;
   /** Font family from CMS config */
   fontFamily: string | null;
+  /** Google Fonts URLs extracted from routes/_app.tsx or CSS @import */
+  googleFonts: { preconnects: string[]; stylesheets: string[] };
 
   /**
    * Statically-extracted content of the source site's `tailwind.config.ts`
@@ -217,6 +225,7 @@ export function createContext(
 ): MigrationContext {
   return {
     sourceDir,
+    layout: "classic",
     siteName: "",
     platform: "custom",
     vtexAccount: null,
@@ -226,10 +235,13 @@ export function createContext(
     discoveredNpmDeps: {},
     themeColors: {},
     fontFamily: null,
+    googleFonts: { preconnects: [], stylesheets: [] },
     tailwindConfig: {
       colors: {},
       fontFamily: {},
       screens: {},
+      animations: {},
+      keyframes: {},
       safelist: [],
       safelistPatterns: [],
       plugins: [],