@lokascript/htmx-adapter 3.0.0 → 3.1.0

package/src/extension.ts

@@ -4,18 +4,25 @@
  * Primary target is **htmx v4**, whose extensions register via
  * `htmx.registerExtension(name, ext)` and hook lifecycle events through
  * underscore-named methods (event name with `:` → `_`), each receiving
- * `(elt, detail)`. Verified against htmx 4.0.0-beta5 (see
+ * `(elt, detail)`. Verified against htmx 4.0.0 (see
  * test/browser/vendor/README.md): `process(root)` fires
  * `htmx:before:process` on the processed root — `document.body`
  * initially, each swapped-in subtree afterwards — BEFORE any element
  * init or hx-on binding, so canonicalizing in `htmx_before_process`
  * covers everything htmx will read. `htmx_before_process_node` is kept
  * as a defensive alias for other v4 prereleases that used per-node
- * naming; an unmatched key is inert.
+ * naming; an unmatched key is inert. The cancelable
+ * `htmx_before_on_init` hook (fires per hx-on-carrying node, after
+ * before:process; documented as cancelable in htmx 4.0.0's `htmx.d.ts`)
+ * lets executor mode keep claimed `hx-on:*` attributes in the DOM
+ * instead of removing them — see createExtension.
  *
  * A v2 fallback (`htmx.defineExtension` + `onEvent('htmx:beforeProcessNode')`)
  * is included because the localized attribute names are version-agnostic
- * data — but v2 support is best-effort, not a tested target.
+ * data — but v2 support is best-effort, not a tested target. Measured on
+ * 2.0.10: `processNode` binds `hx-on` (`processHxOnWildcard`) BEFORE it
+ * fires `htmx:beforeProcessNode` per node, so v2 has no pre-bind seam and
+ * executor-mode claims keep removing canonical `hx-on:*` attrs there.
  *
  * The extension hook alone is not enough for the *initial* page: script
  * order decides whether our sweep beats htmx's own DOMContentLoaded scan.
@@ -25,27 +32,90 @@
  * ahead of htmx's.
  */
 
-import { canonicalizeTree } from './canonicalize.js';
+import { canonicalizeTree, setTriggerSpecSplitter } from './canonicalize.js';
 import { onVocabUpdate } from './registry.js';
-import { onBodyHooksChanged } from './hx-on.js';
+import {
+  claimedAttrNames,
+  onBodyHooksChanged,
+  removeClaimedCanonicalAttrs,
+  setNeutralizeOnClaim,
+} from './hx-on.js';
 
 export const EXTENSION_NAME = 'lokascript-i18n';
 
 /** Minimal shape of the htmx global we interact with. */
 export interface HtmxLike {
-  /** htmx v4 registration entry point. */
-  registerExtension?(name: string, extension: object): void;
+  /**
+   * htmx v4 registration entry point. Returns `false` when the name is
+   * rejected — `htmx.config.extensions` is a non-empty allowlist that
+   * omits it, or it was already registered. (`htmx.d.ts` types the
+   * return as `void`; the runtime, verified on 4.0.0, returns `false`.)
+   */
+  registerExtension?(name: string, extension: object): boolean | void;
   /** htmx v1/v2 registration entry point. */
   defineExtension?(name: string, extension: object): void;
+  /** htmx v4 config — the parts that decide which hx-on spellings it binds. */
+  config?: {
+    /** Alternate attribute prefix (`data-hx-` by default; `''` disables it). */
+    prefix?: string;
+    /** Separator between `hx-on` and the event name (`:` by default). */
+    metaCharacter?: string;
+  };
+}
+
+/** The slice of htmx v4's `internalAPI` the extension reads. */
+interface InternalApiLike {
+  HCON?: { split?(value: string): string[] };
+}
+
+/**
+ * The hx-on attribute names htmx v4 will bind on a node, mirroring
+ * `#prefixes("hx-on")` + `#handleHxOnAttributes` (vendored 4.0.0):
+ * for each prefix `p` in [`hx-on`, `config.prefix + "on"`], the bare
+ * composite `p` (`hx-on="event -> code"`) and `p + metaCharacter + event`.
+ * `hx-online` / `data-hx-once` are NOT bound — the char after the prefix
+ * must be the meta character.
+ */
+function isHtmxBindableHxOn(name: string, prefixes: string[], mc: string): boolean {
+  for (const p of prefixes) {
+    if (name === p) return true;
+    if (name.startsWith(p) && name.charAt(p.length) === mc) return true;
+  }
+  return false;
 }
 
 /**
  * Build the extension object. v4 hooks and the v2 `onEvent` callback are
- * both present — each API only reads the members it knows about.
+ * both present — each API only reads the members it knows about. Pass
+ * the htmx instance so the v4 hook can read `config.prefix` /
+ * `config.metaCharacter` (defaults are assumed otherwise).
+ *
+ * `init(internalAPI)` (v4 only) takes exactly one thing from the API:
+ * `HCON.split`, htmx's own top-level trigger-spec splitter, which
+ * replaces the regex mirror in canonicalize.ts for the lifetime of the
+ * page. The rest of the 4.0.0 surface — `attributeValue`,
+ * `parseTriggerSpecs`, `getAttributeObject`, `insertContent`, `morph`,
+ * `initSecurity`, `onTrigger`, `htmxProp`, `triggerHtmxEvent`,
+ * `executeJavaScript` — was evaluated and not used: `parseTriggerSpecs`
+ * is parse-only (no serializer, so translating through it would mean a
+ * hand-written spec serializer); `attributeValue`'s inheritance-aware
+ * reads buy nothing for a sweep that visits every element anyway; and
+ * `htmxProp(node).onInitialized = true` WOULD keep htmx's binder off a
+ * node, but couples to a private flag where `htmx:before:on:init` is a
+ * typed, documented, cancelable event — the hook below uses that.
  */
-export function createExtension(): object {
+export function createExtension(htmx?: HtmxLike | null): object {
+  const cfg = htmx?.config;
+  const prefix = cfg && 'prefix' in cfg ? (cfg.prefix ?? '') : 'data-hx-';
+  const mc = cfg?.metaCharacter || ':';
+  const hxOnPrefixes = prefix ? ['hx-on', prefix + 'on'] : ['hx-on'];
+
   return {
-    // htmx v4 (verified on 4.0.0-beta5): fires on each process() root
+    init(internalAPI?: InternalApiLike): void {
+      const split = internalAPI?.HCON?.split;
+      if (typeof split === 'function') setTriggerSpecSplitter(split.bind(internalAPI!.HCON));
+    },
+    // htmx v4 (verified on 4.0.0): fires on each process() root
     // before element init and hx-on binding.
     htmx_before_process(elt: Element): void {
       canonicalizeTree(elt);
@@ -54,6 +124,36 @@ export function createExtension(): object {
     htmx_before_process_node(elt: Element): void {
       canonicalizeTree(elt);
     },
+    // htmx v4 (verified on 4.0.0): fires per node carrying an
+    // hx-on-family attribute, cancelable — returning false makes htmx
+    // skip JS-binding that node entirely. This is executor mode's
+    // zero-mutation double-execution guard, decided from what the sweep
+    // RECORDED on the node (not from whether an executor is set now):
+    //
+    // - nothing claimed on this node → htmx proceeds as usual;
+    // - every hx-on attribute htmx would bind here is claimed → cancel,
+    //   the authored attributes stay in the DOM;
+    // - the node also carries forms htmx must bind and the adapter never
+    //   claims (the legacy composite `hx-on="event -> code"`, the
+    //   `config.prefix` spelling, a custom meta character) → per-node
+    //   cancellation would kill those too, so fall back to removing the
+    //   claimed canonical attrs and let htmx bind the rest.
+    htmx_before_on_init(elt: Element): boolean | undefined {
+      const claimedNames = claimedAttrNames(elt);
+      if (claimedNames.size === 0) return undefined;
+      let unclaimedBindable = false;
+      for (const attr of Array.from(elt.attributes)) {
+        const name = attr.name;
+        if (claimedNames.has(name)) continue;
+        if (isHtmxBindableHxOn(name, hxOnPrefixes, mc)) {
+          unclaimedBindable = true;
+          break;
+        }
+      }
+      if (!unclaimedBindable) return false;
+      removeClaimedCanonicalAttrs(elt);
+      return undefined;
+    },
     // htmx v1/v2 fallback: single event dispatcher.
     onEvent(name: string, evt: CustomEvent & { target?: EventTarget | null }): void {
       if (name !== 'htmx:beforeProcessNode') return;
@@ -66,26 +166,62 @@ export function createExtension(): object {
 
 /**
  * Register the extension with an htmx global. Returns which API accepted
- * it (`'v4'` / `'v2'`) or `null` if the object exposes neither.
+ * it (`'v4'` / `'v2'`) or `null` if the object exposes neither, or if
+ * v4 rejected the registration.
+ *
+ * Only an ACCEPTED v4 registration turns claim-time neutralization off:
+ * that is the one runtime whose per-node `htmx:before:on:init` hook can
+ * keep htmx off a preserved `hx-on:*` attribute. Everything else keeps
+ * the hook-independent removal guard.
  */
 export function registerWith(htmx: HtmxLike | undefined | null): 'v4' | 'v2' | null {
   if (!htmx) return null;
-  const ext = createExtension();
+  const ext = createExtension(htmx);
   if (typeof htmx.registerExtension === 'function') {
-    htmx.registerExtension(EXTENSION_NAME, ext);
+    // v4 REJECTS the registration (returns false) when
+    // `htmx.config.extensions` is an allowlist that omits us, or on a
+    // duplicate name. Nothing we return from a hook can then run, so
+    // claim-time neutralization must stay on — turning it off here would
+    // leave claimed hx-on:* bodies in the DOM for htmx to JS-eval.
+    if (htmx.registerExtension(EXTENSION_NAME, ext) === false) {
+      if (typeof console !== 'undefined') {
+        console.warn(
+          `[htmx-i18n] htmx.registerExtension("${EXTENSION_NAME}") returned false — the ` +
+            'extension is not registered. If htmx.config.extensions (the <meta name="htmx-config"> ' +
+            `allowlist) is set, add "${EXTENSION_NAME}" to it. Swapped-in content will not be ` +
+            'canonicalized; executor-mode claims fall back to removing canonical hx-on:* attrs.'
+        );
+      }
+      setNeutralizeOnClaim(true);
+      return null;
+    }
+    setNeutralizeOnClaim(false);
     return 'v4';
   }
   if (typeof htmx.defineExtension === 'function') {
     htmx.defineExtension(EXTENSION_NAME, ext);
+    // v2 binds hx-on before it fires beforeProcessNode — no pre-bind
+    // seam, so removal at claim time stays the guard.
+    setNeutralizeOnClaim(true);
     return 'v2';
   }
   return null;
 }
 
 /**
- * Sweep the whole document now (if parsed) or on DOMContentLoaded, and
- * re-sweep whenever a vocab module registers after the initial sweep
- * (e.g. a vocab <script> below htmx, or dynamic registration).
+ * Sweep the whole document once the DOM is parsed, and re-sweep whenever
+ * a vocab module registers or the body executor changes after that
+ * (e.g. a vocab <script> below htmx, a lazily loaded _hyperscript, or
+ * dynamic registration).
+ *
+ * "Parsed" means DOMContentLoaded has FIRED (or `readyState` is already
+ * `'complete'`) — not merely `readyState !== 'loading'`. During
+ * DOMContentLoaded dispatch `readyState` is already `'interactive'`, and
+ * a `defer`/module adapter runs at `'interactive'` before htmx exists;
+ * sweeping then would claim in the default remove mode before
+ * `registerWith` had a chance to turn neutralization off. A `load`
+ * listener covers a script injected after DOMContentLoaded but before
+ * `'complete'` (DOMContentLoaded will not fire again for it).
  *
  * Returns a cleanup function (mainly for tests).
  */
@@ -94,28 +230,41 @@ export function installAutoSweep(doc: Document = document): () => void {
     canonicalizeTree(doc.body ?? doc.documentElement);
   };
 
-  let removeDomListener: (() => void) | null = null;
-  if (doc.readyState === 'loading') {
-    const onReady = (): void => sweep();
-    doc.addEventListener('DOMContentLoaded', onReady, { once: true });
-    removeDomListener = () => doc.removeEventListener('DOMContentLoaded', onReady);
-  } else {
+  let ready = doc.readyState === 'complete';
+  let removeReadyListeners: (() => void) | null = null;
+  if (ready) {
     sweep();
+  } else {
+    const onReady = (): void => {
+      if (ready) return;
+      ready = true;
+      removeReadyListeners?.();
+      sweep();
+    };
+    const win = doc.defaultView;
+    doc.addEventListener('DOMContentLoaded', onReady);
+    win?.addEventListener('load', onReady);
+    removeReadyListeners = () => {
+      doc.removeEventListener('DOMContentLoaded', onReady);
+      win?.removeEventListener('load', onReady);
+    };
   }
 
   const unsubscribeVocab = onVocabUpdate(() => {
-    if (doc.readyState !== 'loading') sweep();
+    if (ready) sweep();
   });
 
   // A body executor configured after the initial sweep flips the hx-on
   // family into executor mode — re-sweep so already-canonicalized
-  // hx-on:* attrs get claimed (listener installed, attr removed).
+  // hx-on:* attrs get claimed (listener installed; an adapter-created
+  // canonical sibling is removed, an authored one is left for the v4
+  // hook or removed by the claim, per the neutralization setting).
   const unsubscribeBodyHooks = onBodyHooksChanged(() => {
-    if (doc.readyState !== 'loading') sweep();
+    if (ready) sweep();
   });
 
   return () => {
-    removeDomListener?.();
+    removeReadyListeners?.();
     unsubscribeVocab();
     unsubscribeBodyHooks();
   };

package/src/hx-on.ts

@@ -19,11 +19,21 @@
  * - Localized-named attrs (`hx-en:clic`) stay verbatim in the DOM — htmx
  *   never recognized them anyway — and NO canonical `hx-on:*` sibling is
  *   created.
- * - Canonical-named attrs (`hx-on:click`) are REMOVED after claiming.
- *   This is the one place the adapter deletes an authored attribute: if
- *   it stayed, htmx would eval the hyperscript body as JS — a console
- *   error plus a double-execution attempt on every fire. Documented as
- *   the executor-mode exception in the README.
+ * - Canonical-named attrs (`hx-on:click`) must be kept away from htmx's
+ *   own binder: if htmx bound them, it would eval the hyperscript body
+ *   as JS — a console error plus a double-execution attempt on every
+ *   fire. A claim RECORDS the attribute (name + body) on the element;
+ *   what keeps htmx off it is decided by whoever owns the runtime:
+ *   - htmx v4, extension accepted: the extension's cancelable
+ *     `htmx:before:on:init` hook consults the record per node and
+ *     cancels htmx's binding — the authored attribute stays in the DOM
+ *     (see extension.ts). `registerWith` turns claim-time removal OFF
+ *     only after the registration actually succeeded.
+ *   - everywhere else (htmx v2, a rejected v4 registration, no htmx):
+ *     `neutralizeOnClaim` is ON (the default) and the canonical-named
+ *     attribute is removed at claim time — the only guard that does not
+ *     depend on a hook being installed, documented as the executor-mode
+ *     exception in the README.
  *
  * With no executor set (the default), none of this runs and bodies keep
  * upstream JS semantics — the behavior-preservation invariant.
@@ -32,28 +42,66 @@
  * loads after the initial sweep still applies. Both auto-detection
  * (`autoDetectBodyHooks`) and manual configuration are supported; the
  * executor is also re-read at fire time so replacing it takes effect on
- * live listeners.
+ * live listeners. The body is re-read on every re-claim, so
+ * `htmx.process(elt, true)` after editing the attribute runs the new body.
  */
 
 export type BodyExecutor = (code: string, elt: Element, evt: Event) => unknown;
 export type BodyTranslator = (body: string, lang: string) => string;
 
+/** Own-key lookup: vocab maps are plain objects, and `constructor` is not an event. */
+const hasOwn = (o: object, k: string): boolean => Object.prototype.hasOwnProperty.call(o, k);
+
 let executor: BodyExecutor | null = null;
 let translator: BodyTranslator | null = null;
 
 /** Listeners notified when the executor is set/cleared (drives re-sweeps). */
 const hookChangeListeners = new Set<() => void>();
 
+/** One claimed hx-on attribute on an element. */
+interface Claim {
+  /** The attribute the listener was installed for (`hx-on:click` / `hx-en:clic`). */
+  attrName: string;
+  /** Element language at claim time — drives lazy body translation. */
+  lang: string;
+  /** Authored body, refreshed on re-claim when the attribute changed. */
+  body: string;
+  /** Memoized translation of `body` (null = not translated yet). */
+  translated: string | null;
+}
+
+/**
+ * Per-element claims keyed by resolved EVENT name (sweep idempotency).
+ * Keyed by event rather than attribute name so a localized attr and its
+ * canonical form never both install a listener. When both are genuinely
+ * authored, DOM attribute order decides which body wins; an
+ * adapter-created canonical sibling (a no-executor sweep copied
+ * `hx-en:clic` to `hx-on:click`, then an executor arrived) is removed
+ * on the re-claim — it was never authored, so the never-mutate rule does
+ * not cover it, and leaving it would hand htmx a foreign-language body.
+ */
+let claimed = new WeakMap<Element, Map<string, Claim>>();
+
 /**
- * Per-element set of already-claimed EVENT names (sweep idempotency).
- * Keyed by resolved event name rather than attribute name so a localized
- * attr and its canonical form never both install a listener — e.g. after
- * a v1 (no-executor) sweep created an `hx-on:click` sibling of
- * `hx-en:clic` and an executor registered later, the re-sweep claims one
- * of them and neutralizes the other. When both are genuinely authored,
- * DOM attribute order decides which body wins.
+ * Whether a claim on a canonical-named `hx-on:*` attribute deletes it.
+ *
+ * ON (default) is the hook-independent guard. `registerWith` turns it
+ * OFF only once htmx v4 has actually accepted the extension, because
+ * only then does the per-node `htmx_before_on_init` cancellation exist
+ * to keep htmx off the preserved attribute. Consumers wiring
+ * `createExtension()` into `htmx.registerExtension` themselves must
+ * call `setNeutralizeOnClaim(false)` after a successful registration
+ * to get the same zero-mutation behaviour.
  */
-let claimed = new WeakMap<Element, Set<string>>();
+let neutralizeOnClaim = true;
+
+export function setNeutralizeOnClaim(enabled: boolean): void {
+  neutralizeOnClaim = enabled;
+}
+
+export function neutralizesOnClaim(): boolean {
+  return neutralizeOnClaim;
+}
 
 /** Configure the body executor. Setting/clearing it notifies subscribers. */
 export function setBodyExecutor(fn: BodyExecutor | null): void {
@@ -82,20 +130,62 @@ export function onBodyHooksChanged(listener: () => void): () => void {
   };
 }
 
+/** True when the adapter has claimed at least one hx-on attribute on `elt`. */
+export function isClaimed(elt: Element): boolean {
+  return (claimed.get(elt)?.size ?? 0) > 0;
+}
+
+/** Names of the attributes claimed on `elt` (canonical and localized). */
+export function claimedAttrNames(elt: Element): Set<string> {
+  const names = new Set<string>();
+  const claims = claimed.get(elt);
+  if (claims) for (const c of claims.values()) names.add(c.attrName);
+  return names;
+}
+
+/**
+ * Remove the claimed CANONICAL-named (`hx-on:*`) attributes from `elt`.
+ * The per-node fallback for runtimes that will bind the node anyway
+ * (v4 mixed nodes). Localized names are invisible to htmx and stay.
+ * Returns how many were removed.
+ */
+export function removeClaimedCanonicalAttrs(elt: Element): number {
+  let n = 0;
+  for (const name of claimedAttrNames(elt)) {
+    if (name.startsWith('hx-on:') && elt.hasAttribute(name)) {
+      elt.removeAttribute(name);
+      n++;
+    }
+  }
+  return n;
+}
+
 /**
  * Resolve the DOM event name for an hx-on attribute suffix.
  * `hx-on::after-swap` shorthand (leading `:`) means the `htmx:` namespace;
- * plain suffixes translate through the vocab events map.
+ * plain suffixes translate through the vocab events map (own keys only —
+ * `constructor` is not an event).
  */
 function eventNameForSuffix(rawSuffix: string, events: Record<string, string>): string {
   if (rawSuffix.startsWith(':')) return `htmx${rawSuffix}`;
-  return events[rawSuffix] ?? rawSuffix;
+  return hasOwn(events, rawSuffix) ? events[rawSuffix] : rawSuffix;
+}
+
+export interface ClaimOptions {
+  /**
+   * The attribute was written by the adapter's own canonicalization (a
+   * no-executor sweep's `hx-on:*` copy of a localized attr), not by the
+   * author. Such a duplicate is always removed on claim.
+   */
+  adapterCreated?: boolean;
 }
 
 /**
- * Claim one hx-on-family attribute on an element: install the executor
- * listener and neutralize htmx's view of it. Returns true if the claim
- * happened now (false when no executor, already claimed, or malformed).
+ * Claim one hx-on-family attribute on an element: record it, install the
+ * executor listener, and — when claim-time neutralization is on — remove
+ * a canonical-named attribute so htmx never JS-evals it. Returns true if
+ * the element changed or a listener was installed now (false when no
+ * executor, already claimed for that event, or malformed).
  *
  * `lang` is the element's language at claim time — used for lazy body
  * translation. `events` is the language's event-name map (for the
@@ -105,7 +195,8 @@ export function claimHxOnAttribute(
   elt: Element,
   attrName: string,
   lang: string,
-  events: Record<string, string>
+  events: Record<string, string>,
+  options: ClaimOptions = {}
 ): boolean {
   if (!executor) return false;
 
@@ -113,30 +204,46 @@ export function claimHxOnAttribute(
   if (colon <= 0) return false; // colon-form only; legacy composite hx-on="…" unsupported
 
   const eventName = eventNameForSuffix(attrName.slice(colon + 1), events);
-  const already = claimed.get(elt);
-  if (already?.has(eventName)) {
-    // Duplicate claim for an already-claimed event — no second listener,
-    // but canonical-named attrs still get neutralized so htmx never
-    // JS-evals them.
-    if (attrName.startsWith('hx-on:') && elt.hasAttribute(attrName)) {
+  const canonical = attrName.startsWith('hx-on:');
+  const body = elt.getAttribute(attrName) ?? '';
+
+  let claims = claimed.get(elt);
+  const existing = claims?.get(eventName);
+  if (existing) {
+    if (existing.attrName === attrName) {
+      // Re-claim of the same attribute (re-sweep, or a force re-process
+      // after the author edited it): refresh the body, no new listener.
+      if (existing.body !== body) {
+        existing.body = body;
+        existing.translated = null;
+      }
+      if (canonical && neutralizeOnClaim && elt.hasAttribute(attrName)) {
+        elt.removeAttribute(attrName);
+        return true;
+      }
+      return false;
+    }
+    // A second attribute for an already-claimed event (localized +
+    // canonical naming the same event). No second listener. A canonical
+    // duplicate is removed when it is adapter-created (never authored)
+    // or when claim-time neutralization is on; an authored one stays
+    // for the v4 hook to cancel.
+    if (canonical && (options.adapterCreated || neutralizeOnClaim) && elt.hasAttribute(attrName)) {
       elt.removeAttribute(attrName);
       return true;
     }
     return false;
   }
 
-  const body = elt.getAttribute(attrName) ?? '';
-
-  // Lazy, memoized translation: translator may register after the sweep,
-  // and repeated fires shouldn't re-translate.
-  let translatedBody: string | null = null;
+  const claim: Claim = { attrName, lang, body, translated: null };
   elt.addEventListener(eventName, evt => {
     if (!executor) return; // executor cleared after claim — go quiet
-    if (translatedBody === null) {
-      translatedBody = lang !== 'en' && translator ? translator(body, lang) : body;
+    if (claim.translated === null) {
+      claim.translated =
+        claim.lang !== 'en' && translator ? translator(claim.body, claim.lang) : claim.body;
     }
     try {
-      executor(translatedBody, elt, evt);
+      executor(claim.translated, elt, evt);
     } catch (err) {
       if (typeof console !== 'undefined') {
         console.error(`[htmx-i18n] hx-on body execution failed (${attrName} → ${eventName})`, err);
@@ -144,16 +251,18 @@ export function claimHxOnAttribute(
     }
   });
 
-  // Canonical-named claims are removed so htmx never JS-evals the
-  // hyperscript body (double-execution guard). Localized names are
-  // invisible to htmx and stay verbatim.
-  if (attrName.startsWith('hx-on:')) elt.removeAttribute(attrName);
-
-  if (already) {
-    already.add(eventName);
-  } else {
-    claimed.set(elt, new Set([eventName]));
+  if (!claims) {
+    claims = new Map();
+    claimed.set(elt, claims);
   }
+  claims.set(eventName, claim);
+
+  // Hook-independent guard: with neutralization on, a canonical-named
+  // claim is deleted so htmx never JS-evals the hyperscript body. With it
+  // off (v4 extension accepted) the attribute stays and the extension's
+  // before:on:init hook cancels htmx's binding instead. Localized names
+  // are invisible to htmx and always stay verbatim.
+  if (canonical && neutralizeOnClaim) elt.removeAttribute(attrName);
   return true;
 }
 
@@ -194,4 +303,5 @@ export function resetBodyHooks(): void {
   translator = null;
   hookChangeListeners.clear();
   claimed = new WeakMap();
+  neutralizeOnClaim = true;
 }

package/src/index.ts

@@ -28,7 +28,15 @@ export {
   type HtmxVocab,
   type VocabPayload,
 } from './registry.js';
-export { canonicalizeElement, canonicalizeTree, translateTriggerValue } from './canonicalize.js';
+export {
+  canonicalizeElement,
+  canonicalizeTree,
+  translateTriggerValue,
+  setTriggerSpecSplitter,
+  wasCreatedByAdapter,
+  TOP_LEVEL_COMMA_RE,
+  type TriggerSpecSplitter,
+} from './canonicalize.js';
 export {
   EXTENSION_NAME,
   createExtension,
@@ -50,8 +58,14 @@ export {
   hasBodyTranslator,
   onBodyHooksChanged,
   claimHxOnAttribute,
+  claimedAttrNames,
+  isClaimed,
+  removeClaimedCanonicalAttrs,
+  setNeutralizeOnClaim,
+  neutralizesOnClaim,
   autoDetectBodyHooks,
   resetBodyHooks,
   type BodyExecutor,
   type BodyTranslator,
+  type ClaimOptions,
 } from './hx-on.js';