@decocms/start 2.21.0 → 2.23.0

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

@@ -216,50 +216,20 @@ declare module "@tanstack/react-router" {
 
 function generateRuntime(): string {
   return `/**
- * Runtime invoke proxy.
+ * Runtime invoke proxy — re-exports the framework canonical from @decocms/start/sdk.
  *
- * Turns nested property access into a typed RPC call to /deco/invoke.
- * Converts dot-notation paths to slash-separated keys:
- *   invoke.vtex.loaders.productList(props)
- *   → POST /deco/invoke/vtex/loaders/productList
+ * The implementation (typed RPC over /deco/invoke, dotted-path proxy, .ts
+ * suffix fallback) lives in @decocms/start/sdk/invoke. This file exists so
+ * existing site code can keep \`import { invoke } from "~/runtime"\` and
+ * \`Runtime.invoke\` shapes without churn.
  *
- * The .ts suffix variant is also tried if the primary key isn't found
- * (registered loaders may have ".ts" extensions in their keys).
+ * Don't reimplement here — extend @decocms/start/sdk/invoke instead.
  */
-function createNestedInvokeProxy(path: string[] = []): any {
-  return new Proxy(
-    Object.assign(async (props: any) => {
-      const key = path.join("/");
-      for (const k of [key, \`\${key}.ts\`]) {
-        const response = await fetch(\`/deco/invoke/\${k}\`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(props ?? {}),
-        });
-        if (response.status === 404) continue;
-        if (!response.ok) {
-          throw new Error(\`invoke(\${k}) failed: \${response.status}\`);
-        }
-        return response.json();
-      }
-      throw new Error(\`invoke(\${key}) failed: handler not found\`);
-    }, {}),
-    {
-      get(_target: any, prop: string) {
-        if (prop === "then" || prop === "catch" || prop === "finally") {
-          return undefined;
-        }
-        return createNestedInvokeProxy([...path, prop]);
-      },
-    },
-  );
-}
+import { invoke } from "@decocms/start/sdk";
 
-export const invoke = createNestedInvokeProxy() as any;
+export { invoke };
 
-export const Runtime = {
-  invoke,
-};
+export const Runtime = { invoke };
 `;
 }
 
@@ -299,11 +269,8 @@ export const invoke = {} as const;
  * auto-generated in invoke.gen.ts. Run \`npm run generate:invoke\` to update.
  */
 import { createServerFn } from "@tanstack/react-start";
-import {
-  getRequestHeader,
-  getResponseHeaders,
-  setResponseHeader,
-} from "@tanstack/react-start/server";
+import { getRequestHeader } from "@tanstack/react-start/server";
+import { forwardResponseCookies } from "@decocms/start/sdk/cookiePassthrough";
 import { vtexActions } from "./invoke.gen";
 ${hasVtexAuthLoader ? `import vtexAuthLoader from "../loaders/vtex-auth-loader";\n` : ""}import {
   extractVtexCookiesFromHeader,
@@ -314,15 +281,6 @@ ${hasVtexAuthLoader ? `import vtexAuthLoader from "../loaders/vtex-auth-loader";
 
 export type { OrderForm } from "./invoke.gen";
 
-function mergeSetCookies(newCookies: string[]): void {
-  if (newCookies.length === 0) return;
-  const existing: string[] =
-    typeof getResponseHeaders().getSetCookie === "function"
-      ? getResponseHeaders().getSetCookie()
-      : [];
-  setResponseHeader("set-cookie", [...existing, ...newCookies]);
-}
-
 function getVtexCookies(): string {
   return extractVtexCookiesFromHeader(getRequestHeader("cookie") ?? "");
 }
@@ -336,7 +294,7 @@ ${hasVtexAuthLoader ? `const _vtexAuth = createServerFn({ method: "POST" })
     } as any);
     if (result instanceof Response) {
       const setCookies = result.headers.getSetCookie?.() ?? [];
-      mergeSetCookies(stripCookieDomain(setCookies));
+      forwardResponseCookies(stripCookieDomain(setCookies));
       return result.json();
     }
     return result;
@@ -344,7 +302,7 @@ ${hasVtexAuthLoader ? `const _vtexAuth = createServerFn({ method: "POST" })
 ` : ""}const _logout = createServerFn({ method: "POST" }).handler(
   async (): Promise<{ success: boolean }> => {
     const { setCookies } = await performVtexLogout(getVtexCookies());
-    mergeSetCookies(setCookies);
+    forwardResponseCookies(setCookies);
     return { success: true };
   },
 );

package/scripts/migrate/templates/vite-config.ts

@@ -53,41 +53,6 @@ export default defineConfig({
     }),
     tailwindcss(),
     decoVitePlugin(),
-    {
-      name: "site-manual-chunks",
-      config(_cfg, { command }) {
-        if (command !== "build") return;
-        return {
-          build: {
-            rollupOptions: {
-              output: {
-                manualChunks(id: string) {
-                  if (id.includes("node_modules/react-dom") || id.includes("node_modules/react/"))
-                    return "vendor-react";
-                  if (id.includes("@tanstack/react-router") || id.includes("@tanstack/start"))
-                    return "vendor-router";
-                  if (id.includes("@tanstack/react-query")) return "vendor-query";
-                },
-              },
-            },
-          },
-        };
-      },
-    },
-    {
-      name: "deco-stub-meta-gen",
-      enforce: "pre" as const,
-      resolveId(id, importer, options) {
-        if (!options?.ssr && importer && id.includes("meta.gen")) {
-          return "\\0stub:meta-gen";
-        }
-      },
-      load(id) {
-        if (id === "\\0stub:meta-gen") {
-          return "export default {};";
-        }
-      },
-    },
   ],
   build: {
     sourcemap: "hidden",

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

@@ -0,0 +1,305 @@
+import { describe, expect, it } from "vitest";
+import {
+  _internals,
+  transformHtmxOnEvents,
+} from "./htmx-on-events";
+
+const { STANDARD_EVENT_MAP, TODO_MARKER } = _internals;
+
+describe("transformHtmxOnEvents — basic renames", () => {
+  it("renames hx-on:click → onClick (colon variant)", () => {
+    const src = `<button hx-on:click={() => alert("hi")}>click</button>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.changed).toBe(true);
+    expect(r.content).toBe(
+      `<button onClick={() => alert("hi")}>click</button>`,
+    );
+    expect(r.notes[0]).toContain("Renamed 1 hx-on:* attribute(s)");
+    expect(r.notes[0]).toContain("onClick=1");
+  });
+
+  it("renames hx-on-click → onClick (dash variant)", () => {
+    const src = `<button hx-on-click={fn}>click</button>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.changed).toBe(true);
+    expect(r.content).toBe(`<button onClick={fn}>click</button>`);
+  });
+
+  it("preserves whitespace around `=`", () => {
+    const src = `<button hx-on:click = {fn}>x</button>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.content).toBe(`<button onClick = {fn}>x</button>`);
+  });
+
+  it("renames every standard event in the map", () => {
+    for (const [htmxEvent, reactName] of Object.entries(STANDARD_EVENT_MAP)) {
+      const src = `<x hx-on:${htmxEvent}={fn}/>`;
+      const r = transformHtmxOnEvents(src);
+      expect(r.content, `event=${htmxEvent}`).toBe(`<x ${reactName}={fn}/>`);
+    }
+  });
+
+  it("renames every standard event in the map (dash variant)", () => {
+    for (const [htmxEvent, reactName] of Object.entries(STANDARD_EVENT_MAP)) {
+      const src = `<x hx-on-${htmxEvent}={fn}/>`;
+      const r = transformHtmxOnEvents(src);
+      expect(r.content, `event=${htmxEvent}`).toBe(`<x ${reactName}={fn}/>`);
+    }
+  });
+
+  it("handles multiple events on the same element", () => {
+    const src = `<input hx-on:change={a} hx-on:keyup={b} hx-on:focus={c}/>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.content).toBe(
+      `<input onChange={a} onKeyUp={b} onFocus={c}/>`,
+    );
+    expect(r.notes[0]).toContain("Renamed 3 hx-on:* attribute(s)");
+  });
+
+  it("handles multi-line attribute values", () => {
+    const src = `<button
+  hx-on:click={() => {
+    setLoading(true);
+    doStuff();
+  }}>
+  Submit
+</button>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.content).toContain("onClick={() => {");
+    expect(r.content).toContain("setLoading(true);");
+    expect(r.content).not.toContain("hx-on");
+  });
+
+  it("handles string-valued events (rare but legal htmx)", () => {
+    const src = `<button hx-on:click="alert('hi')">x</button>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.content).toBe(`<button onClick="alert('hi')">x</button>`);
+  });
+});
+
+describe("transformHtmxOnEvents — what stays untouched", () => {
+  it("leaves htmx lifecycle events alone (htmx-config-request, htmx-before-request, ...)", () => {
+    const src = `<form hx-post="/x"
+      hx-on:htmx-before-request={a}
+      hx-on:htmx-config-request={b}
+      hx-on-htmx-after-swap={c}
+    />`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.changed).toBe(false);
+    expect(r.content).toBe(src);
+  });
+
+  it("renames standard events but preserves htmx lifecycle on the same element", () => {
+    const src = `<form hx-post="/x" hx-on:submit={validate} hx-on:htmx-before-request={addCsrf}>...</form>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.changed).toBe(true);
+    expect(r.content).toBe(
+      `<form hx-post="/x" onSubmit={validate} hx-on:htmx-before-request={addCsrf}>...</form>`,
+    );
+  });
+
+  it("leaves unknown/custom events alone (no React synthetic equivalent)", () => {
+    const src = `<x hx-on:my-custom-event={fn} hx-on-other-thing={fn2}/>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.changed).toBe(false);
+    expect(r.content).toBe(src);
+  });
+
+  it("leaves non-event hx-* attributes alone (hx-post, hx-target, hx-swap, ...)", () => {
+    const src = `<form hx-post="/x" hx-target="#r" hx-swap="innerHTML" hx-trigger="submit"/>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.changed).toBe(false);
+    expect(r.content).toBe(src);
+  });
+
+  it("leaves already-React onClick alone", () => {
+    const src = `<button onClick={fn}>x</button>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.changed).toBe(false);
+    expect(r.content).toBe(src);
+  });
+
+  it("does not match attribute names that merely contain 'hx-on' as a substring", () => {
+    const src = `<x data-hx-onfoo={fn} aria-hx-on="x"/>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.changed).toBe(false);
+  });
+
+  it("returns unchanged on files with no hx-on at all (fast path)", () => {
+    const src = `<button onClick={fn}>x</button>\n<form hx-post="/x"/>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.changed).toBe(false);
+    expect(r.content).toBe(src);
+    expect(r.notes).toEqual([]);
+  });
+});
+
+describe("transformHtmxOnEvents — Fresh-isms TODO injection", () => {
+  it("injects a top-of-file MIGRATION TODO when handler references useScript()", () => {
+    const src = `import { useScript } from "site/sdk/useScript.ts";
+
+export default function X() {
+  return <button hx-on:click={useScript(handler)}>x</button>;
+}
+`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.changed).toBe(true);
+    expect(r.content.startsWith(TODO_MARKER)).toBe(true);
+    expect(r.content).toContain("onClick={useScript(handler)}");
+    expect(r.notes.some((n) => n.includes("Injected MIGRATION TODO"))).toBe(true);
+  });
+
+  it("injects a top-of-file MIGRATION TODO when handler references globalThis.window.STOREFRONT", () => {
+    const src = `<button hx-on:click={() => { globalThis.window.STOREFRONT.CART.addToCart({}); }}>buy</button>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.content.startsWith(TODO_MARKER)).toBe(true);
+  });
+
+  it("injects a top-of-file MIGRATION TODO when handler references STOREFRONT.* (shorthand)", () => {
+    const src = `import { STOREFRONT } from "site/sdk";\n<button hx-on:click={() => STOREFRONT.CART.addToCart()}>x</button>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.content.startsWith(TODO_MARKER)).toBe(true);
+  });
+
+  it("does NOT inject a TODO when no Fresh-isms are detected", () => {
+    const src = `<button hx-on:click={() => setOpen(true)}>x</button>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.changed).toBe(true);
+    expect(r.content.startsWith(TODO_MARKER)).toBe(false);
+    expect(r.content).toBe(`<button onClick={() => setOpen(true)}>x</button>`);
+    expect(r.notes.some((n) => n.includes("Injected MIGRATION TODO"))).toBe(false);
+  });
+
+  it("preserves a leading shebang and inserts the TODO after it", () => {
+    const src = `#!/usr/bin/env node\n<button hx-on:click={useScript(fn)}>x</button>\n`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.content.startsWith("#!/usr/bin/env node\n")).toBe(true);
+    expect(r.content.split("\n")[1]).toBe(TODO_MARKER);
+  });
+
+  it("does not inject the TODO twice when the codemod is rerun (idempotent)", () => {
+    const src = `<button hx-on:click={useScript(fn)}>x</button>`;
+    const first = transformHtmxOnEvents(src);
+    const second = transformHtmxOnEvents(first.content);
+    expect(second.changed).toBe(false);
+    const occurrences = first.content.split(TODO_MARKER).length - 1;
+    expect(occurrences).toBe(1);
+  });
+});
+
+describe("transformHtmxOnEvents — idempotency + edge cases", () => {
+  it("is idempotent on a clean rewritten file (rerunning is a no-op)", () => {
+    const src = `<button onClick={fn}>x</button>`;
+    const first = transformHtmxOnEvents(src);
+    const second = transformHtmxOnEvents(first.content);
+    expect(first.changed).toBe(false);
+    expect(second.changed).toBe(false);
+    expect(second.content).toBe(src);
+  });
+
+  it("is idempotent on a file that just got rewritten (rerun produces same output)", () => {
+    const src = `<button hx-on:click={fn}>x</button>`;
+    const first = transformHtmxOnEvents(src);
+    const second = transformHtmxOnEvents(first.content);
+    expect(second.changed).toBe(false);
+    expect(second.content).toBe(first.content);
+  });
+
+  it("handles JSX components (capitalized tag names) just like lowercase intrinsics", () => {
+    const src = `<Accordion.Trigger hx-on-click={toggle}>open</Accordion.Trigger>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.content).toBe(
+      `<Accordion.Trigger onClick={toggle}>open</Accordion.Trigger>`,
+    );
+  });
+
+  it("renames within a long file containing many tags", () => {
+    const src = Array.from({ length: 20 })
+      .map((_, i) => `<button key={${i}} hx-on:click={() => setCount(${i})}>${i}</button>`)
+      .join("\n");
+    const r = transformHtmxOnEvents(src);
+    expect(r.notes[0]).toContain("Renamed 20 hx-on:* attribute(s)");
+    expect(r.content.split("onClick=").length - 1).toBe(20);
+    expect(r.content.includes("hx-on")).toBe(false);
+  });
+});
+
+describe("transformHtmxOnEvents — als-shaped fixtures", () => {
+  it("AddToBagButton: hx-on-click + Fresh useScript → onClick + TODO", () => {
+    const src = `import { useScript } from "site/sdk/useScript.ts";
+
+interface Props { productId: string; }
+
+export default function AddToBagButton({ productId }: Props) {
+  const handler = (id: string) => {
+    globalThis.window.STOREFRONT.CART.addToCart({ id });
+  };
+  return (
+    <button
+      class="btn"
+      hx-on-click={useScript(handler, productId)}
+    >
+      Add to bag
+    </button>
+  );
+}
+`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.changed).toBe(true);
+    expect(r.content).toContain("onClick={useScript(handler, productId)}");
+    expect(r.content.startsWith(TODO_MARKER)).toBe(true);
+    const codeBody = r.content.split("§ Pattern 1 (event-handler).\n")[1];
+    expect(codeBody).not.toMatch(/\bhx-on\b/);
+  });
+
+  it("SearchInput: keeps hx-post/hx-target/etc, renames hx-on:change", () => {
+    const src = `<input
+  type="search"
+  hx-post={searchUrl}
+  hx-target="#suggestions"
+  hx-swap="innerHTML"
+  hx-trigger="keyup changed delay:300ms"
+  hx-sync="closest form:abort"
+  hx-on:change={(e) => { e.preventDefault(); }}
+/>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.changed).toBe(true);
+    expect(r.content).toContain(`onChange={(e) => { e.preventDefault(); }}`);
+    expect(r.content).toContain("hx-post={searchUrl}");
+    expect(r.content).toContain('hx-target="#suggestions"');
+    expect(r.content).toContain('hx-swap="innerHTML"');
+    expect(r.content).toContain('hx-sync="closest form:abort"');
+  });
+
+  it("RecoveryPassword: form with mixed standard + htmx lifecycle hooks", () => {
+    const src = `<form
+  hx-post={url}
+  hx-target="#form"
+  hx-swap="outerHTML"
+  hx-trigger="submit"
+  hx-disabled-elt="find button"
+  hx-indicator="#loader"
+  hx-select="#form"
+  hx-on:submit={(e) => { /* validate */ }}
+  hx-on-htmx-before-request={(e) => addCsrf(e)}
+>
+  …
+</form>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.changed).toBe(true);
+    expect(r.content).toContain(`onSubmit={(e) => { /* validate */ }}`);
+    expect(r.content).toContain("hx-on-htmx-before-request={(e) => addCsrf(e)}");
+    expect(r.content).toContain("hx-post={url}");
+    expect(r.content).toContain('hx-trigger="submit"');
+  });
+
+  it("Footer.tsx-style: simple onClick with no Fresh-ism — no TODO", () => {
+    const src = `<button hx-on:click={() => setOpen((p) => !p)}>menu</button>`;
+    const r = transformHtmxOnEvents(src);
+    expect(r.changed).toBe(true);
+    expect(r.content.startsWith(TODO_MARKER)).toBe(false);
+    expect(r.content).toBe(
+      `<button onClick={() => setOpen((p) => !p)}>menu</button>`,
+    );
+  });
+});

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

@@ -0,0 +1,193 @@
+import type { TransformResult } from "../types";
+
+/**
+ * htmx → React event-name mapping for the seven `hx-on:*` / `hx-on-*`
+ * patterns that have a 1:1 React equivalent.
+ *
+ * The codemod is intentionally narrow: only events present in this map
+ * get renamed. Custom DOM events (`hx-on:my-thing`), htmx lifecycle
+ * events (`hx-on:htmx-config-request`), and any event that requires a
+ * React `addEventListener` in `useEffect` get left alone — the
+ * `htmx-residue` audit rule catches them and points at the per-pattern
+ * `htmx-rewrite.md` skill.
+ *
+ * Kept lowercase to mirror htmx's own naming and to keep the regex
+ * simple. JSX attribute names ARE case-sensitive; htmx writers always
+ * use lowercase.
+ */
+const STANDARD_EVENT_MAP: Record<string, string> = {
+  click: "onClick",
+  dblclick: "onDoubleClick",
+  submit: "onSubmit",
+  reset: "onReset",
+  change: "onChange",
+  input: "onInput",
+  keyup: "onKeyUp",
+  keydown: "onKeyDown",
+  keypress: "onKeyPress",
+  focus: "onFocus",
+  blur: "onBlur",
+  focusin: "onFocus",
+  focusout: "onBlur",
+  mouseover: "onMouseOver",
+  mouseout: "onMouseOut",
+  mouseenter: "onMouseEnter",
+  mouseleave: "onMouseLeave",
+  mousedown: "onMouseDown",
+  mouseup: "onMouseUp",
+  mousemove: "onMouseMove",
+  contextmenu: "onContextMenu",
+  load: "onLoad",
+  scroll: "onScroll",
+  paste: "onPaste",
+  copy: "onCopy",
+  cut: "onCut",
+  dragstart: "onDragStart",
+  drag: "onDrag",
+  dragend: "onDragEnd",
+  drop: "onDrop",
+  dragenter: "onDragEnter",
+  dragleave: "onDragLeave",
+  dragover: "onDragOver",
+  wheel: "onWheel",
+  touchstart: "onTouchStart",
+  touchend: "onTouchEnd",
+  touchmove: "onTouchMove",
+  touchcancel: "onTouchCancel",
+};
+
+/**
+ * Marker comment we inject when a rename happened *and* the surviving
+ * 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
+ * so re-running the codemod does not double-inject.
+ */
+const TODO_MARKER = "// MIGRATION TODO (codemod: htmx-on-event-rename):";
+
+const TODO_BLOCK = `${TODO_MARKER}
+// hx-on:* attributes were auto-renamed to React event handlers, but
+// the handler bodies were preserved verbatim. They may reference
+// Fresh-only globals like \`globalThis.window.STOREFRONT\` or
+// \`useScript(...)\`. Verify each handler matches a TanStack Start
+// equivalent (state hook, platform hook, or server function) — see
+// .agents/skills/deco-to-tanstack-migration/references/htmx-rewrite.md
+// § Pattern 1 (event-handler).`;
+
+/**
+ * Matches a single `hx-on:eventname=` or `hx-on-eventname=` attribute
+ * occurrence in the source.
+ *
+ * `\b` before `hx-on` keeps us from matching inside identifiers like
+ * `withHx-on` (impossible in TS but defensive). The separator capture
+ * group distinguishes colon vs dash so we can flip both syntactic
+ * variants in one pass.
+ *
+ * The event name allows a-zA-Z0-9 and `-` so multi-segment htmx events
+ * (`htmx-config-request`, `htmx-before-request`) are captured intact and
+ * we can decide *after* the match whether to rename or skip.
+ */
+const HX_ON_ATTR_RE = /\bhx-on([:\-])([a-zA-Z][a-zA-Z0-9-]*)(\s*=)/g;
+
+/**
+ * Heuristic patterns for handler bodies that reference Fresh-specific
+ * globals. Used only to gate TODO injection — false positives are
+ * harmless (extra comment), false negatives are tolerable (audit will
+ * still catch htmx residue elsewhere).
+ */
+const FRESH_BODY_PATTERNS: readonly RegExp[] = [
+  /\buseScript\s*\(/,
+  /\bglobalThis\.window\.STOREFRONT\b/,
+  /\bSTOREFRONT\./,
+];
+
+/**
+ * Rewrite `hx-on:click={...}` and `hx-on-click={...}` attributes to
+ * the React equivalent (`onClick={...}`), preserving the handler value
+ * verbatim. Renames only happen for events with a known React mapping.
+ *
+ * - htmx lifecycle events (`htmx-config-request`, `htmx-before-request`,
+ *   `htmx-after-swap`, etc.) are left alone — they require manual
+ *   rewrite per the htmx-rewrite skill, and the `htmx-residue` audit
+ *   rule will catch them post-migration.
+ * - Unknown custom events (e.g. `hx-on:my-custom-thing`) are left alone
+ *   — React doesn't have synthetic equivalents for arbitrary custom
+ *   events; the engineer must wire those via `addEventListener` in
+ *   `useEffect`, which the codemod cannot generate safely.
+ *
+ * If any rename happens AND the file contains Fresh-only body
+ * patterns, a single file-level TODO comment is injected at the top so
+ * reviewers know the bodies still need attention. Idempotent — running
+ * the codemod twice produces identical output.
+ */
+export function transformHtmxOnEvents(content: string): TransformResult {
+  if (!content.includes("hx-on")) {
+    return { content, changed: false, notes: [] };
+  }
+
+  const renamesByEvent = new Map<string, number>();
+  let renamed = 0;
+
+  const next = content.replace(
+    HX_ON_ATTR_RE,
+    (match, _sep: string, eventName: string, equals: string) => {
+      const lower = eventName.toLowerCase();
+      if (lower.startsWith("htmx-")) return match;
+
+      const reactName = STANDARD_EVENT_MAP[lower];
+      if (!reactName) return match;
+
+      renamed += 1;
+      renamesByEvent.set(reactName, (renamesByEvent.get(reactName) ?? 0) + 1);
+      return `${reactName}${equals}`;
+    },
+  );
+
+  if (renamed === 0) {
+    return { content, changed: false, notes: [] };
+  }
+
+  const notes: string[] = [];
+  const breakdown = [...renamesByEvent.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, n]) => `${name}=${n}`)
+    .join(", ");
+  notes.push(`Renamed ${renamed} hx-on:* attribute(s) → React events (${breakdown})`);
+
+  const hasFreshIsms = FRESH_BODY_PATTERNS.some((re) => re.test(next));
+  const hasMarker = next.includes(TODO_MARKER);
+
+  if (!hasFreshIsms || hasMarker) {
+    return { content: next, changed: true, notes };
+  }
+
+  const final = injectTopOfFileTodo(next);
+  notes.push(
+    "Injected MIGRATION TODO — handler body references Fresh-only globals (useScript / globalThis.window.STOREFRONT)",
+  );
+  return { content: final, changed: true, notes };
+}
+
+/**
+ * Insert TODO_BLOCK as a top-of-file comment, *after* any leading
+ * shebang line or block comment. Keeps directives like `"use client"`
+ * intact (they live below the comment block, which is fine).
+ */
+function injectTopOfFileTodo(source: string): string {
+  if (source.startsWith("#!")) {
+    const newlineIdx = source.indexOf("\n");
+    if (newlineIdx === -1) return `${source}\n${TODO_BLOCK}\n`;
+    return `${source.slice(0, newlineIdx + 1)}${TODO_BLOCK}\n${source.slice(newlineIdx + 1)}`;
+  }
+  return `${TODO_BLOCK}\n${source}`;
+}
+
+/** Exported for direct unit tests. */
+export const _internals = {
+  STANDARD_EVENT_MAP,
+  HX_ON_ATTR_RE,
+  TODO_MARKER,
+  FRESH_BODY_PATTERNS,
+};