@decocms/start 2.21.0 → 2.22.0

package/.agents/skills/deco-to-tanstack-migration/references/htmx-rewrite.md

@@ -62,6 +62,27 @@ Both rewrite to the same React `onClick` / `onChange` etc.
 The biggest bucket. Almost always a `useScript`-wrapped function
 attached as an event handler, with no fetch involved.
 
+> **Codemod available** (since `@decocms/start >= 2.21.0`). The
+> migration script's `transforms` pipeline now runs
+> `htmx-on-event-rename`, which mechanically rewrites
+> `hx-on:click={…}` → `onClick={…}` (and every other standard DOM
+> event in the [STANDARD_EVENT_MAP](https://github.com/decocms/deco-start/blob/main/scripts/migrate/transforms/htmx-on-events.ts)
+> table) for both colon and dash variants. Handler bodies are
+> preserved verbatim; if the body references Fresh-only globals
+> (`useScript(…)`, `globalThis.window.STOREFRONT`, `STOREFRONT.…`),
+> the codemod injects a single MIGRATION TODO comment at the top
+> of the file pointing back here. **htmx lifecycle events**
+> (`hx-on:htmx-config-request`, `hx-on-htmx-before-request`, etc.)
+> and unknown custom events (`hx-on:my-custom-thing`) are left
+> alone — those need manual rewrite, and the `htmx-residue` audit
+> rule catches them.
+>
+> Smoke result on als-storefront (754 files): codemod renames 98
+> `hx-on:*` attributes across 71 files; 67 of those files (94 %)
+> get the body-TODO. Engineers still own the body rewrite below;
+> the codemod just removes the dead `hx-*` attribute name so the
+> file compiles in React.
+
 ### Before
 
 ```tsx

package/MIGRATION_TOOLING_PLAN.md

@@ -239,6 +239,36 @@ Each item carries a status: ⬜ pending, 🟡 in progress, ✅ done, 🚫 blocke
 
 > Append-only. Each entry: date, what we found, where it impacts the plan.
 
+### 2026-05-01 — Wave 14-A rescoped from three codemods to one based on real als data
+
+- **Pre-data plan vs post-data plan.** The plan called for three
+  htmx codemods (`event-handler`, `form-swap`, `click-swap`).
+  After running `deco-htmx-analyze` against als-storefront's
+  actual code (210 occurrences across 133 files), only the
+  `event-handler` bucket (88 occurrences, 42 %) genuinely admits
+  a mechanical rewrite — the other buckets need per-call-site
+  product decisions a codemod cannot encode. **Decided: ship
+  one codemod (W14-A: `htmx-on-event-rename`), defer the other
+  two to W15+.** Rationale captured in the Wave 14 — discoveries
+  block.
+- **Codemod shape generalises:** rename + preserve body +
+  conditional file-level TODO. Three outputs, one mechanical,
+  one verbatim, one conditional on body-content heuristics. This
+  is the shape any future per-pattern codemod should target.
+- **Smoke against the real source tree validated the design in
+  five minutes.** 754 files scanned, 71 changed, 98 renames, 67
+  TODO injections (94 % of changed files). Without that smoke
+  step we'd have shipped blind on edge cases like multi-line
+  values, mixed standard + lifecycle hooks on the same element,
+  and the colon-vs-dash variants both showing up in the same
+  file.
+- **The codemod + audit pair closes another loop.** Same shape
+  as W12 (D3 throwing stubs + audit `--fix` for swap-able
+  stubs). The codemod removes the mechanical half of the htmx
+  surface; the `htmx-residue` audit catches the surviving half
+  in CI. Engineers can never silently ship a half-rewritten
+  file.
+
 ### 2026-05-01 — als-storefront surfaces the htmx track + policy reset
 
 - **als-storefront is the third migration target and the first
@@ -834,12 +864,125 @@ analysis, rewrite recipes, and a "rewrite-complete" gate.
   rule means changing one file, getting `--strict` and `--json`
   for free.
 
-### Wave 14 (htmx codemods + first als migration on 2.14+) — planned
-
-- **W14-A** deco-start: codemod `transforms/htmx-form-post-swap.ts` — `<form hx-post={url} hx-target hx-swap>` → `useMutation` + state setter
-- **W14-B** deco-start: codemod `transforms/htmx-click-fetch-swap.ts` — `<button hx-get={url}>` → onClick + invoke + state
-- **W14-C** deco-start: codemod `transforms/htmx-on-click-script.ts` — `hx-on:click={useScript(...)}` → `onClick` handler
-- **W14-D** als: rm -rf old als-tanstack, fresh `deco-migrate` run on 2.14+ with new htmx codemods. Per D5 (no --restart), this is the only restart UX.
+### Wave 14 (htmx codemod — Priority 2 part 2) — ✅ **PARTIAL / RESCOPED**
+
+After shipping the W13 htmx foundations and gathering real data
+from als-storefront with `deco-htmx-analyze`, the planned three-codemod
+scope was reduced to **one codemod** + **one inventory artefact**.
+The other two codemods (form-swap, click-swap) were deferred to W15+,
+to be designed *after* als migration data exposes which exact
+attribute clusters dominate. **Rationale logged in W14 discoveries.**
+
+**Shipped:**
+
+- **W14-A** [`deco-start#132`](https://github.com/decocms/deco-start/pull/132) — `feat(migrate): htmx-on-event-rename codemod` ✅ **MERGED**, released as `@decocms/start@2.22.0`.
+  Adds `scripts/migrate/transforms/htmx-on-events.ts` to the migrate
+  `transforms/` pipeline. Mechanically rewrites `hx-on:event=` and
+  `hx-on-event=` (colon + dash variants) to the React equivalent
+  for every standard DOM event in `STANDARD_EVENT_MAP` (40 entries:
+  click, submit, change, input, key*, mouse*, focus*, drag*, touch*,
+  paste/copy/cut, scroll, wheel, load, contextmenu). Handler bodies
+  are preserved verbatim. **Idempotent** — running twice is a no-op.
+  Two safety hatches: htmx lifecycle events (`hx-on:htmx-*`) and
+  unknown custom events left alone (the `htmx-residue` audit catches
+  them); a single top-of-file MIGRATION TODO comment is injected
+  when the body references Fresh-only globals (`useScript(…)`,
+  `globalThis.window.STOREFRONT`, `STOREFRONT.…`) so engineers
+  don't ship a syntactically-clean file with broken runtime calls.
+  29 unit tests + als-shaped fixtures (AddToBagButton, SearchInput,
+  RecoveryPassword form, Footer.tsx). 339/339 pass; typecheck clean.
+  htmx-rewrite skill § Pattern 1 cross-references the codemod.
+- **W14-B** [`deco-start#132`](https://github.com/decocms/deco-start/pull/132) — captured the **als-storefront htmx inventory** in this plan (this section) as a fixture for future W15+ codemod design.
+
+**Deferred (intentionally) — see Wave 14 discoveries:**
+
+- ~~**W14-C** codemod `transforms/htmx-form-post-swap.ts`~~ — moved to W15+. The form-swap rewrite is genuinely non-mechanical (per-call-site decisions about optimistic vs pessimistic UI, where to surface loading state, which response handler shape). A speculative codemod would produce React skeletons that still need ~80 % manual work.
+- ~~**W14-D** codemod `transforms/htmx-click-fetch-swap.ts`~~ — moved to W15+. Same logic; on top of that, choosing between local state machine vs sub-route is a routing-architecture decision that varies per page.
+
+#### W14-A smoke + als inventory (captured 2026-05-01)
+
+The W13-A `deco-htmx-analyze` CLI run against als-storefront's
+production Fresh tree:
+
+| Category | Count | % | Notes |
+|---|---:|---:|---|
+| `event-handler` | 88 | 42 % | **Codemoded by W14-A** — mechanical rename |
+| `click-swap` | 64 | 30 % | Manual (W15+) — needs state vs sub-route decision |
+| `form-swap` | 20 | 10 % | Manual (W15+) — needs `useMutation` shape decision |
+| `auto-fetch` | 9 | 4 % | Manual — debounced state + `useQuery` |
+| `oob-swap` | 8 | 4 % | Manual — no 1:1 React equivalent |
+| `unmatched` | 21 | 10 % | Mostly typed-generic noise (`<string>` from `Map<string,X>`) |
+| **Total** | **210** | | across 133 files |
+
+W14-A codemod sweep against the same tree (754 ts/tsx files):
+
+| Metric | Value |
+|---|---:|
+| Files scanned | 754 |
+| Files changed | 71 |
+| Total `hx-on:*` attributes renamed | 98 |
+| Files getting the MIGRATION TODO | 67 (94 % of changed) |
+
+The 98 vs 88 discrepancy is expected: the analyzer counts attribute
+*clusters* per element (an `<input hx-post hx-target hx-on:change>`
+classifies as one `auto-fetch`); the codemod counts individual
+`hx-on:*` attribute renames (the same element gets one rename
+plus the `auto-fetch` cluster left intact for the engineer to
+finish). Net effect: ~98 mechanical wins, leaving ~112 cluster
+rewrites (click-swap + form-swap + auto-fetch + oob-swap +
+unmatched) for the engineer — matching the manual rewrite
+recipes in `references/htmx-rewrite.md`.
+
+### Wave 14 — discoveries
+
+- **Speculative codemods are over-engineering; data-driven scope
+  is better.** The pre-data plan said three codemods (event-handler,
+  form-swap, click-swap). After running `deco-htmx-analyze` against
+  als-storefront's actual code, only the event-handler bucket
+  (88 occurrences, 42 % of the surface) genuinely admits a
+  mechanical rewrite. The other two buckets need per-call-site
+  product decisions (state machine vs sub-route, optimistic vs
+  pessimistic UI, response-handler shape) that a codemod cannot
+  encode without producing React skeletons that still need ~80 %
+  manual work — net negative versus the recipe in
+  `references/htmx-rewrite.md`. **New rule: codemods come *after*
+  the analyzer data, not before.**
+- **The smoke-against-real-site step is the design feedback loop.**
+  Running the codemod against als's full 754-file tree (98
+  renames, 71 files changed, 67 with TODO injection) validated
+  three things in five minutes: (a) the rename surface matches
+  the inventory (98 vs 88 ratio explained), (b) the TODO
+  injection rate is high (94 %) — the marker is essential, not
+  defensive, (c) the codemod is idempotent at scale (re-running
+  produces zero diffs). Without this step we'd ship blind.
+- **The three-output codemod shape (rename + preserve body +
+  conditional TODO) generalises.** Same shape any future
+  per-pattern codemod should target: do the mechanical part,
+  preserve the human-decision-required part, leave a single
+  file-level marker the engineer can grep for. Over-eager
+  body rewriting is what produces the ~80 % manual cleanup load
+  that justifies leaving form-swap / click-swap codemods out for
+  now.
+- **`htmx-residue` audit + W14-A codemod close another loop.**
+  Same pattern as W12 (D3 throwing stubs + audit `--fix` for
+  swap-able stubs). The codemod removes the easy half of the
+  htmx surface; the audit catches the surviving half. Engineers
+  can never accidentally ship a half-rewritten file: the
+  attribute is either gone (codemod ran, body might still need
+  work — TODO), or it's still there (audit fires in CI).
+- **als-storefront's profile probably generalises to other htmx
+  sites.** 42 % event-handler is a strong skew toward
+  trivially-mechanical rewrites; even if other sites differ,
+  this codemod alone removes the largest single bucket. If a
+  future site shows 80 % click-swap, *that* would be the cue to
+  build the click-swap codemod — not pre-emptively now.
+- **Pipeline order matters.** Codemod runs after `transformJsx`
+  (which renames `class` → `className` and `onInput` → `onChange`)
+  and before `transformFreshApis` (which removes `useScript`
+  imports). If `transformFreshApis` ran first, the codemod's
+  TODO marker would still fire (we look for `useScript(` calls,
+  not the import), but the import-removal would create dead
+  references. Order is correct.
 
 ### Wave 15+ (htmx cleanup PRs on als + propagation to other sites) — Priority 3 / 4
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.21.0",
+  "version": "2.22.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/migrate/phase-transform.ts

@@ -9,6 +9,7 @@ import { transformFreshApis } from "./transforms/fresh-apis";
 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 { createSectionConventionsTransform } from "./transforms/section-conventions";
 
 /** Map of section path → metadata, populated per-run */
@@ -54,10 +55,15 @@ function applyTransforms(content: string, filePath: string, ctx?: MigrationConte
     return { content, changed: false, notes: [] };
   }
 
-  // Pipeline: imports → jsx → fresh-apis → dead-code → deno-isms → tailwind
+  // Pipeline: imports → jsx → htmx-on-events → fresh-apis → dead-code → deno-isms → tailwind
+  // htmx-on-events runs after jsx (which renames class/onChange) and
+  // before fresh-apis (which removes useScript imports the htmx
+  // codemod's TODO might still reference). The codemod is a no-op on
+  // files without hx-on, so it never adds latency to non-htmx sites.
   const pipeline: Array<{ name: string; fn: (content: string) => TransformResult }> = [
     { name: "imports", fn: (c) => transformImports(c, ctx?.islandWrapperTargets) },
     { name: "jsx", fn: transformJsx },
+    { name: "htmx-on-events", fn: transformHtmxOnEvents },
     { name: "fresh-apis", fn: transformFreshApis },
     { name: "dead-code", fn: (c) => transformDeadCode(c, ctx?.platform) },
     { name: "deno-isms", fn: transformDenoIsms },

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,
+};