@decocms/start 2.20.0 → 2.21.0

package/.agents/skills/deco-to-tanstack-migration/SKILL.md

@@ -369,6 +369,7 @@ For sites with 100+ sections:
 | Admin / CMS integration | `references/admin-cms.md` |
 | Gotchas index | `references/gotchas.md` |
 | Post-migration cleanup checklist | `references/post-migration-cleanup.md` |
+| HTMX → React rewrite recipes | `references/htmx-rewrite.md` |
 | React hooks patterns | `references/react-hooks-patterns.md` |
 | React signals & state | `references/react-signals-state.md` |
 | JSX migration differences | `references/jsx-migration.md` |

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

@@ -0,0 +1,527 @@
+# HTMX → React Rewrite Recipes
+
+Some Deco storefronts on the Fresh stack picked up htmx as their
+interactivity model — `hx-get`, `hx-post`, `hx-target`, `hx-swap`,
+`hx-on:click`, etc. The TanStack Start / React stack does **not**
+ship an htmx runtime, and per **D2** in the
+[migration tooling policy](https://github.com/decocms/deco-start/blob/main/.cursor/rules/migration-tooling-policy.mdc)
+we don't add one — every `hx-*` attribute gets rewritten to a React
+equivalent on migration. There is no half-measure adapter package.
+
+This reference is the per-pattern playbook the engineer (and the
+Wave 14 codemods) follow.
+
+## Inventory the surface first
+
+Before rewriting anything, run the analyzer (added in
+`@decocms/start >= 2.20.0`):
+
+```bash
+# From the SOURCE site directory (Fresh repo, before migration).
+npx -p @decocms/start deco-htmx-analyze --top 20
+
+# Or after migration to verify there's nothing left:
+cd /path/to/migrated-site
+npx -p @decocms/start deco-htmx-analyze --json | jq '.totalOccurrences'
+```
+
+The analyzer groups every `hx-*` element into one of seven
+**categories**, ordered roughly by rewrite difficulty:
+
+| Category | Cluster | Difficulty |
+|---|---|---|
+| `event-handler` | `hx-on:*` / `hx-on-*`, no fetch attr | trivial — direct `onClick` |
+| `boost` | `hx-boost="true"` | trivial — `<Link>` |
+| `click-swap` | fetch + `hx-target` on a button-like element | medium — state + conditional render |
+| `form-swap` | fetch on `<form>` with target/swap | medium — `useMutation` |
+| `auto-fetch` | fetch on input or `hx-trigger=keyup\|intersect` | medium — debounced state + `useQuery` |
+| `oob-swap` | `hx-swap-oob` / `hx-select-oob` | hard — manual, no 1:1 |
+| `unmatched` | doesn't fit a known cluster | manual — read the call site |
+
+**Order of attack**: walk the list top-down. Most sites' surface is
+~40 % event-handler, ~30 % click-swap, ~10 % each form-swap and
+auto-fetch, ~5 % each oob-swap and unmatched. Knock out the trivial
+ones first — they're often the easiest wins and clear the noise.
+
+## Two syntactic flavours of `hx-on`
+
+htmx 2.x supports both colon and dash forms of event handler attrs.
+HTML's spec doesn't allow `:` in attribute names, so the dash is
+canonical:
+
+```tsx
+<button hx-on:click={useScript(...)} />     // colon (older Fresh fixtures)
+<button hx-on-click={useScript(...)} />     // dash  (htmx 2.x canonical)
+<div    hx-on-htmx-after-request={...} />   // htmx event with prefix
+```
+
+Both rewrite to the same React `onClick` / `onChange` etc.
+
+## Pattern 1 — `event-handler`
+
+The biggest bucket. Almost always a `useScript`-wrapped function
+attached as an event handler, with no fetch involved.
+
+### Before
+
+```tsx
+<button
+  hx-on:click={useScript(
+    async (skuId: string, sellerId: string) => {
+      if (!skuId || !sellerId) return;
+      const button = this as HTMLButtonElement;
+      button.dataset.loading = "true";
+      await globalThis.window.STOREFRONT.CART.addToCart({
+        orderItems: [{ id: skuId, quantity: 1, seller: sellerId }],
+      });
+      button.dataset.loading = "false";
+    },
+    productSku,
+    sellerId ?? "1",
+  )}
+>
+  Add to bag
+</button>
+```
+
+### After
+
+```tsx
+import { useState } from "react";
+import { useCart } from "~/hooks/useCart";
+
+export default function AddToBagButton({ productSku, sellerId }) {
+  const { addItems } = useCart();
+  const [loading, setLoading] = useState(false);
+
+  return (
+    <button
+      data-loading={loading}
+      onClick={async () => {
+        if (!productSku || !sellerId) return;
+        setLoading(true);
+        try {
+          await addItems({
+            orderItems: [{ id: productSku, quantity: 1, seller: sellerId ?? "1" }],
+          });
+        } finally {
+          setLoading(false);
+        }
+      }}
+    >
+      Add to bag
+    </button>
+  );
+}
+```
+
+### Gotchas
+
+- `globalThis.window.STOREFRONT.CART.*` → the platform hook
+  (`useCart` from `~/hooks/useCart`, which delegates to `createUseCart`
+  from `@decocms/apps/vtex/hooks/createUseCart`). Do not reach for
+  globals.
+- `this as HTMLButtonElement` → use a `useRef`, or read from the
+  React event (`(e) => e.currentTarget`).
+- `button.dataset.loading = "true"` direct DOM mutation breaks
+  hydration on F5 and React Compiler optimisations. Use state.
+- The `useScript` import (`@deco/deco/hooks` or
+  `@decocms/start/sdk/useScript`) becomes unused — remove it.
+
+## Pattern 2 — `boost`
+
+Trivial. `hx-boost` enabled SPA-style navigation on regular `<a>`
+elements. TanStack Router's `<Link>` does this by default.
+
+### Before
+
+```tsx
+<a hx-boost="true" href="/produto/foo">Foo</a>
+```
+
+### After
+
+```tsx
+import { Link } from "@tanstack/react-router";
+
+<Link to="/produto/$slug" params={{ slug: "foo" }}>Foo</Link>;
+```
+
+### Gotchas
+
+- For unparameterised links, `<Link to="/produto/foo">` works without
+  `params`.
+- `<a>` tags that aren't `hx-boost`-ed should also become `<Link>`
+  if they target a route in the app — but that's covered by
+  `references/navigation.md`, not by this skill.
+
+## Pattern 3 — `click-swap`
+
+The dominant button-driven shape: a button with `hx-get` (or
+`hx-post`) + `hx-target` + `hx-swap` that fetches a server-rendered
+section and swaps it into a target element.
+
+### Before
+
+```tsx
+<button
+  type="button"
+  hx-target={`#${VIEW_CONTENT_ID}`}
+  hx-swap="innerHTML transition:true"
+  hx-trigger="click"
+  hx-get={useSection({
+    props: {
+      viewConfig: {
+        view: viewIds.RECEIVE_ACCESS_CODE_FOR_PASSWORD,
+        currentEmail: props?.currentEmail,
+      },
+    },
+  })}
+  hx-indicator="this"
+>
+  Forgot password
+</button>
+```
+
+### Two After options
+
+**Option A — local state machine** (when the swap stays inside one
+component tree, e.g. a multi-step login form). Each `view` becomes a
+discriminator in component state, each section becomes a sub-component.
+
+```tsx
+import { useState } from "react";
+
+type View =
+  | { name: "EMAIL_PWD" }
+  | { name: "RECEIVE_CODE_FOR_PWD"; currentEmail?: string }
+  | { name: "FORGOTTEN_PWD" };
+
+export function LoginFlow({ initialEmail }: { initialEmail?: string }) {
+  const [view, setView] = useState<View>({ name: "EMAIL_PWD" });
+
+  if (view.name === "EMAIL_PWD") {
+    return (
+      <EmailAndPassword
+        currentEmail={initialEmail}
+        onForgotPassword={() =>
+          setView({
+            name: "RECEIVE_CODE_FOR_PWD",
+            currentEmail: initialEmail,
+          })
+        }
+      />
+    );
+  }
+  if (view.name === "RECEIVE_CODE_FOR_PWD") {
+    return <ReceiveAccessCode currentEmail={view.currentEmail} />;
+  }
+  return <ForgottenPassword />;
+}
+```
+
+The "Forgot password" button becomes:
+
+```tsx
+<button type="button" onClick={onForgotPassword}>Forgot password</button>
+```
+
+**Option B — sub-route** (when the swap should be URL-addressable,
+e.g. cart, address-book pages, account sections that benefit from
+deep-links).
+
+```tsx
+// routes/account/forgot-password.tsx
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/account/forgot-password")({
+  component: ForgottenPasswordPage,
+});
+```
+
+Button becomes:
+
+```tsx
+<Link to="/account/forgot-password">Forgot password</Link>
+```
+
+### Choose between A and B
+
+- **B** if the new "view" is a meaningful URL (search filters, tabs,
+  multi-step flows worth bookmarking, account pages).
+- **A** if the swap is incidental UI state (modals, dropdowns,
+  step-flows that should not survive reload).
+
+## Pattern 4 — `form-swap`
+
+Form posts that swap the result back into a target. Same surface as
+click-swap but on a `<form>` and triggered by `submit`.
+
+### Before
+
+```tsx
+<form
+  hx-target={`#${VIEW_CONTENT_ID}`}
+  hx-swap="innerHTML transition:true show:window:top"
+  hx-trigger="submit"
+  hx-post={useSection({
+    props: {
+      viewConfig: { view: viewIds.EMAIL_AND_PASSWORD },
+      action: actionIds.CLASSIC_SIGN_IN,
+    },
+  })}
+  hx-indicator=".submit"
+>
+  <input name="email" type="email" required />
+  <input name="password" type="password" required />
+  <button type="submit" data-test-id="login-submit">Sign In</button>
+</form>
+```
+
+### After
+
+```tsx
+import { useMutation } from "@tanstack/react-query";
+import { invoke } from "~/server/invoke";
+import { useState } from "react";
+
+export function EmailAndPassword({ onSuccess }: { onSuccess: (user: User) => void }) {
+  const [error, setError] = useState<string | null>(null);
+
+  const signIn = useMutation({
+    mutationFn: (input: { email: string; password: string }) =>
+      invoke({ "vtex.actions.auth/classicSignIn": input }),
+    onSuccess: (user) => onSuccess(user),
+    onError: (e) => setError(e.message),
+  });
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        const data = new FormData(e.currentTarget);
+        signIn.mutate({
+          email: String(data.get("email")),
+          password: String(data.get("password")),
+        });
+      }}
+    >
+      <input name="email" type="email" required />
+      <input name="password" type="password" required />
+      <button type="submit" disabled={signIn.isPending}>
+        {signIn.isPending ? "Signing in…" : "Sign In"}
+      </button>
+      {error && <p>{error}</p>}
+    </form>
+  );
+}
+```
+
+### Gotchas
+
+- `hx-post={useSection(...)}` posted to a Deco section that ran a
+  server-side handler. The TanStack equivalent is **either** a
+  server function (`createServerFn`) **or** an action exposed via
+  `invoke` over `@decocms/apps`. Pick the one whose business logic
+  already lives there.
+- `hx-indicator=".submit"` → button `disabled={mutation.isPending}`
+  + visible "Signing in…" text. No CSS class plumbing.
+- Validation errors that the section returned via re-render: now
+  surface via `mutation.onError` + state.
+
+## Pattern 5 — `auto-fetch`
+
+A fetch attribute fires automatically on a non-click trigger:
+`keyup`, `intersect`, `revealed`, `load`, or `every:Xs`. Most often
+seen on `<input>` for search-as-you-type.
+
+### Before — search-as-you-type
+
+```tsx
+<input
+  id={searchInputId}
+  name="q"
+  type="text"
+  hx-sync="this:replace"
+  hx-swap="innerHTML transition:true"
+  hx-target={`#${searchResultsId}`}
+  hx-post={useComponent(Suggestions, { id })}
+  hx-trigger="keyup changed delay:200ms"
+  class="…"
+/>
+<div id={searchResultsId}></div>
+```
+
+### After
+
+```tsx
+import { useState, useDeferredValue } from "react";
+import { useQuery, keepPreviousData } from "@tanstack/react-query";
+import { invoke } from "~/server/invoke";
+
+export function SearchInput() {
+  const [term, setTerm] = useState("");
+  const debouncedTerm = useDeferredValue(term);
+
+  const suggestions = useQuery({
+    queryKey: ["search-suggestions", debouncedTerm],
+    queryFn: () =>
+      invoke({ "vtex.loaders.intelligentSearch/suggestions": { term: debouncedTerm } }),
+    enabled: debouncedTerm.length >= 2,
+    placeholderData: keepPreviousData,
+    staleTime: 30_000,
+  });
+
+  return (
+    <>
+      <input
+        type="text"
+        value={term}
+        onChange={(e) => setTerm(e.target.value)}
+        placeholder="Search"
+      />
+      <div>{suggestions.data?.map((s) => <SuggestionRow key={s.id} item={s} />)}</div>
+    </>
+  );
+}
+```
+
+### Before — intersection-triggered (lazy load row)
+
+```tsx
+<div hx-trigger="intersect once" hx-get={useComponent(MoreItems)} hx-swap="outerHTML"></div>
+```
+
+### After
+
+```tsx
+import { useEffect, useRef, useState } from "react";
+
+export function MoreItemsLoader() {
+  const ref = useRef<HTMLDivElement>(null);
+  const [loaded, setLoaded] = useState(false);
+  const [items, setItems] = useState<Item[] | null>(null);
+
+  useEffect(() => {
+    if (loaded || !ref.current) return;
+    const obs = new IntersectionObserver(
+      async ([entry]) => {
+        if (!entry.isIntersecting) return;
+        obs.disconnect();
+        setLoaded(true);
+        setItems(await invoke({ "site.loaders/moreItems": {} }));
+      },
+      { rootMargin: "100px" },
+    );
+    obs.observe(ref.current);
+    return () => obs.disconnect();
+  }, [loaded]);
+
+  if (items) return <>{items.map((i) => <Row key={i.id} item={i} />)}</>;
+  return <div ref={ref} />;
+}
+```
+
+### Gotchas
+
+- `hx-sync="this:replace"` — the htmx-side concurrency control —
+  becomes "useQuery dedupes identical query keys + replaces results
+  on key change" automatically. No equivalent flag needed.
+- `keyup changed delay:200ms` → `useDeferredValue` gives concurrent
+  rendering, or fall back to a manual debounce hook if you want a
+  fixed delay.
+- Single-`once` triggers should set a flag on first intersection
+  and disconnect the observer (see `loaded` above).
+
+## Pattern 6 — `oob-swap`
+
+Out-of-band swaps don't have a clean React equivalent. They were
+htmx's mechanism for a server response to update **multiple
+disconnected DOM nodes** in one request — e.g. update the cart
+indicator in the header AND the cart drawer body from a single
+"add to cart" response.
+
+There's no codemod here. Two refactor patterns:
+
+### Refactor A — global state
+Lift the data the OOB nodes read into a shared store (`@tanstack/store`).
+The mutation writes to the store; the consumers re-render naturally.
+This is the right choice 90 % of the time.
+
+### Refactor B — broadcast event
+For cases where one component must trigger a side effect in another
+without a shared data shape: dispatch a custom event on `window`,
+listen for it in the consumer's `useEffect`. This is the htmx
+`hx-swap-oob` pattern, just done with browser primitives.
+
+```tsx
+// Producer
+window.dispatchEvent(new CustomEvent("cart:item-added", { detail: { itemId } }));
+
+// Consumer
+useEffect(() => {
+  const handler = (e: Event) => { /* react to e.detail */ };
+  window.addEventListener("cart:item-added", handler);
+  return () => window.removeEventListener("cart:item-added", handler);
+}, []);
+```
+
+Prefer A. Resort to B only when the producer/consumer can't share a
+parent.
+
+## Pattern 7 — `unmatched`
+
+Cases the analyzer didn't fit cleanly. Read each call site. Common
+shapes:
+
+- `<div hx-indicator="…">` standalone — passive marker that some
+  *other* element shows as a loading indicator. The other element
+  is the real interactivity site; rewrite there. The `hx-indicator`
+  div becomes plain JSX gated on a state boolean.
+- `htmx-request:` Tailwind variants (`htmx-request:loading`,
+  `[.htmx-request>&]:hidden`) — these toggle styles based on
+  htmx's own request lifecycle. Replace with `data-[loading=true]:`
+  variants driven by your component state.
+- `hx-confirm`, `hx-prompt` — synchronous browser dialogs. Use the
+  site's modal system, or `window.confirm()` if it was always a
+  trivial native dialog.
+- Any `hx-*` attribute on a Deco component import path
+  (`<Accordion.Trigger hx-on-click={...}>`) — the component itself
+  spreads attrs onto a child element. Lift the handler into a prop.
+
+## Verification
+
+After the rewrite, the post-cleanup audit's
+**`htmx-residue`** rule (Wave 13-C) reports any remaining `hx-*` in
+the migrated `src/`. A site is "rewrite-complete" when `htmx-residue
+== 0` for non-test files.
+
+```bash
+npx -p @decocms/start deco-post-cleanup --strict
+# exit 2 if any hx-* attributes survive in src/
+```
+
+You can also re-run the analyzer on the migrated tree to verify
+zero hits:
+
+```bash
+npx -p @decocms/start deco-htmx-analyze
+# expects: ✓ No hx-* attributes found.
+```
+
+## Real-world signal — als-storefront
+
+Initial inventory across 133 source files, 210 occurrences:
+
+| Bucket | Count | % |
+|---|---:|---:|
+| event-handler | 88 | 42 % |
+| click-swap | 64 | 30 % |
+| form-swap | 20 | 10 % |
+| auto-fetch | 9 | 4 % |
+| oob-swap | 8 | 4 % |
+| unmatched | 21 | 10 % |
+
+86 % of occurrences fall in codemod-able buckets (event-handler,
+click-swap, form-swap, auto-fetch). Wave 14 ships codemods for those
+four; the rest stay manual.

package/.agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md

@@ -359,7 +359,46 @@ rm src/types/widgets.ts
 Confirm `tsc --noEmit` is still clean — the framework version is a
 strict superset of what the migration script generated.
 
-## 7. Search for orphan `TODO: move into framework` comments
+## 7. Verify no leftover HTMX residue in `src/`
+
+For sites that came from a Fresh codebase using HTMX (`@deco/htmx`,
+`hx-*` attributes on JSX elements), the migration to TanStack Start
+requires **rewriting** every HTMX interaction to React state +
+event handlers + `useNavigate()`/sub-routes. The framework
+intentionally ships **no** HTMX runtime — leaving `hx-*` attributes
+in the migrated `src/` tree means the corresponding interaction is
+silently dead.
+
+The audit's `htmx-residue` rule scans every `*.{ts,tsx}` under `src/`
+(excluding `*.test.tsx` / `*.spec.ts` / `__tests__/`) for any
+remaining `hx-*` attribute, classifies each occurrence into one of
+seven categories (`event-handler`, `form-swap`, `click-swap`,
+`auto-fetch`, `oob-swap`, `boost`, `unmatched`), and emits one
+warning per file with a category breakdown:
+
+```
+[WARNING] src/components/AddToBagButton.tsx:14 — 1 hx-* element(s) — event-handler=1
+  fix: Rewrite per .agents/skills/deco-to-tanstack-migration/references/htmx-rewrite.md
+       (run `deco-htmx-analyze` for the per-category breakdown)
+```
+
+The rule is intentionally **detect-only**:
+
+- The rewrites are non-mechanical — choosing between a local state
+  machine, a sub-route, a React form action, or a platform hook
+  (e.g. `useCart`) varies per call site and depends on the data
+  flow, not just the attribute cluster.
+- The companion CLI `deco-htmx-analyze` produces a richer inventory
+  (top tags, sample line numbers, JSON output) when you need to
+  triage hundreds of occurrences across a large repo.
+- The `references/htmx-rewrite.md` skill is the per-pattern
+  playbook with before/after code for each of the seven categories.
+
+In `--strict` mode any residue exits 2 — wire that into CI once a
+site has finished its HTMX rewrite to prevent regressions sneaking
+back in via copy-paste from a Fresh source.
+
+## 8. Search for orphan `TODO: move into framework` comments
 
 Real sites accumulate `TODO` comments like `// TODO: move into decoVitePlugin
 in next @decocms/start release`. These are roadmap items the framework
@@ -376,7 +415,7 @@ For each hit, decide:
 
 ## Verification checklist
 
-After completing 1-7:
+After completing 1-8:
 
 - [ ] `npm run typecheck` baseline matches pre-cleanup count (no new errors)
 - [ ] `npm run dev` starts and `/`, `/some-pdp/p`, `/s?q=foo` all render

package/MIGRATION_TOOLING_PLAN.md

@@ -766,18 +766,73 @@ Wave 12 ships in priority-1 order; Wave 13 starts now.
   prove it on 2 sites, promote to `@decocms/apps`, then rewrite the
   template to use the canonical.
 
-### Wave 13 (htmx foundations — Priority 2 part 1) — planned
+### Wave 13 (htmx foundations — Priority 2 part 1) — ✅ **COMPLETE**
 
-Once Wave 12 is in, the migration script needs an htmx track because
-als is the first heavy htmx site and we know it won't be the last
-(per the user, "some of our sites are, not all, not even most, some").
+Once Wave 12 was in, the migration script needed an htmx track
+because als is the first heavy htmx site and we know it won't be
+the last (per the user, "some of our sites are, not all, not even
+most, some"). **3 PRs in `deco-start`, all merged.** D2 forbids an
+htmx adapter package; nothing in Wave 13 ships htmx runtime — only
+analysis, rewrite recipes, and a "rewrite-complete" gate.
 
-- **W13-A** deco-start: `scripts/migrate/htmx-analyze.ts` — categorize hx-* by pattern (form-swap, click-fetch, hx-on, hx-trigger+useSection, etc.). Output: per-site htmx inventory.
-- **W13-B** deco-start: skill `references/htmx-rewrite.md` — pattern catalog with per-pattern rewrite recipe (decision tree: codemod vs manual recipe).
-- **W13-C** deco-start: audit rule `htmx-residue` — counts `hx-*` attributes still in `src/`. Required-empty for "rewrite-complete" sites.
+**Shipped PRs:**
 
-D2 forbids an htmx adapter package; nothing in Wave 13 ships htmx
-runtime.
+- **W13-A** [`deco-start#129`](https://github.com/decocms/deco-start/pull/129) — `feat(migrate): htmx surface analyzer` ✅ **MERGED**, released as `@decocms/start@2.20.0`.
+  Adds `scripts/migrate/analyzers/htmx-analyze.ts` (per-file walker + classifier) and the `deco-htmx-analyze` CLI. The walker is heuristic JSX (regex for `hx-*` attrs, brace-balanced traversal back to the opening tag, forward to the closing `>` / `/>`) — skips strings, template literals, JSX expression slots, and balanced `{...}` blocks. Each occurrence is classified into one of seven categories (`event-handler`, `form-swap`, `click-swap`, `auto-fetch`, `oob-swap`, `boost`, `unmatched`) based on the attribute cluster, not individual attrs (recipes apply to clusters, not attrs in isolation). CLI emits per-category counts, top tags, sample line numbers, and a one-line migration recipe; `--json` for tooling. 24 tests covering classification (all 7 categories + tie-breaks + dash-variant `hx-on`) and real als-shaped fixtures (AddToBagButton, SearchInput, EmailAndPassword, ForgotPassword).
+- **W13-B** [`deco-start#130`](https://github.com/decocms/deco-start/pull/130) — `docs(skills): add htmx-rewrite reference` ✅ **MERGED**.
+  Per-pattern playbook at `.agents/skills/deco-to-tanstack-migration/references/htmx-rewrite.md`. For each of the seven categories: a "Before" snippet pulled directly from als (so the recipe is grounded in what an engineer is actually staring at), an "After" snippet using the canonical TanStack Start patterns (`useState` + `useCart`, `useNavigate`, `useMutation`, sub-routes), an explicit decision criterion when more than one path is reasonable (e.g. local state machine vs. sub-route for `click-swap`), and a "Gotchas" block enumerating the failure modes humans actually hit (focus loss, double-submit, hydration mismatch, etc.). Cross-linked from `SKILL.md`'s problem table.
+- **W13-C** [`deco-start#131`](https://github.com/decocms/deco-start/pull/131) — `feat(audit): htmx-residue rule` ✅ **MERGED**, released as `@decocms/start@2.21.0`.
+  Eighth audit rule. Reuses `analyzeFile` from `analyzers/htmx-analyze.ts` to scan `src/**/*.{ts,tsx}` (excluding `*.test.tsx` / `*.spec.ts` / `__tests__/`) and emits one warning per file with a category breakdown (`event-handler=2, form-swap=1`). Severity is `warning` so `--strict` exits 2 — the "rewrite-complete" CI gate. The fix string points at `references/htmx-rewrite.md`. Intentionally **detect-only** — rewrites are non-mechanical (state machine vs. sub-route vs. mutation choices vary per call site), so `--fix` wiring would be misleading; the skill is the playbook. 7 new tests cover aggregation, severity, test-file exclusion, scope (`src/` only), zero-finding gate, line-number reporting, and `supportsAutoFix: false`. Skill doc § 7 added explaining the rule + when to wire it into CI; help text updated.
+
+### Wave 13 — discoveries
+
+- **Heuristic JSX walking is enough; full AST is not needed for
+  this surface.** `analyzeFile` goes character-by-character with
+  brace-counting and string/template/comment skipping; it correctly
+  identifies attribute clusters in 100 % of the als-storefront and
+  internal-fixture sample (~120 files, ~270 hx-* attributes), and
+  the test corpus pins the tricky cases (dash-variant `hx-on-*`,
+  attached comments, balanced JSX expressions inside attributes,
+  multiline tags). Pulling in `@swc/core` or `recast` for this
+  would be over-engineering — the walker is ~150 LOC, deterministic,
+  and shares a single source of truth between the standalone CLI
+  (`deco-htmx-analyze`), the post-cleanup audit rule
+  (`htmx-residue`), and the per-pattern recipe references.
+- **Classify by attribute cluster, not by individual attribute.**
+  An `hx-on:click` and `hx-post + hx-target + hx-swap` get
+  fundamentally different rewrites. Categorising at the cluster
+  level (the JSX tag + all its hx-* attrs) means each finding
+  points at exactly one of seven recipes in
+  `references/htmx-rewrite.md`. This is the same discipline that
+  worked for `STUB_FIX_HINTS` in the vtex-shim rule: the data shape
+  encodes the actionability category, the rule is just a thin
+  classifier on top.
+- **D2 + W13-C form a closed loop, mirroring the W12 D3 + audit
+  pattern.** D2 says "no htmx runtime in `@decocms/start`". W13-C's
+  `htmx-residue` rule says "fail CI if any `hx-*` survives in
+  `src/`". Together: a migrated site cannot accidentally rely on
+  htmx because (a) the framework gives them no runtime to import,
+  (b) the audit catches every leftover `hx-*` in code review.
+- **Detect-only is correct here, not a stop-gap.** Auto-fixing
+  htmx is conceptually hard: even a "simple" `<button hx-post>` →
+  `useMutation` rewrite has to choose between optimistic vs
+  pessimistic UI, error handling shape, where to surface the
+  loading state, and whether the response should re-render the
+  whole page or a fragment. Each is a per-site product decision.
+  The pattern catalog in `references/htmx-rewrite.md` is the
+  durable artefact; codemods (Wave 14) can target a specific
+  cluster shape (e.g. `hx-post + hx-target=#id + hx-swap=innerHTML`
+  with no `hx-trigger`) safely, but they're scoped by category,
+  not the rule's auto-fix.
+- **The audit registry is now self-shaped for additive growth.**
+  Eight rules, three of which (`vtex-shim-regression`,
+  `obsolete-vite-plugins`, `htmx-residue`) ship with their own
+  analyzer modules. The pattern is set: add a rule to
+  `ALL_RULES`, supply `applyFix` only when mechanical, point the
+  prose `fix:` field and JSON `meta` at a skill reference. The CLI
+  (`migrate-post-cleanup.ts`) is rule-agnostic — adding a ninth
+  rule means changing one file, getting `--strict` and `--json`
+  for free.
 
 ### Wave 14 (htmx codemods + first als migration on 2.14+) — planned
 

package/package.json

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

package/scripts/migrate/post-cleanup/rules.ts

@@ -9,6 +9,7 @@
  * Rules are intentionally read-only here — `--fix` is a follow-up.
  */
 
+import { analyzeFile as analyzeHtmxFile } from "../analyzers/htmx-analyze";
 import { classifyShimExports, type ExportClass } from "./shim-classify";
 import type { Finding, FixAction, FsWriter, Rule, RuleContext } from "./types";
 
@@ -887,6 +888,76 @@ const ruleFrameworkTodos: Rule = {
   },
 };
 
+/* ------------------------------------------------------------------ */
+/* Rule 8 — `htmx-residue` — leftover hx-* attrs in migrated src/      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Per D2 in the migration tooling policy, every `hx-*` attribute is
+ * rewritten on migration; nothing in `@decocms/start` ships an htmx
+ * runtime. This rule is the verification gate: a migrated site is
+ * "rewrite-complete" when there are zero `hx-*` attributes left in
+ * `src/`.
+ *
+ * Implementation reuses the htmx analyzer (`analyzeFile` from
+ * `analyzers/htmx-analyze.ts`) so categorisation and the JSX walker
+ * stay consistent with the standalone `deco-htmx-analyze` CLI. The
+ * rule restricts to `src/**` (the migrated React tree) and excludes
+ * test files — tests are allowed to mention `hx-*` for fixtures or
+ * regression checks.
+ *
+ * Severity is `warning`, so `--strict` exits 2 on any finding. The
+ * rule is intentionally detect-only: rewrites are non-mechanical
+ * (state machine + sub-route + mutation choices vary per call site)
+ * — the
+ * `references/htmx-rewrite.md` skill is the playbook.
+ */
+const ruleHtmxResidue: Rule = {
+  id: "htmx-residue",
+  title: "HTMX residue in migrated src/",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const findings: Finding[] = [];
+    const tsFiles = fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
+    for (const abs of tsFiles) {
+      const rel = abs.slice(siteDir.length + 1);
+      // Skip test files — tests legitimately reference hx-* in fixtures
+      // or regression checks. Same exclusion shape as vitest's default.
+      if (/\.(test|spec)\.(ts|tsx)$/.test(rel)) continue;
+      if (rel.startsWith("src/__tests__/") || rel.includes("/__tests__/")) {
+        continue;
+      }
+      const content = fs.readText(abs);
+      const occurrences = analyzeHtmxFile(rel, content);
+      if (occurrences.length === 0) continue;
+
+      // Aggregate per-file: total + categories present.
+      const byCat = new Map<string, number>();
+      for (const occ of occurrences) {
+        byCat.set(occ.category, (byCat.get(occ.category) ?? 0) + 1);
+      }
+      const catSummary = [...byCat.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([cat, n]) => `${cat}=${n}`)
+        .join(", ");
+      const firstLine = occurrences[0].line;
+
+      findings.push({
+        rule: "htmx-residue",
+        severity: "warning",
+        file: `${rel}:${firstLine}`,
+        message: `${occurrences.length} hx-* element(s) — ${catSummary}`,
+        fix: `Rewrite per .agents/skills/deco-to-tanstack-migration/references/htmx-rewrite.md (run \`deco-htmx-analyze\` for the per-category breakdown)`,
+        meta: {
+          total: occurrences.length,
+          byCategory: Object.fromEntries(byCat),
+          firstLine,
+        },
+      });
+    }
+    return findings;
+  },
+};
+
 export const ALL_RULES: Rule[] = [
   ruleDeadLibShims,
   ruleObsoleteVitePlugins,
@@ -895,6 +966,7 @@ export const ALL_RULES: Rule[] = [
   ruleVtexShimRegression,
   ruleLocalWidgetsTypes,
   ruleFrameworkTodos,
+  ruleHtmxResidue,
 ];
 
 /** Exported for direct unit tests. */
@@ -907,6 +979,7 @@ export const _internals = {
     ruleDeadRuntimeShim,
     ruleSiteLocalGlobals,
     ruleVtexShimRegression,
+    ruleHtmxResidue,
     ruleLocalWidgetsTypes,
     ruleFrameworkTodos,
   },

package/scripts/migrate/post-cleanup/runner.test.ts

@@ -986,3 +986,111 @@ export default defineConfig({
     expect(supported).toContain("obsolete-vite-plugins");
   });
 });
