@decocms/start 2.19.0 → 2.20.0

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

@@ -17,7 +17,8 @@ of which sections below actually apply to your codebase:
 npx -p @decocms/start deco-post-cleanup
 
 # Auto-apply mechanical fixes for the safe rules, then report what's left.
-# Safe rules: dead-lib-shims, dead-runtime-shim, local-widgets-types.
+# Safe rules: dead-lib-shims, dead-runtime-shim, local-widgets-types,
+# vtex-shim-regression (swap subset), obsolete-vite-plugins.
 # Other rules stay detect-only — they require human judgment.
 npx -p @decocms/start deco-post-cleanup --fix
 
@@ -29,18 +30,23 @@ npx -p @decocms/start deco-post-cleanup --json
 ```
 
 The audit covers all 7 rules below and prints the exact file path +
-suggested fix for each finding. With `--fix`, the three safe rules
-auto-apply (`rm` for dead files, regex-anchored import rewrites for
-shadowed shims). The output explicitly tags rules that require manual
-work as `(0 fixed, manual)`, so you always know what's left after
-auto-fix runs.
+suggested fix for each finding. With `--fix`, the safe rules
+auto-apply: `rm` for dead files, regex-anchored import rewrites for
+shadowed shims (`local-widgets-types`, `dead-runtime-shim`), the swap
+subset of `vtex-shim-regression`, and JS-aware removal of obsolete
+inline plugin literals from `vite.config.ts`. The output explicitly
+tags rules that require manual work as `(0 fixed, manual)`, so you
+always know what's left after auto-fix runs.
 
 Real-world signal: on baggagio, `--fix` produced a byte-identical
 diff to the manual cleanup PR a human had just made (45 files,
 +45/-53). On casaevideo-storefront (production), the audit caught
 six silent VTEX shim regressions that no `tsc --noEmit` run can
-detect — those still require manual cleanup until rule 5 gains a
-per-shim mapping table.
+detect — `--fix` covers the swap subset of those automatically since
+`>= 2.16.0`. On the same site's `vite.config.ts`, `--fix` removes
+both obsolete inline plugins (`site-manual-chunks` +
+`deco-stub-meta-gen`) cleanly — ~74 LOC / 2.5 KB gone, attached
+comments included.
 
 ## 1. Delete unused `src/lib/*` shims
 
@@ -115,8 +121,14 @@ The framework's `decoVitePlugin()` now handles both:
   old split caused circular-dep load-order crashes — every site overrode it)
 - `meta.gen.{json,ts}` is stubbed on the client by default
 
-Delete both inline plugins from the site's `vite.config.ts`. Verify the
-production build still succeeds (`vite build` in the site repo).
+Delete both inline plugins from the site's `vite.config.ts`. Since
+`@decocms/start >= 2.19.0`, `deco-post-cleanup --fix` does this for
+you — it walks the AST with brace-balanced parsing (template literals
+and nested `{}` inside `config()`/`load()` bodies don't trip it up),
+removes the literal **plus its trailing comma + attached `// ...`
+comment block**, and is idempotent (rerunning is a no-op). Block
+comments are left alone. Verify the production build still succeeds
+(`vite build` in the site repo).
 
 ## 3. Drop the `runtime.ts` `invoke` shim
 

package/MIGRATION_TOOLING_PLAN.md

@@ -688,27 +688,83 @@ Releases shipped from Wave 6:
 - `@decocms/apps@1.7.0` — adds `vtex/hooks/createUseCart` factory
 - `@decocms/start@2.8.0` (compile phase) → `2.9.0` (template shim) → `2.10.0` (per-site config)
 
-### Wave 12 (kicked off 2026-05-01 after D1–D5 sign-off) — Priority 1 (framework + commerce)
+### Wave 12 (kicked off 2026-05-01 after D1–D5 sign-off) — Priority 1 (framework + commerce) — ✅ **COMPLETE**
 
 After surfacing als-storefront as the third migration target (heavy on
 htmx, ~120 hx-* files, prior als-tanstack attempt thrown away), the
-"wait for 3rd site" deferrals collapse. Wave 12 ships the abstractions
-that als + casaevideo + baggagio have already justified, plus the
-audit `--fix` work D3 forces us into.
-
-**Planned PRs (will be filled in as they ship):**
-
-- **W12-A** apps-start: `createUseUser` factory (mirrors `createUseCart` from #32)
-- **W12-B** apps-start: `createUseWishlist` factory (same pattern)
-- **W12-C** deco-start: throwing stubs in `lib-utils.ts` template + per-stub message linking to skill (D3 implementation)
-- **W12-D** deco-start: audit `--fix` for `toProduct` swap (uses #121's `meta.fixHints`)
-- **W12-E** deco-start: audit `--fix` for `withSegmentCookie` swap
-- **W12-F** deco-start: audit `--fix` for `obsolete-vite-plugins` rule (mechanical cleanup)
-- **W12-G** apps-start (or deco-start CLAUDE.md cross-link): per-repo pointer to `migration-tooling-policy.mdc` so the constitutional rule is discoverable from any consumer repo
-- **W12-H** deco-start: cleanup phase scaffolds `.cursor/rules/migration-policy-pointer.mdc` in target site, pointing at the canonical rule (D1/D4 enforcement at site level)
-
-Wave 12 ships in priority-1 order; Wave 13 only starts when the
-foundation is in place.
+"wait for 3rd site" deferrals collapse. Wave 12 shipped the abstractions
+that als + casaevideo + baggagio had already justified, plus the
+audit `--fix` work D3 forces us into. **9 PRs across `deco-start` and
+`apps-start`, all merged.**
+
+**Shipped PRs:**
+
+- **W12-A + W12-B** [`apps-start#33`](https://github.com/decocms/apps-start/pull/33) — `feat(vtex/hooks): add createUseUser + createUseWishlist factories` ✅ **MERGED**.
+  Mirrors the `createUseCart` shape: invoke-driven legacy state machine, signal-shaped public API (`.value`), independent instances per call. `createUseWishlist` also exposes the `legacyAddArgsToCanonical` and `findWishlistEntry` helpers so site code can keep its old `productId`/`productGroupId` swap convention while routing through the canonical `vtex.actions.{addToWishlist, removeFromWishlist}` signature. New unit tests assert factory shape, instance independence, the arg-swap convention, and the entry-finder helper.
+- **(Lint unblock)** [`apps-start#34`](https://github.com/decocms/apps-start/pull/34) — `chore(lint): tighten shopify storefront.graphql.gen.ts types + biome formatting` ✅ **MERGED**.
+  Cleared pre-existing `noExplicitAny` failures in `shopify/utils/storefront/storefront.graphql.gen.ts` plus formatting drift in `vtex/__tests__/client-segment-cookie.test.ts` so subsequent Wave 12 PRs in `apps-start` could land on a green CI baseline. Replaced loose `any` types with a structured `ProductFilter` shape (derived from real consumers) and `unknown` elsewhere; ran `biome check --write` to fix import order + formatting.
+- **W12-C** [`deco-start#123`](https://github.com/decocms/deco-start/pull/123) — `feat(migrate): D3 — generated stubs throw at runtime` ✅ **MERGED**, released as `@decocms/start@2.16.0`.
+  Implements **D3** verbatim. The migration-time stubs in `lib-utils.ts` for `toProduct`, `getISCookiesFromBag`, `getSegmentFromBag`, `withSegmentCookie` no longer return identity-cast values, empty objects, or empty `Headers` — they now `throw new Error(STUB_MSG)` with a per-symbol message that names the canonical replacement, the canonical signature, and the `deco-post-cleanup --fix` invocation. Tests assert the throwing bodies + that other functional helpers (e.g. `parseCookie`, `isFilterParam`) are untouched.
+- **W12-D + W12-E** [`deco-start#124`](https://github.com/decocms/deco-start/pull/124) — `feat(audit): vtex-shim-regression --fix for swap-able symbols` ✅ **MERGED**, released as `@decocms/start@2.17.0`.
+  Auto-fixes the swap subset of the regression rule: when every imported symbol from a `~/lib/vtex-*` shim has a `kind: "swap"` hint pointing to the same canonical module, the rule rewrites the `from "..."` clause to canonical and leaves the named-import list (including `as`-aliases) verbatim. Mixed swap + refactor surfaces, and shims that mix stubs with real impls (e.g. `isFilterParam`), are deliberately left for manual fix. 6 new tests + skill doc § 5 update.
+- **W12-i** [`deco-start#125`](https://github.com/decocms/deco-start/pull/125) — `feat(migrate): scaffold useUser + useWishlist as factory shims (vtex)` ✅ **MERGED**.
+  Updates the migration script's `hooks.ts` template so freshly migrated VTEX sites get 3-line factory shims (`export const { useUser, resetUser } = createUseUser({ invoke })`) instead of 200-LOC singletons that were copy-pasted by the old migration. Non-VTEX sites still get the legacy stubs but with docstrings pointing at the factories for parity context. 4 new tests cover both branches and a line-count budget.
+- **W12-F** [`deco-start#127`](https://github.com/decocms/deco-start/pull/127) — `feat(audit): obsolete-vite-plugins --fix` ✅ **MERGED**.
+  JS-aware applyFix for the rule. Walks `vite.config.ts` with a brace-counter that skips strings, template literals (including `${...}` interpolation), and line/block comments, so nested `{}` inside `config()` / `load()` / `resolveId()` bodies do not throw off boundary detection. Removes the inline literal + trailing `,\n` + the contiguous block of `// ...` comments immediately attached above. Idempotent. 7 new tests + smoke verified against real casaevideo `vite.config.ts` (162 LOC → both plugins gone, 2503 bytes / ~74 LOC removed, structurally identical to baggagio's already-clean shape, post-fix audit returns 0 findings).
+- **W12-G** [`apps-start#35`](https://github.com/decocms/apps-start/pull/35) — `docs: add AGENTS.md cross-linking the canonical migration policy` ✅ **MERGED**.
+  Adds an AGENTS.md to `apps-start` so any agent or contributor opening that repo knows the canonical migration policy lives in `decocms/deco-start` and what D1–D5 mean specifically inside `apps-start` (especially D4: site-local apps live in the *site*, not in `apps-start`). Architecture overview + cross-link table.
+- **W12-H** [`deco-start#126`](https://github.com/decocms/deco-start/pull/126) — `feat(migrate): scaffold migration-tooling-policy pointer rule` ✅ **MERGED**, released as `@decocms/start@2.18.0`.
+  Migration scaffold phase now writes `.cursor/rules/migration-tooling-policy.mdc` into every newly migrated site. The pointer is `alwaysApply: true`, links to the canonical rule and plan in `decocms/deco-start`, includes a one-line-per-decision D1–D5 table scoped to the site, and points at the `deco-post-cleanup --fix` / `--strict` commands. Length budget under 3 KB so it stays a pointer, not a copy. 8 new tests.
+
+Wave 12 ships in priority-1 order; Wave 13 starts now.
+
+### Wave 12 — discoveries
+
+- **D3 + audit `--fix` is a closed loop, not an either/or.** The
+  symmetry that `--fix` for swap-able stubs (W12-D/E) combined with
+  throwing stubs (W12-C) produces is significant: the moment a
+  migrated site runs anything that hits a stub'd symbol, it throws
+  with an actionable error pointing at the canonical replacement; the
+  same moment, `--fix` knows what `from "..."` clause to rewrite. The
+  user no longer has a "silent regression" failure mode.
+- **Per-symbol fix-hint table now has 5 consumers.** It's read by:
+  the rule's prose `fix:` field, the rule's `meta.fixHints`
+  structured payload, the runtime stub error message, the `--fix`
+  rewriter (selects swap candidates), and the skill doc table. Adding
+  a 5th, 6th, Nth stub means appending one entry to `STUB_FIX_HINTS`
+  — every consumer picks up the new symbol for free.
+- **Site-level policy enforcement at scaffold time, not runtime.**
+  W12-H ships the canonical D1–D5 policy *as a pointer* into every
+  new site. Cursor sessions in those sites load the rule with
+  `alwaysApply: true`, so they know the policy without us having to
+  pull a copy of the rule into each repo. Drift-free by construction
+  — the canonical rule changes upstream and the pointer keeps
+  pointing.
+- **Brace-balanced parsing + comment attachment makes
+  `obsolete-vite-plugins` `--fix` safe at scale.** The casaevideo
+  smoke test confirmed the approach handles real-world vite configs
+  with multi-line plugins, attached comments describing the
+  workaround, template literals containing `}`, and nested
+  `rollupOptions`. Idempotency falls out of "rule found 0 plugins
+  → no findings → no fix actions". This is the pattern for any
+  future `--fix` that needs to surgically edit a file: extract a
+  span helper, write surface-level tests, smoke against a real
+  production file, ship.
+- **`apps-start` had latent CI debt.** W12 surfaced pre-existing
+  `noExplicitAny` failures in `shopify/utils/storefront/storefront.graphql.gen.ts`
+  that had been failing on `main` for an unknown duration. The lint
+  unblock PR (`apps-start#34`) is the kind of "passing through" fix
+  that should land first whenever a CI gate is red. Don't paper
+  over it.
+- **Factories migrate cleaner than templates.** Comparing
+  `apps-start#33` (factories) to `deco-start#125` (template that
+  *consumes* the factories), the factory PR is the larger artifact
+  but the template PR shipped 4 lines into each generated file.
+  Investing once in a well-shaped factory pays a 50:1 multiplier on
+  every site that runs the migration after that point. This is the
+  D4 promotion path working end-to-end: build it once at site level,
+  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
 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@decocms/start",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
   "bin": {
     "deco-migrate": "./scripts/migrate.ts",
-    "deco-post-cleanup": "./scripts/migrate-post-cleanup.ts"
+    "deco-post-cleanup": "./scripts/migrate-post-cleanup.ts",
+    "deco-htmx-analyze": "./scripts/htmx-analyze.ts"
   },
   "exports": {
     ".": "./src/index.ts",

package/scripts/htmx-analyze.ts

@@ -0,0 +1,226 @@
+#!/usr/bin/env tsx
+/**
+ * HTMX surface analyzer — CLI entry point.
+ *
+ * Inventories the `hx-*` surface of a Deco storefront so the engineer
+ * (or the next codemod wave) knows exactly what shapes are out there
+ * before starting the rewrite to React. Per D2 in the migration
+ * tooling policy, all htmx is rewritten on migration; no runtime is
+ * shipped in `@decocms/start`.
+ *
+ * Usage (from a site directory):
+ *   npx -p @decocms/start deco-htmx-analyze
+ *   npx -p @decocms/start deco-htmx-analyze --source /path/to/site
+ *   npx -p @decocms/start deco-htmx-analyze --json
+ *
+ * Options:
+ *   --source <dir>   Site directory to analyze (default: current directory)
+ *   --json           Emit machine-readable JSON instead of pretty text
+ *   --top <n>        Show top N files by occurrence count (default: 20)
+ *   --help, -h       Show this help
+ *
+ * Wave 13-A. Read-only. Codemods land in Wave 14.
+ */
+
+import * as path from "node:path";
+import { realFsAdapter } from "./migrate/post-cleanup/runner";
+import {
+	analyzeHtmx,
+	type HtmxCategory,
+	type HtmxInventory,
+} from "./migrate/analyzers/htmx-analyze";
+import { banner, bold, cyan, gray, green, red, yellow } from "./migrate/colors";
+
+interface CliOpts {
+	source: string;
+	json: boolean;
+	top: number;
+	help: boolean;
+}
+
+function parseArgs(args: string[]): CliOpts {
+	let source = ".";
+	let json = false;
+	let top = 20;
+	let help = false;
+	for (let i = 0; i < args.length; i++) {
+		switch (args[i]) {
+			case "--source":
+				source = args[++i];
+				break;
+			case "--json":
+				json = true;
+				break;
+			case "--top":
+				top = Number.parseInt(args[++i] ?? "20", 10);
+				if (Number.isNaN(top) || top < 0) top = 20;
+				break;
+			case "--help":
+			case "-h":
+				help = true;
+				break;
+			default:
+				console.error(`Unknown argument: ${args[i]}`);
+				process.exit(1);
+		}
+	}
+	return { source, json, top, help };
+}
+
+function printHelp(): void {
+	console.log(`deco-htmx-analyze
+
+Inventory the htmx surface (hx-* attributes) of a Deco storefront.
+
+Usage:
+  npx -p @decocms/start deco-htmx-analyze [options]
+
+Options:
+  --source <dir>   Site directory to analyze (default: cwd)
+  --json           Emit machine-readable JSON
+  --top <n>        Top N files by occurrence count (default: 20)
+  --help, -h       Show this help
+
+The output is read-only. Codemods that rewrite htmx to React are a
+planned follow-up — see the deco-to-tanstack-migration skill for the
+per-pattern rewrite recipes.
+`);
+}
+
+const CATEGORY_DESCRIPTIONS: Record<HtmxCategory, string> = {
+	"event-handler": "hx-on:* with no fetch attr — pure client-side handler",
+	"form-swap": "hx-post on a <form> with hx-target/hx-swap",
+	"click-swap": "hx-get/hx-post on a button with hx-target",
+	"auto-fetch": "hx-trigger=keyup/intersect/etc on input or auto-fired element",
+	"oob-swap": "hx-swap-oob / hx-select-oob — out-of-band patches",
+	boost: "hx-boost=true — link prefetch, already-SPA in TanStack Start",
+	unmatched: "hx-* attribute set that didn't match a known pattern",
+};
+
+const CATEGORY_RECIPES: Record<HtmxCategory, string> = {
+	"event-handler":
+		"replace hx-on:click={useScript(...)} with onClick={() => { ... }}",
+	"form-swap":
+		"<form onSubmit> + useMutation/server function; render result with state",
+	"click-swap":
+		"setState/setView + conditional render, or sub-route via TanStack Router",
+	"auto-fetch":
+		"debounced state + useQuery; for intersect use IntersectionObserver",
+	"oob-swap":
+		"manual: out-of-band has no 1:1; refactor to broadcast event + listener",
+	boost: "replace <a hx-boost> with TanStack Router <Link> (already SPA)",
+	unmatched: "manual review",
+};
+
+const CATEGORY_ORDER: HtmxCategory[] = [
+	"event-handler",
+	"click-swap",
+	"form-swap",
+	"auto-fetch",
+	"boost",
+	"oob-swap",
+	"unmatched",
+];
+
+function printText(inv: HtmxInventory, top: number): void {
+	banner("HTMX surface analysis");
+
+	if (inv.totalOccurrences === 0) {
+		console.log(green("✓ No hx-* attributes found.\n"));
+		return;
+	}
+
+	console.log(`${bold("Files with hx-* usage:")} ${inv.totalFiles}`);
+	console.log(`${bold("Total occurrences:")}    ${inv.totalOccurrences}\n`);
+
+	console.log(bold("By category:"));
+	for (const cat of CATEGORY_ORDER) {
+		const count = inv.byCategory[cat];
+		if (count === 0) continue;
+		const label = `${cat.padEnd(15)}`;
+		const desc = gray(CATEGORY_DESCRIPTIONS[cat]);
+		console.log(`  ${cyan(label)} ${String(count).padStart(4)}  ${desc}`);
+	}
+
+	console.log(`\n${bold("Migration recipes:")}`);
+	for (const cat of CATEGORY_ORDER) {
+		if (inv.byCategory[cat] === 0) continue;
+		console.log(`  ${cyan(cat.padEnd(15))} ${gray(CATEGORY_RECIPES[cat])}`);
+	}
+
+	console.log(`\n${bold(`Top ${top} files by occurrence:`)}`);
+	const slice = inv.files.slice(0, top);
+	const widest = Math.max(...slice.map((f) => f.file.length), 30);
+	for (const f of slice) {
+		const detail = CATEGORY_ORDER.filter((c) => f.byCategory[c] > 0)
+			.map((c) => `${c}=${f.byCategory[c]}`)
+			.join(", ");
+		console.log(
+			`  ${f.file.padEnd(widest)}  ${String(f.total).padStart(3)}  ${gray(detail)}`,
+		);
+	}
+
+	if (inv.files.length > top) {
+		console.log(gray(`  …and ${inv.files.length - top} more file(s)`));
+	}
+
+	console.log(`\n${bold("Sample call sites:")}`);
+	for (const cat of CATEGORY_ORDER) {
+		const samples = inv.samples[cat];
+		if (samples.length === 0) continue;
+		console.log(`  ${cyan(cat)}`);
+		for (const s of samples) {
+			const attrs = s.attrs.join(", ");
+			console.log(
+				`    ${gray(`${s.file}:${s.line}`)} <${s.tag}> [${attrs}]`,
+			);
+		}
+	}
+
+	const hasOob = inv.byCategory["oob-swap"] > 0;
+	const hasUnmatched = inv.byCategory.unmatched > 0;
+	if (hasOob || hasUnmatched) {
+		console.log();
+		if (hasOob) {
+			console.log(
+				yellow(
+					"⚠ oob-swap occurrences require manual rewrite — no 1:1 React equivalent.",
+				),
+			);
+		}
+		if (hasUnmatched) {
+			console.log(
+				yellow(
+					"⚠ unmatched occurrences require manual review — see Sample call sites.",
+				),
+			);
+		}
+	}
+	console.log();
+}
+
+function main(argv: string[]): number {
+	const opts = parseArgs(argv);
+	if (opts.help) {
+		printHelp();
+		return 0;
+	}
+
+	const sourceDir = path.resolve(opts.source);
+	const inv = analyzeHtmx(sourceDir, realFsAdapter);
+
+	if (opts.json) {
+		console.log(JSON.stringify(inv, null, 2));
+	} else {
+		printText(inv, opts.top);
+	}
+	return 0;
+}
+
+try {
+	process.exit(main(process.argv.slice(2)));
+} catch (err) {
+	console.error(red(`✗ deco-htmx-analyze failed: ${(err as Error).message}`));
+	if (process.env.DEBUG) console.error((err as Error).stack);
+	process.exit(1);
+}