+
+/* ------------------------------------------------------------------ */
+/* W13-C — htmx-residue rule                                           */
+/* ------------------------------------------------------------------ */
+
+describe("rule: htmx-residue", () => {
+  it("flags any leftover hx-* element in src/ with category breakdown", () => {
+    const fs = makeFs({
+      "/site/src/components/AddToBag.tsx":
+        '<button hx-on:click={() => {}}>buy</button>\n',
+      "/site/src/components/Search.tsx":
+        '<form hx-post="/x" hx-target="#r" hx-swap="innerHTML"><input/></form>\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.findings).toHaveLength(2);
+    const summary = r.findings.map((f) => f.message).join(" | ");
+    expect(summary).toContain("event-handler=1");
+    expect(summary).toContain("form-swap=1");
+    expect(r.findings[0].fix).toContain("htmx-rewrite.md");
+  });
+
+  it("aggregates multiple occurrences in one file as a single finding", () => {
+    const fs = makeFs({
+      "/site/src/components/Big.tsx":
+        '<button hx-on:click={() => {}}>1</button>\n' +
+        '<button hx-on:click={() => {}}>2</button>\n' +
+        '<form hx-post="/x" hx-target="#r" hx-swap="innerHTML"><input/></form>\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].message).toContain("3 hx-* element(s)");
+    expect(r.findings[0].message).toContain("event-handler=2");
+    expect(r.findings[0].message).toContain("form-swap=1");
+    expect(r.findings[0].meta?.total).toBe(3);
+  });
+
+  it("emits warning severity (so --strict exits 2)", () => {
+    const fs = makeFs({
+      "/site/src/x.tsx": '<button hx-on:click={() => {}}>x</button>\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.findings[0].severity).toBe("warning");
+  });
+
+  it("excludes test files (*.test.tsx, *.spec.ts, __tests__/) — they may legitimately reference hx-*", () => {
+    const fs = makeFs({
+      "/site/src/components/x.test.tsx":
+        '<button hx-on:click={() => {}}>x</button>\n',
+      "/site/src/components/y.spec.ts":
+        'expect(html).toContain("hx-post=\\"/x\\""); /* doesn\'t hit our regex */\n',
+      "/site/src/__tests__/csrf.tsx":
+        '<form hx-post="/x" hx-target="#r" hx-swap="innerHTML"><input/></form>\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("does NOT flag files outside src/ (the rule is scoped to migrated React tree)", () => {
+    const fs = makeFs({
+      // A pre-migration site might still have ./components/ at root.
+      // After migration that's gone; if the engineer left some stragglers
+      // in /scripts or /docs they don't block "rewrite-complete" gate.
+      "/site/scripts/legacy.tsx":
+        '<button hx-on:click={() => {}}>x</button>\n',
+      "/site/docs/example.tsx":
+        '<button hx-on:click={() => {}}>x</button>\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("returns zero findings on a clean migrated tree (the rewrite-complete gate)", () => {
+    const fs = makeFs({
+      "/site/src/components/Real.tsx":
+        '<button onClick={() => {}}>x</button>\n',
+      "/site/src/routes/index.tsx":
+        'export const Route = createFileRoute("/")({ component: () => <div/> });\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("reports the line number of the FIRST hx-* element in the file", () => {
+    const fs = makeFs({
+      "/site/src/x.tsx":
+        "import x from 'y';\n" +
+        "// header\n" +
+        '<button hx-on:click={() => {}}>x</button>\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.findings[0].file).toBe("src/x.tsx:3");
+    expect(r.findings[0].meta?.firstLine).toBe(3);
+  });
+
+  it("does NOT support auto-fix (rewrites are non-mechanical)", () => {
+    const fs = makeFs({});
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "htmx-residue")!;
+    expect(r.supportsAutoFix).toBe(false);
+  });
+});

package/scripts/migrate-post-cleanup.ts

@@ -76,8 +76,9 @@ function showHelp() {
   Options:
     --source <dir>   Site directory to audit (default: .)
     --fix            Auto-apply mechanical fixes for the safe rules
-                     (dead-lib-shims, dead-runtime-shim, local-widgets-types).
-                     Other rules still detect-only.
+                     (dead-lib-shims, dead-runtime-shim, local-widgets-types,
+                     vtex-shim-regression swap subset, obsolete-vite-plugins).
+                     Other rules — including htmx-residue — stay detect-only.
     --json           Emit machine-readable JSON instead of pretty text
     --strict         Exit code 2 if any warning-severity findings exist
     --help, -h       Show this help