package/scripts/migrate/analyzers/htmx-analyze.test.ts

@@ -0,0 +1,372 @@
+import { describe, expect, it } from "vitest";
+import {
+	analyzeFile,
+	analyzeHtmx,
+	classify,
+	type HtmxCategory,
+} from "./htmx-analyze";
+import type { FsAdapter } from "../post-cleanup/types";
+
+/**
+ * In-memory FsAdapter mirroring the post-cleanup tests' helper. Kept
+ * local to this test file to avoid coupling — the analyzer's adapter
+ * surface is a strict subset of the audit's.
+ */
+function makeFs(files: Record<string, string>): FsAdapter {
+	const norm = Object.fromEntries(
+		Object.entries(files).map(([k, v]) => [k.replace(/\\/g, "/"), v]),
+	);
+	return {
+		exists(absPath) {
+			return absPath.replace(/\\/g, "/") in norm;
+		},
+		readText(absPath) {
+			const k = absPath.replace(/\\/g, "/");
+			if (!(k in norm)) throw new Error(`ENOENT: ${absPath}`);
+			return norm[k];
+		},
+		glob(siteDir, pattern, excludeDirs = []) {
+			const root = siteDir.replace(/\\/g, "/");
+			const all = Object.keys(norm).filter((p) => p.startsWith(`${root}/`));
+			const filtered = all.filter((p) => {
+				const rel = p.slice(root.length + 1);
+				return !excludeDirs.some((dir) => rel.startsWith(`${dir}/`));
+			});
+			const branches = pattern.includes("{")
+				? pattern
+						.match(/\{([^{}]+)\}/)![1]
+						.split(",")
+						.map((b) => pattern.replace(/\{[^{}]+\}/, b.trim()))
+				: [pattern];
+			const regexes = branches.map((p) => {
+				const re = p
+					.replace(/[.+^$()|]/g, "\\$&")
+					.replace(/\*\*\//g, "<<DBL>>")
+					.replace(/\*\*/g, "<<DBL>>")
+					.replace(/\*/g, "[^/]*")
+					.replace(/<<DBL>>/g, "(?:.*/)?");
+				return new RegExp(`^${re}$`);
+			});
+			return filtered
+				.filter((p) => {
+					const rel = p.slice(root.length + 1);
+					return regexes.some((re) => re.test(rel));
+				})
+				.sort();
+		},
+	};
+}
+
+const SITE = "/site";
+
+/* ------------------------------------------------------------------ */
+/* classify() — pure unit tests                                        */
+/* ------------------------------------------------------------------ */
+
+describe("classify (pure)", () => {
+	it("classifies hx-boost as boost regardless of other attrs", () => {
+		expect(classify("a", ["hx-boost", "hx-target"])).toBe("boost");
+	});
+
+	it("classifies hx-swap-oob / hx-select-oob as oob-swap", () => {
+		expect(classify("div", ["hx-swap-oob"])).toBe("oob-swap");
+		expect(classify("div", ["hx-select-oob"])).toBe("oob-swap");
+	});
+
+	it("classifies a form with hx-post + hx-target + hx-swap as form-swap", () => {
+		expect(classify("form", ["hx-post", "hx-swap", "hx-target"])).toBe(
+			"form-swap",
+		);
+	});
+
+	it("classifies a button with hx-get + hx-target as click-swap", () => {
+		expect(classify("button", ["hx-get", "hx-target", "hx-swap"])).toBe(
+			"click-swap",
+		);
+	});
+
+	it("classifies an input with hx-post + hx-trigger as auto-fetch", () => {
+		expect(
+			classify("input", ["hx-post", "hx-target", "hx-trigger", "hx-swap"]),
+		).toBe("auto-fetch");
+	});
+
+	it("classifies a button with only hx-on:click as event-handler", () => {
+		expect(classify("button", ["hx-on:click"])).toBe("event-handler");
+	});
+
+	it("classifies hx-on-click (dash variant, htmx 2.x) as event-handler", () => {
+		// HTML spec doesn't allow `:` in attribute names; htmx 2.x
+		// canonicalised the dash form. We must recognise both.
+		expect(classify("button", ["hx-on-click"])).toBe("event-handler");
+		expect(classify("Accordion.Trigger", ["hx-on-click"])).toBe(
+			"event-handler",
+		);
+		// htmx-specific bare events e.g. `hx-on-htmx-config-request` —
+		// when paired with a fetch they fold into click-swap (fetch
+		// wins); standalone they are still event-handler shape.
+		expect(classify("div", ["hx-on-htmx-after-request"])).toBe(
+			"event-handler",
+		);
+	});
+
+	it("classifies a div with only hx-trigger and no fetch attr as unmatched", () => {
+		// hx-trigger alone is meaningless; flag for manual review.
+		expect(classify("div", ["hx-trigger"])).toBe("unmatched");
+	});
+
+	it("treats hx-on with a fetch attr as click-swap (the fetch wins)", () => {
+		// Real example from als (EmailAndPassword button): hx-get +
+		// hx-target + hx-trigger=click — engineer often piles
+		// hx-on alongside, but the dominant migration path is the
+		// click-swap recipe.
+		expect(
+			classify("button", ["hx-get", "hx-on:click", "hx-target", "hx-trigger"]),
+		).toBe("click-swap");
+	});
+});
+
+/* ------------------------------------------------------------------ */
+/* analyzeFile() — JSX walker tests using real als-shaped fixtures     */
+/* ------------------------------------------------------------------ */
+
+describe("analyzeFile (real shapes)", () => {
+	it("detects hx-on:click={useScript(...)} click handler (als AddToBagButton shape)", () => {
+		const file = `
+import { useScript } from "@deco/deco/hooks";
+export default function AddToBagButton() {
+  return (
+    <button
+      hx-on:click={useScript(async (skuId, sellerId) => {
+        if (!skuId || !sellerId) return;
+        const button = this as HTMLButtonElement;
+        button.dataset.loading = "true";
+        await globalThis.window.STOREFRONT.CART.addToCart({ orderItems: [{ id: skuId, quantity: 1 }] });
+      }, "sku", "1")}
+      class="add-to-bag"
+    >
+      Add to bag
+    </button>
+  );
+}
+`;
+		const out = analyzeFile("AddToBagButton.tsx", file);
+		expect(out).toHaveLength(1);
+		expect(out[0].category).toBe("event-handler");
+		expect(out[0].tag).toBe("button");
+		expect(out[0].attrs).toEqual(["hx-on:click"]);
+	});
+
+	it("detects hx-post + hx-target + hx-trigger=keyup on an input as auto-fetch (als SearchInput shape)", () => {
+		const file = `
+<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-on:change={useScript(() => { /* analytics */ }, searchInputId)}
+  hx-trigger="keyup changed delay:200ms"
+  class="…"
+/>
+`;
+		const out = analyzeFile("SearchInput.tsx", file);
+		expect(out).toHaveLength(1);
+		expect(out[0].category).toBe("auto-fetch");
+		expect(out[0].tag).toBe("input");
+		expect(out[0].attrs).toContain("hx-post");
+		expect(out[0].attrs).toContain("hx-trigger");
+		expect(out[0].attrs).toContain("hx-target");
+	});
+
+	it("detects hx-post + hx-target + hx-swap on a form as form-swap (als EmailAndPassword shape)", () => {
+		const file = `
+<form
+  class="flex flex-col w-full"
+  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 } } })}
+  hx-indicator=".submit"
+>
+  <fieldset>…</fieldset>
+</form>
+`;
+		const out = analyzeFile("EmailAndPassword.tsx", file);
+		expect(out).toHaveLength(1);
+		expect(out[0].category).toBe("form-swap");
+		expect(out[0].tag).toBe("form");
+		expect(out[0].attrs).toContain("hx-post");
+		expect(out[0].attrs).toContain("hx-target");
+	});
+
+	it("detects hx-get on a button as click-swap (als ForgotPassword shape)", () => {
+		const file = `
+<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 } } })}
+  hx-indicator="this"
+>
+  Forgot password
+</button>
+`;
+		const out = analyzeFile("ForgotPassword.tsx", file);
+		expect(out).toHaveLength(1);
+		expect(out[0].category).toBe("click-swap");
+		expect(out[0].tag).toBe("button");
+		expect(out[0].attrs).toContain("hx-get");
+	});
+
+	it("counts each element exactly once even when multiple hx-* attrs match", () => {
+		// 4 hx-* attributes on the same form — should produce ONE
+		// occurrence, not four.
+		const file = `
+<form hx-post="/x" hx-target="#a" hx-swap="innerHTML" hx-trigger="submit">
+  <input />
+</form>
+`;
+		const out = analyzeFile("F.tsx", file);
+		expect(out).toHaveLength(1);
+	});
+
+	it("detects multiple distinct elements in the same file", () => {
+		const file = `
+<>
+  <button hx-on:click={() => {}}>A</button>
+  <form hx-post="/x" hx-target="#r" hx-swap="innerHTML">
+    <input name="q" />
+  </form>
+  <a hx-boost="true" href="/p">P</a>
+</>
+`;
+		const out = analyzeFile("Multi.tsx", file);
+		expect(out).toHaveLength(3);
+		const cats = out.map((o) => o.category).sort();
+		expect(cats).toEqual(["boost", "event-handler", "form-swap"]);
+	});
+
+	it("does not miscount braces inside template literals or attribute expressions", () => {
+		const file = `
+<button
+  hx-target={\`#\${id}\`}
+  hx-get={useSection({ props: { x: { y: 1 } } })}
+>
+  go
+</button>
+`;
+		const out = analyzeFile("Tricky.tsx", file);
+		expect(out).toHaveLength(1);
+		expect(out[0].category).toBe("click-swap");
+	});
+
+	it("returns an empty array when no hx-* attributes are present", () => {
+		const file = `
+<button onClick={() => {}}>plain react</button>
+`;
+		expect(analyzeFile("React.tsx", file)).toEqual([]);
+	});
+
+	it("captures the tag name of components, not just intrinsic tags", () => {
+		const file = `
+<MyComponent hx-on:click={() => {}}>x</MyComponent>
+`;
+		const out = analyzeFile("C.tsx", file);
+		expect(out).toHaveLength(1);
+		expect(out[0].tag).toBe("MyComponent");
+	});
+
+	it("reports a 1-indexed line number for the opening tag", () => {
+		const file = "// header\n// line 2\n<button hx-on:click={() => {}}>x</button>\n";
+		const out = analyzeFile("L.tsx", file);
+		expect(out[0].line).toBe(3);
+	});
+});
+
+/* ------------------------------------------------------------------ */
+/* analyzeHtmx() — full inventory tests                                */
+/* ------------------------------------------------------------------ */
+
+describe("analyzeHtmx (inventory)", () => {
+	it("aggregates counts across files and produces samples", () => {
+		const fs = makeFs({
+			"/site/components/A.tsx":
+				'<button hx-on:click={() => {}}>a1</button>\n' +
+				'<button hx-on:click={() => {}}>a2</button>\n',
+			"/site/components/B.tsx":
+				'<form hx-post="/x" hx-target="#r" hx-swap="innerHTML"><input/></form>\n',
+			"/site/components/C.tsx":
+				'<a hx-boost="true" href="/p">p</a>\n',
+			"/site/Plain.ts": "export const x = 1;\n",
+		});
+		const inv = analyzeHtmx(SITE, fs);
+		expect(inv.totalFiles).toBe(3);
+		expect(inv.totalOccurrences).toBe(4);
+		expect(inv.byCategory["event-handler"]).toBe(2);
+		expect(inv.byCategory["form-swap"]).toBe(1);
+		expect(inv.byCategory.boost).toBe(1);
+		expect(inv.samples["event-handler"]).toHaveLength(2);
+		expect(inv.samples["form-swap"]).toHaveLength(1);
+		expect(inv.samples.boost).toHaveLength(1);
+	});
+
+	it("orders files by total descending so the biggest offenders come first", () => {
+		const fs = makeFs({
+			"/site/Small.tsx": '<button hx-on:click={() => {}}>x</button>\n',
+			"/site/Big.tsx":
+				'<button hx-on:click={() => {}}>1</button>\n' +
+				'<button hx-on:click={() => {}}>2</button>\n' +
+				'<button hx-on:click={() => {}}>3</button>\n',
+			"/site/Mid.tsx":
+				'<button hx-on:click={() => {}}>a</button>\n' +
+				'<button hx-on:click={() => {}}>b</button>\n',
+		});
+		const inv = analyzeHtmx(SITE, fs);
+		expect(inv.files.map((f) => f.file)).toEqual([
+			"Big.tsx",
+			"Mid.tsx",
+			"Small.tsx",
+		]);
+	});
+
+	it("caps samples per category at 3 even when there are many occurrences", () => {
+		const lines = Array.from(
+			{ length: 10 },
+			(_, i) => `<button hx-on:click={() => {}}>x${i}</button>`,
+		).join("\n");
+		const fs = makeFs({ "/site/Many.tsx": lines });
+		const inv = analyzeHtmx(SITE, fs);
+		expect(inv.totalOccurrences).toBe(10);
+		expect(inv.samples["event-handler"]).toHaveLength(3);
+	});
+
+	it("excludes documentation directories from analysis", () => {
+		// `.cursor/` and `docs/` are common locations for htmx skill
+		// references / tutorials. They should not pollute the count.
+		const fs = makeFs({
+			"/site/components/Real.tsx":
+				'<button hx-on:click={() => {}}>x</button>\n',
+			"/site/.cursor/skills/htmx/example.tsx":
+				'<button hx-on:click={() => {}}>doc</button>\n',
+			"/site/docs/example.md": "irrelevant",
+		});
+		const inv = analyzeHtmx(SITE, fs);
+		expect(inv.totalOccurrences).toBe(1);
+		expect(inv.files.map((f) => f.file)).toEqual(["components/Real.tsx"]);
+	});
+
+	it("returns zero counts on a clean repo", () => {
+		const fs = makeFs({
+			"/site/A.tsx": '<button onClick={() => {}}>x</button>\n',
+		});
+		const inv = analyzeHtmx(SITE, fs);
+		expect(inv.totalOccurrences).toBe(0);
+		expect(inv.totalFiles).toBe(0);
+		const allCats = Object.values(inv.byCategory) as number[];
+		expect(allCats.every((c) => c === 0)).toBe(true);
+	});
+});

package/scripts/migrate/analyzers/htmx-analyze.ts

@@ -0,0 +1,425 @@
+/**
+ * HTMX surface analyzer.
+ *
+ * For sites with significant HTMX usage (the deco-cx Fresh stack
+ * embraced htmx as the interactivity model), the migration to TanStack
+ * Start has to either rewrite or eliminate every `hx-*` attribute.
+ * Per D2 in the migration tooling policy we don't ship a runtime —
+ * everything gets rewritten to React. This analyzer is the first step:
+ * it inventories the `hx-*` surface so the engineer (or the next
+ * codemod wave) knows exactly what shapes are out there before
+ * starting the rewrite.
+ *
+ * The output is a structured `HtmxInventory`: per-category counts,
+ * per-file counts, and three sample call sites per category. The
+ * report is the source of truth for the rewrite recipes documented
+ * in `references/htmx-rewrite.md` (Wave 13-B).
+ *
+ * Categorization is heuristic — we group elements by their **attribute
+ * cluster** rather than by individual attribute, because the rewrite
+ * recipe depends on the cluster (e.g. `hx-post + hx-target + hx-swap`
+ * on a `<form>` is a different rewrite than `hx-get + hx-target` on a
+ * `<button>`). False positives are recoverable: a human reads the
+ * report.
+ *
+ * Wave 13-A. Closes the analysis half of `htmx-foundations`; the
+ * codemods proper land in Wave 14.
+ */
+
+import type { FsAdapter } from "../post-cleanup/types";
+
+const SRC_GLOB_EXCLUDES = [
+	"node_modules",
+	"dist",
+	".wrangler",
+	".vite",
+	".tanstack",
+	"build",
+	".cursor",
+	".agents",
+	"docs",
+];
+
+/* ------------------------------------------------------------------ */
+/* Public types                                                        */
+/* ------------------------------------------------------------------ */
+
+export type HtmxCategory =
+	| "event-handler"
+	| "form-swap"
+	| "click-swap"
+	| "auto-fetch"
+	| "oob-swap"
+	| "boost"
+	| "unmatched";
+
+export interface HtmxOccurrence {
+	category: HtmxCategory;
+	file: string;
+	/** 1-indexed line of the opening tag's start. */
+	line: number;
+	/** Tag name (e.g. "button", "form", "input", "MyComponent"). */
+	tag: string;
+	/** Set of canonical hx-* attribute names found on this element. */
+	attrs: string[];
+}
+
+export interface HtmxFileSummary {
+	file: string;
+	total: number;
+	byCategory: Record<HtmxCategory, number>;
+}
+
+export interface HtmxInventory {
+	totalFiles: number;
+	totalOccurrences: number;
+	byCategory: Record<HtmxCategory, number>;
+	files: HtmxFileSummary[];
+	/** Up to 3 sample occurrences per category (ordered by file path). */
+	samples: Record<HtmxCategory, HtmxOccurrence[]>;
+}
+
+/* ------------------------------------------------------------------ */
+/* Entry point                                                         */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Analyze every `*.{ts,tsx}` file under `siteDir` and return a
+ * structured inventory of htmx usage. Pure over the injected
+ * `FsAdapter`, so callers (CLI, tests, migration phase wiring) can
+ * substitute in-memory file systems.
+ */
+export function analyzeHtmx(siteDir: string, fs: FsAdapter): HtmxInventory {
+	const files = fs.glob(siteDir, "**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
+	const occurrences: HtmxOccurrence[] = [];
+	const fileSummaries: HtmxFileSummary[] = [];
+
+	for (const abs of files) {
+		const rel = abs.startsWith(`${siteDir}/`)
+			? abs.slice(siteDir.length + 1)
+			: abs;
+		const content = fs.readText(abs);
+		const fileOccurrences = analyzeFile(rel, content);
+		if (fileOccurrences.length === 0) continue;
+		const summary: HtmxFileSummary = {
+			file: rel,
+			total: fileOccurrences.length,
+			byCategory: emptyCategoryRecord(),
+		};
+		for (const occ of fileOccurrences) {
+			summary.byCategory[occ.category]++;
+		}
+		fileSummaries.push(summary);
+		occurrences.push(...fileOccurrences);
+	}
+
+	const byCategory = emptyCategoryRecord();
+	for (const occ of occurrences) byCategory[occ.category]++;
+
+	const samples = emptyCategorySamples();
+	for (const occ of occurrences) {
+		const bucket = samples[occ.category];
+		if (bucket.length < 3) bucket.push(occ);
+	}
+
+	// Order files by total descending so the "biggest offenders" land
+	// at the top of the report — that's the order an engineer wants to
+	// chip away at the surface in.
+	fileSummaries.sort((a, b) => b.total - a.total || a.file.localeCompare(b.file));
+
+	return {
+		totalFiles: fileSummaries.length,
+		totalOccurrences: occurrences.length,
+		byCategory,
+		files: fileSummaries,
+		samples,
+	};
+}
+
+function emptyCategoryRecord(): Record<HtmxCategory, number> {
+	return {
+		"event-handler": 0,
+		"form-swap": 0,
+		"click-swap": 0,
+		"auto-fetch": 0,
+		"oob-swap": 0,
+		boost: 0,
+		unmatched: 0,
+	};
+}
+
+function emptyCategorySamples(): Record<HtmxCategory, HtmxOccurrence[]> {
+	return {
+		"event-handler": [],
+		"form-swap": [],
+		"click-swap": [],
+		"auto-fetch": [],
+		"oob-swap": [],
+		boost: [],
+		unmatched: [],
+	};
+}
+
+/* ------------------------------------------------------------------ */
+/* Per-file analysis                                                   */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Parse a single source file and extract one occurrence per JSX
+ * opening-tag that carries any `hx-*` attribute. Exported so tests
+ * can exercise the parser without needing an FsAdapter.
+ */
+export function analyzeFile(file: string, content: string): HtmxOccurrence[] {
+	const occurrences: HtmxOccurrence[] = [];
+	const seenTagStarts = new Set<number>();
+
+	// Anchored on the attribute name only (not the value), so JSX
+	// expression slots in the value (`hx-post={useSection({...})}`)
+	// don't trip the regex up.
+	const HX_ATTR_RE = /\bhx-([a-z]+(?:-[a-z]+)*(?::[A-Za-z]+)?)\b/g;
+
+	for (const m of content.matchAll(HX_ATTR_RE)) {
+		const attrIdx = m.index;
+		if (attrIdx === undefined) continue;
+		const tagOpen = findEnclosingTagOpen(content, attrIdx);
+		if (tagOpen < 0) continue;
+		if (seenTagStarts.has(tagOpen)) continue;
+		const tagClose = findOpeningTagClose(content, tagOpen);
+		if (tagClose < 0) continue;
+		seenTagStarts.add(tagOpen);
+
+		const tagSpan = content.slice(tagOpen, tagClose + 1);
+		const tag = extractTagName(tagSpan);
+		const attrs = collectHxAttrs(tagSpan);
+		const line = lineNumberAt(content, tagOpen);
+		const category = classify(tag, attrs);
+
+		occurrences.push({
+			category,
+			file,
+			line,
+			tag,
+			attrs,
+		});
+	}
+
+	return occurrences;
+}
+
+/**
+ * Walk backwards from `attrIdx` to the most recent `<` that starts an
+ * opening tag (`<TagName`). Returns the index of that `<`, or -1 if
+ * no plausible tag start is found before the start of the file.
+ *
+ * "Plausible tag start" = `<` followed by a letter or `_`, where the
+ * `<` is not part of a `</` (closing tag), `<<` (operator), or
+ * preceded by an operand that would make it a comparison.
+ */
+function findEnclosingTagOpen(content: string, attrIdx: number): number {
+	for (let i = attrIdx - 1; i >= 0; i--) {
+		if (content[i] !== "<") continue;
+		// Closing tag — `</foo>` — wouldn't carry attributes.
+		if (content[i + 1] === "/") continue;
+		// Comparison / shift operator — left side is a non-tag char.
+		const next = content[i + 1];
+		if (!/[A-Za-z_]/.test(next ?? "")) continue;
+		// Be slightly defensive: if the character right before `<` is a
+		// closing-paren or another `>`, we're definitely in JSX. If it's
+		// an alpha char or `]`, this could be `a < b` — but `a < b` is
+		// followed by an *expression*, not a tag-name + space + `hx-…`,
+		// so the regex hit at attrIdx would be far away. Don't bother
+		// disambiguating; just return the candidate.
+		return i;
+	}
+	return -1;
+}
+
+/**
+ * From the `<` at `tagOpen`, walk forward to find the index of the
+ * `>` that closes the *opening tag* (not the close tag of the same
+ * element). Skips strings (single-, double-, backtick-quoted) and
+ * tracks balanced `{...}` expression slots so JSX expressions in
+ * attributes (`hx-post={useSection({...})}`) don't mislead us.
+ */
+function findOpeningTagClose(content: string, tagOpen: number): number {
+	let i = tagOpen + 1;
+	const n = content.length;
+	while (i < n) {
+		const ch = content[i];
+		if (ch === '"' || ch === "'") {
+			i = skipStringQuote(content, i, ch);
+			continue;
+		}
+		if (ch === "`") {
+			i = skipTemplateLiteral(content, i);
+			continue;
+		}
+		if (ch === "{") {
+			i = skipBraceBalanced(content, i);
+			continue;
+		}
+		if (ch === "/" && content[i + 1] === ">") return i + 1;
+		if (ch === ">") return i;
+		i++;
+	}
+	return -1;
+}
+
+function skipStringQuote(content: string, start: number, quote: string): number {
+	let i = start + 1;
+	const n = content.length;
+	while (i < n) {
+		if (content[i] === "\\") {
+			i += 2;
+			continue;
+		}
+		if (content[i] === quote) return i + 1;
+		i++;
+	}
+	return n;
+}
+
+function skipTemplateLiteral(content: string, start: number): number {
+	let i = start + 1;
+	const n = content.length;
+	while (i < n) {
+		if (content[i] === "\\") {
+			i += 2;
+			continue;
+		}
+		if (content[i] === "`") return i + 1;
+		if (content[i] === "$" && content[i + 1] === "{") {
+			i = skipBraceBalanced(content, i + 1);
+			continue;
+		}
+		i++;
+	}
+	return n;
+}
+
+function skipBraceBalanced(content: string, openIdx: number): number {
+	let i = openIdx + 1;
+	let depth = 1;
+	const n = content.length;
+	while (i < n && depth > 0) {
+		const ch = content[i];
+		if (ch === '"' || ch === "'") {
+			i = skipStringQuote(content, i, ch);
+			continue;
+		}
+		if (ch === "`") {
+			i = skipTemplateLiteral(content, i);
+			continue;
+		}
+		if (ch === "{") {
+			depth++;
+			i++;
+			continue;
+		}
+		if (ch === "}") {
+			depth--;
+			i++;
+			continue;
+		}
+		i++;
+	}
+	return i;
+}
+
+function extractTagName(tagSpan: string): string {
+	// tagSpan starts with `<`. The tag name is /[A-Za-z_][\w.-]*/ until
+	// whitespace, `/`, or `>`.
+	const m = /^<([A-Za-z_][\w.-]*)/.exec(tagSpan);
+	return m?.[1] ?? "";
+}
+
+function collectHxAttrs(tagSpan: string): string[] {
+	// Strip JSX expression slots so `hx-post={someFn({hx-thing: 1})}`
+	// — which doesn't actually exist in JSX, but defensive — doesn't
+	// inflate attr counts. We match the same name shape as the entry
+	// regex.
+	const seen = new Set<string>();
+	const re = /\bhx-([a-z]+(?:-[a-z]+)*(?::[A-Za-z]+)?)\b/g;
+	for (const m of tagSpan.matchAll(re)) {
+		seen.add(`hx-${m[1]}`);
+	}
+	return [...seen].sort();
+}
+
+function lineNumberAt(content: string, idx: number): number {
+	let line = 1;
+	for (let i = 0; i < idx && i < content.length; i++) {
+		if (content[i] === "\n") line++;
+	}
+	return line;
+}
+
+/* ------------------------------------------------------------------ */
+/* Classification                                                      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Bucket an element with attribute set `attrs` into one of the
+ * `HtmxCategory` values. Order is intentional: the more specific
+ * shapes are checked first.
+ *
+ * - **boost**: `hx-boost="true"` is a top-level switch — handled
+ *   first so it doesn't conflate with click-swap/form-swap shapes.
+ * - **oob-swap**: `hx-swap-oob` / `hx-select-oob` is a structural
+ *   pattern that almost never has a clean React equivalent.
+ * - **auto-fetch**: a fetch attribute paired with a `hx-trigger` that
+ *   isn't user-driven (`keyup`, `intersect`, `revealed`, `load`,
+ *   `every:`).
+ * - **form-swap**: `hx-post` (with or without `hx-target`/`hx-swap`)
+ *   on a `<form>`, OR with an explicit `hx-trigger="submit"`.
+ * - **click-swap**: `hx-get` (or `hx-post`) on anything else with
+ *   `hx-target` — the dominant button-driven pattern.
+ * - **event-handler**: `hx-on:*` or `hx-on:click` etc with no
+ *   fetch attr — pure client-side handler that happens to be wired
+ *   via htmx for historical consistency.
+ * - **unmatched**: anything that didn't fit cleanly. Reported as a
+ *   manual-review bucket.
+ */
+export function classify(tag: string, attrs: string[]): HtmxCategory {
+	const has = (name: string) => attrs.includes(name);
+	const hasAny = (re: RegExp) => attrs.some((a) => re.test(a));
+
+	if (has("hx-boost")) return "boost";
+	if (has("hx-swap-oob") || has("hx-select-oob")) return "oob-swap";
+
+	const hasFetch = hasAny(/^hx-(get|post|put|patch|delete)$/);
+	// htmx supports both colon (`hx-on:click`) and dash (`hx-on-click`)
+	// syntax for event handlers; HTML's spec doesn't allow `:` in
+	// attribute names so htmx 2.x canonicalised the dash form. Match
+	// both. The dash form is followed by an event name (`click`,
+	// `htmx-config-request`, etc.), the colon form by `:event`.
+	const hasOn = hasAny(/^hx-on(?:[:-]|$)/);
+	const hasTarget = has("hx-target");
+	const triggerIsAutoLike =
+		// We don't have the value of the trigger here — just whether
+		// the attribute exists. The dominant non-form pattern *with*
+		// hx-trigger is "keyup changed delay:Xms" or "intersect".
+		// Without value access, we infer "auto-fetch" by elimination:
+		// fetch + hx-trigger + non-form. Form-submit explicit triggers
+		// are caught by the form-swap branch via `tag === "form"`.
+		has("hx-trigger");
+
+	if (hasFetch) {
+		// `<form>` element — form-swap (regardless of trigger).
+		if (tag === "form") return "form-swap";
+		// `<input>`, `<textarea>` etc carrying a fetch attribute —
+		// they fire on input event, treat as auto-fetch.
+		if (tag === "input" || tag === "textarea" || tag === "select") {
+			return "auto-fetch";
+		}
+		// Non-form / non-input element with fetch + auto-trigger →
+		// auto-fetch (could be `<div hx-trigger="intersect" hx-get>`).
+		if (triggerIsAutoLike && !hasTarget) return "auto-fetch";
+		// Default for the dominant button-driven pattern.
+		return "click-swap";
+	}
+
+	if (hasOn) return "event-handler";
+
+	return "unmatched";
+}