@lokascript/htmx-adapter 2.8.0

package/dist/index.d.cts

@@ -0,0 +1,305 @@
+/**
+ * Per-element language resolution for localized htmx attribute names.
+ *
+ * Mirrors `packages/core/src/htmx/lang-resolver.ts` (which in turn mirrors
+ * loka-js's `lang-resolver.js`) so a page migrating between hyperfixi's
+ * embedded htmx-compat layer and this upstream-htmx adapter resolves
+ * languages identically. Resolution order:
+ *
+ *   1. `data-hyperfixi-lang` attribute on the element itself
+ *   2. `data-hyperfixi-lang` on any ancestor
+ *   3. `lang` attribute on any ancestor (HTML standard)
+ *   4. `'en'` fallback
+ *
+ * Results are normalized to the part before the first `-`/`_` (`es-MX` →
+ * `es`) and lowercased so callers can index vocab maps by 2-letter code
+ * without caring about regional variants.
+ */
+/** Normalize a language tag — `es-MX` / `ES_mx` → `es`. */
+declare function normLang(s: string | null | undefined): string;
+/** Resolve the language code for an element via ancestor walk. */
+declare function langOf(elt: Element): string;
+
+/**
+ * Vocab registry for the upstream-htmx adapter.
+ *
+ * Accepts the SAME payload shape as hyperfixi core's htmx-compat
+ * orchestrator (`packages/core/src/htmx/i18n-orchestrator.ts`), so the
+ * generated vocab modules under `packages/core/vocab/htmx/{lang}.js`
+ * (which call `window.__hyperfixi_i18n.register(lang, payload)`) work
+ * verbatim against this adapter — one generated artifact, two consumers.
+ *
+ *   register('es', {
+ *     hyperfixi: {
+ *       attrs: { 'hx-obtener': 'hx-get', 'sse-conectar': 'sse-connect' },
+ *       events: { clic: 'click', cambiar: 'change' },
+ *     },
+ *   });
+ *
+ * Unlike core's orchestrator this registry needs no inverted index: the
+ * adapter canonicalizes (localized → canonical), which is exactly the
+ * direction the parse maps are published in. There is deliberately no
+ * KEYS copy here either — the vocab data is self-describing (full
+ * attribute names on both sides), so the canonical key set lives only in
+ * core's generator (`packages/core/scripts/gen-htmx-vocab.mjs`).
+ */
+interface HtmxVocab {
+    /** Map of localized attribute name → canonical English form (fully qualified). */
+    attrs?: Record<string, string>;
+    /** Map of localized event name → canonical English form (`'clic'` → `'click'`). */
+    events?: Record<string, string>;
+}
+interface VocabPayload {
+    hyperfixi?: HtmxVocab;
+}
+/**
+ * Register a vocab module for a language. Idempotent — re-registering a
+ * language replaces its vocab entirely.
+ */
+declare function register(code: string, data: VocabPayload): void;
+/** Look up the vocab registered for a (normalized) language code. */
+declare function vocabFor(lang: string): HtmxVocab | undefined;
+/** Inspect whether any vocab is registered for a language. Mainly for tests. */
+declare function isLangRegistered(code: string): boolean;
+/** True if at least one language has registered vocab. */
+declare function hasAnyVocab(): boolean;
+/** Subscribe to vocab-registration notifications. Returns an unsubscribe fn. */
+declare function onVocabUpdate(listener: () => void): () => void;
+/**
+ * Reset registry state — drop all registrations and listeners. Mainly for
+ * tests; production code should leave registrations in place.
+ */
+declare function resetRegistry(): void;
+
+/**
+ * Localized → canonical attribute canonicalization for upstream htmx.
+ *
+ * htmx v4 has no hook to override how core resolves an attribute name —
+ * it reads `hx-get` literally. Until an upstream resolver seam exists
+ * (see docs/UPSTREAM_HOOK_PROPOSAL.md), this module makes localized
+ * authoring work by copying each localized attribute to its canonical
+ * name on the same element *before* htmx processes the node:
+ *
+ *   <button lang="es" hx-obtener="/api">  →  + hx-get="/api"
+ *
+ * Design rules (mirroring the loka-js invariants where the mechanism
+ * allows):
+ *
+ * - **The authored attribute is never removed or rewritten** — devtools
+ *   keeps showing what the author wrote. The one exception is an
+ *   author-written canonical `hx-trigger` whose *value* uses localized
+ *   event names (`hx-trigger="clic"`): there is no separate canonical
+ *   target to write to, so the value is translated in place (idempotent —
+ *   the maps are localized → canonical, so a second pass is a no-op).
+ * - **An existing canonical attribute always wins.** If the element
+ *   already has `hx-get`, a localized `hx-obtener` never overwrites it.
+ * - **No vocab, no work.** With no languages registered every function
+ *   here is a cheap no-op, so stock htmx pages pay ~nothing.
+ *
+ * Only attributes in the `hx-` / `sse-` / `ws-` namespaces are ever
+ * considered — the brand prefix is preserved across languages (Phase 8
+ * convention: Spanish writes `hx-obtener`, not `xx-obtener`), so the
+ * prefix doubles as the discovery anchor.
+ */
+/**
+ * Translate localized event names inside an `hx-trigger` value.
+ *
+ * hx-trigger grammar: comma-separated specs, each `eventName[filter]
+ * modifier…`. Only the leading event token of each spec is translated
+ * (preserving an attached `[...]` filter); modifiers like `delay:500ms`,
+ * `from:body`, `once` are language-invariant and left alone. Unknown
+ * tokens pass through untouched, which also makes translation idempotent
+ * (the maps are localized → canonical only).
+ */
+declare function translateTriggerValue(value: string, events: Record<string, string>): string;
+/**
+ * Canonicalize one element's localized htmx attributes in place.
+ * Returns true if any attribute was added or updated.
+ */
+declare function canonicalizeElement(elt: Element): boolean;
+/**
+ * Canonicalize an element and all its descendants. Returns the number of
+ * elements that changed. This is what the htmx extension hook and the
+ * initial document sweep call — htmx processes subtrees, so we mirror
+ * that granularity.
+ */
+declare function canonicalizeTree(root: Element | Document | DocumentFragment | null): number;
+
+/**
+ * htmx extension + auto-sweep wiring.
+ *
+ * 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
+ * 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.
+ *
+ * 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.
+ *
+ * The extension hook alone is not enough for the *initial* page: script
+ * order decides whether our sweep beats htmx's own DOMContentLoaded scan.
+ * `installAutoSweep()` handles that — load this adapter (and vocab
+ * modules) BEFORE the htmx <script> tag, mirroring loka-js's
+ * "orchestrator before libraries" rule, and the sweep listener registers
+ * ahead of htmx's.
+ */
+declare const EXTENSION_NAME = "lokascript-i18n";
+/** Minimal shape of the htmx global we interact with. */
+interface HtmxLike {
+    /** htmx v4 registration entry point. */
+    registerExtension?(name: string, extension: object): void;
+    /** htmx v1/v2 registration entry point. */
+    defineExtension?(name: string, extension: object): void;
+}
+/**
+ * Build the extension object. v4 hooks and the v2 `onEvent` callback are
+ * both present — each API only reads the members it knows about.
+ */
+declare function createExtension(): object;
+/**
+ * Register the extension with an htmx global. Returns which API accepted
+ * it (`'v4'` / `'v2'`) or `null` if the object exposes neither.
+ */
+declare function registerWith(htmx: HtmxLike | undefined | null): 'v4' | 'v2' | 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).
+ *
+ * Returns a cleanup function (mainly for tests).
+ */
+declare function installAutoSweep(doc?: Document): () => void;
+
+/**
+ * Resolver mode — the adapter's mechanism-(c) form, usable today against
+ * the reference-patched htmx build (docs/reference-patches/) and ready
+ * for upstream if the attribute-resolver seam lands.
+ *
+ * Where the default shim CANONICALIZES (copies localized attrs onto the
+ * element), resolver mode answers htmx's attribute lookups directly:
+ * core asks "what should I read for `hx-get` on this element?" and the
+ * resolver returns the localized name actually present (`hx-obtener`)
+ * for the element's language scope. Zero DOM mutation, fully
+ * devtools-faithful — the loka-js ideal.
+ *
+ * Two seams must both be fed (the loka-js lesson): the per-element
+ * resolver answers reads, and `additionalAttributeSelectors` feeds the
+ * document-level discovery scan, which a per-element function cannot
+ * drive. `installResolverMode()` wires both and keeps the selector list
+ * fresh as vocab modules register.
+ *
+ * Scope: value-bearing attributes only. The hx-on colon family stays
+ * with the shim/executor mode — its event name is part of the attribute
+ * NAME, which is a different question than "what name holds this
+ * value". Trigger VALUES (`hx-trigger="clic"`) are also name-level
+ * out-of-scope; keep authoring canonical event values, or pair with
+ * executor mode.
+ */
+/** True while resolver mode owns localization (the shim stands down). */
+declare function isResolverMode(): boolean;
+/** Mainly for tests; installResolverMode() manages this in production. */
+declare function setResolverMode(active: boolean): void;
+/**
+ * The per-element resolver htmx consults on attribute reads:
+ * `(elt, canonicalName) → localized name present on elt, or null`.
+ */
+declare function attributeResolver(elt: Element, name: string): string | null;
+/**
+ * CSS attribute selectors for every registered localized name, for
+ * htmx's discovery scan (`config.additionalAttributeSelectors`). The
+ * hx-on family is excluded — see the module header.
+ */
+declare function additionalAttributeSelectors(): string[];
+interface ResolverConfigurableHtmx {
+    config?: {
+        attributeResolver?: ((elt: Element, name: string) => string | null) | null;
+        additionalAttributeSelectors?: string[];
+    };
+}
+/**
+ * Wire resolver mode into a (reference-patched) htmx instance: install
+ * the resolver, feed the discovery selectors, keep them fresh on vocab
+ * registration, and stand the canonicalization shim down. Returns an
+ * uninstall function that restores shim behavior.
+ */
+declare function installResolverMode(htmx: ResolverConfigurableHtmx): () => void;
+
+/**
+ * hx-on body support — opt-in "executor mode".
+ *
+ * Upstream htmx evals `hx-on:*` bodies as JavaScript. In the hyperfixi
+ * ecosystem the convention is hyperscript bodies (`hx-on:click="toggle
+ * .active on me"`), which htmx's JS eval cannot run — and localized
+ * bodies (`hx-en:clic="alternar .active"`) doubly so. This module lets a
+ * page opt in to hyperscript-body semantics by configuring an executor:
+ *
+ *   setBodyExecutor((code, elt, evt) => _hyperscript.evaluate(code, { me: elt, event: evt }))
+ *   setBodyTranslator((body, lang) => HyperscriptI18n.preprocess(body, lang))
+ *
+ * With an executor set, the adapter CLAIMS every hx-on-family attribute
+ * (localized-named or canonical-named — all bodies are treated as
+ * hyperscript; mixed JS/hyperscript pages have no reliable detection):
+ * it installs a real event listener that runs the (lazily translated)
+ * body through the executor, and keeps htmx away from it:
+ *
+ * - 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.
+ *
+ * With no executor set (the default), none of this runs and bodies keep
+ * upstream JS semantics — the behavior-preservation invariant.
+ *
+ * Translation is lazy (first event fire, memoized) so a translator that
+ * 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.
+ */
+type BodyExecutor = (code: string, elt: Element, evt: Event) => unknown;
+type BodyTranslator = (body: string, lang: string) => string;
+/** Configure the body executor. Setting/clearing it notifies subscribers. */
+declare function setBodyExecutor(fn: BodyExecutor | null): void;
+/** Configure the body translator (localized body → English hyperscript). */
+declare function setBodyTranslator(fn: BodyTranslator | null): void;
+declare function hasBodyExecutor(): boolean;
+declare function hasBodyTranslator(): boolean;
+/** Subscribe to executor changes. Returns an unsubscribe fn. */
+declare function onBodyHooksChanged(listener: () => void): () => void;
+/**
+ * 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).
+ *
+ * `lang` is the element's language at claim time — used for lazy body
+ * translation. `events` is the language's event-name map (for the
+ * listener's event name; the shorthand/unknown cases pass through).
+ */
+declare function claimHxOnAttribute(elt: Element, attrName: string, lang: string, events: Record<string, string>): boolean;
+/**
+ * Auto-detect body hooks from page globals — called by the browser entry
+ * at load and again at DOMContentLoaded. Never overwrites hooks that
+ * were set explicitly.
+ *
+ * - `window._hyperscript` → executor (original _hyperscript; pairs with
+ *   `@lokascript/hyperscript-adapter` for multilingual `_=` too)
+ * - `window.HyperscriptI18n.preprocess` → translator (the
+ *   hyperscript-adapter browser bundles expose exactly this)
+ */
+declare function autoDetectBodyHooks(win: object): void;
+/** Reset all body-hook state. Mainly for tests. */
+declare function resetBodyHooks(): void;
+
+export { type BodyExecutor, type BodyTranslator, EXTENSION_NAME, type HtmxLike, type HtmxVocab, type VocabPayload, additionalAttributeSelectors, attributeResolver, autoDetectBodyHooks, canonicalizeElement, canonicalizeTree, claimHxOnAttribute, createExtension, hasAnyVocab, hasBodyExecutor, hasBodyTranslator, installAutoSweep, installResolverMode, isLangRegistered, isResolverMode, langOf, normLang, onBodyHooksChanged, onVocabUpdate, register, registerWith, resetBodyHooks, resetRegistry, setBodyExecutor, setBodyTranslator, setResolverMode, translateTriggerValue, vocabFor };

package/dist/index.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Per-element language resolution for localized htmx attribute names.
+ *
+ * Mirrors `packages/core/src/htmx/lang-resolver.ts` (which in turn mirrors
+ * loka-js's `lang-resolver.js`) so a page migrating between hyperfixi's
+ * embedded htmx-compat layer and this upstream-htmx adapter resolves
+ * languages identically. Resolution order:
+ *
+ *   1. `data-hyperfixi-lang` attribute on the element itself
+ *   2. `data-hyperfixi-lang` on any ancestor
+ *   3. `lang` attribute on any ancestor (HTML standard)
+ *   4. `'en'` fallback
+ *
+ * Results are normalized to the part before the first `-`/`_` (`es-MX` →
+ * `es`) and lowercased so callers can index vocab maps by 2-letter code
+ * without caring about regional variants.
+ */
+/** Normalize a language tag — `es-MX` / `ES_mx` → `es`. */
+declare function normLang(s: string | null | undefined): string;
+/** Resolve the language code for an element via ancestor walk. */
+declare function langOf(elt: Element): string;
+
+/**
+ * Vocab registry for the upstream-htmx adapter.
+ *
+ * Accepts the SAME payload shape as hyperfixi core's htmx-compat
+ * orchestrator (`packages/core/src/htmx/i18n-orchestrator.ts`), so the
+ * generated vocab modules under `packages/core/vocab/htmx/{lang}.js`
+ * (which call `window.__hyperfixi_i18n.register(lang, payload)`) work
+ * verbatim against this adapter — one generated artifact, two consumers.
+ *
+ *   register('es', {
+ *     hyperfixi: {
+ *       attrs: { 'hx-obtener': 'hx-get', 'sse-conectar': 'sse-connect' },
+ *       events: { clic: 'click', cambiar: 'change' },
+ *     },
+ *   });
+ *
+ * Unlike core's orchestrator this registry needs no inverted index: the
+ * adapter canonicalizes (localized → canonical), which is exactly the
+ * direction the parse maps are published in. There is deliberately no
+ * KEYS copy here either — the vocab data is self-describing (full
+ * attribute names on both sides), so the canonical key set lives only in
+ * core's generator (`packages/core/scripts/gen-htmx-vocab.mjs`).
+ */
+interface HtmxVocab {
+    /** Map of localized attribute name → canonical English form (fully qualified). */
+    attrs?: Record<string, string>;
+    /** Map of localized event name → canonical English form (`'clic'` → `'click'`). */
+    events?: Record<string, string>;
+}
+interface VocabPayload {
+    hyperfixi?: HtmxVocab;
+}
+/**
+ * Register a vocab module for a language. Idempotent — re-registering a
+ * language replaces its vocab entirely.
+ */
+declare function register(code: string, data: VocabPayload): void;
+/** Look up the vocab registered for a (normalized) language code. */
+declare function vocabFor(lang: string): HtmxVocab | undefined;
+/** Inspect whether any vocab is registered for a language. Mainly for tests. */
+declare function isLangRegistered(code: string): boolean;
+/** True if at least one language has registered vocab. */
+declare function hasAnyVocab(): boolean;
+/** Subscribe to vocab-registration notifications. Returns an unsubscribe fn. */
+declare function onVocabUpdate(listener: () => void): () => void;
+/**
+ * Reset registry state — drop all registrations and listeners. Mainly for
+ * tests; production code should leave registrations in place.
+ */
+declare function resetRegistry(): void;
+
+/**
+ * Localized → canonical attribute canonicalization for upstream htmx.
+ *
+ * htmx v4 has no hook to override how core resolves an attribute name —
+ * it reads `hx-get` literally. Until an upstream resolver seam exists
+ * (see docs/UPSTREAM_HOOK_PROPOSAL.md), this module makes localized
+ * authoring work by copying each localized attribute to its canonical
+ * name on the same element *before* htmx processes the node:
+ *
+ *   <button lang="es" hx-obtener="/api">  →  + hx-get="/api"
+ *
+ * Design rules (mirroring the loka-js invariants where the mechanism
+ * allows):
+ *
+ * - **The authored attribute is never removed or rewritten** — devtools
+ *   keeps showing what the author wrote. The one exception is an
+ *   author-written canonical `hx-trigger` whose *value* uses localized
+ *   event names (`hx-trigger="clic"`): there is no separate canonical
+ *   target to write to, so the value is translated in place (idempotent —
+ *   the maps are localized → canonical, so a second pass is a no-op).
+ * - **An existing canonical attribute always wins.** If the element
+ *   already has `hx-get`, a localized `hx-obtener` never overwrites it.
+ * - **No vocab, no work.** With no languages registered every function
+ *   here is a cheap no-op, so stock htmx pages pay ~nothing.
+ *
+ * Only attributes in the `hx-` / `sse-` / `ws-` namespaces are ever
+ * considered — the brand prefix is preserved across languages (Phase 8
+ * convention: Spanish writes `hx-obtener`, not `xx-obtener`), so the
+ * prefix doubles as the discovery anchor.
+ */
+/**
+ * Translate localized event names inside an `hx-trigger` value.
+ *
+ * hx-trigger grammar: comma-separated specs, each `eventName[filter]
+ * modifier…`. Only the leading event token of each spec is translated
+ * (preserving an attached `[...]` filter); modifiers like `delay:500ms`,
+ * `from:body`, `once` are language-invariant and left alone. Unknown
+ * tokens pass through untouched, which also makes translation idempotent
+ * (the maps are localized → canonical only).
+ */
+declare function translateTriggerValue(value: string, events: Record<string, string>): string;
+/**
+ * Canonicalize one element's localized htmx attributes in place.
+ * Returns true if any attribute was added or updated.
+ */
+declare function canonicalizeElement(elt: Element): boolean;
+/**
+ * Canonicalize an element and all its descendants. Returns the number of
+ * elements that changed. This is what the htmx extension hook and the
+ * initial document sweep call — htmx processes subtrees, so we mirror
+ * that granularity.
+ */
+declare function canonicalizeTree(root: Element | Document | DocumentFragment | null): number;
+
+/**
+ * htmx extension + auto-sweep wiring.
+ *
+ * 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
+ * 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.
+ *
+ * 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.
+ *
+ * The extension hook alone is not enough for the *initial* page: script
+ * order decides whether our sweep beats htmx's own DOMContentLoaded scan.
+ * `installAutoSweep()` handles that — load this adapter (and vocab
+ * modules) BEFORE the htmx <script> tag, mirroring loka-js's
+ * "orchestrator before libraries" rule, and the sweep listener registers
+ * ahead of htmx's.
+ */
+declare const EXTENSION_NAME = "lokascript-i18n";
+/** Minimal shape of the htmx global we interact with. */
+interface HtmxLike {
+    /** htmx v4 registration entry point. */
+    registerExtension?(name: string, extension: object): void;
+    /** htmx v1/v2 registration entry point. */
+    defineExtension?(name: string, extension: object): void;
+}
+/**
+ * Build the extension object. v4 hooks and the v2 `onEvent` callback are
+ * both present — each API only reads the members it knows about.
+ */
+declare function createExtension(): object;
+/**
+ * Register the extension with an htmx global. Returns which API accepted
+ * it (`'v4'` / `'v2'`) or `null` if the object exposes neither.
+ */
+declare function registerWith(htmx: HtmxLike | undefined | null): 'v4' | 'v2' | 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).
+ *
+ * Returns a cleanup function (mainly for tests).
+ */
+declare function installAutoSweep(doc?: Document): () => void;
+
+/**
+ * Resolver mode — the adapter's mechanism-(c) form, usable today against
+ * the reference-patched htmx build (docs/reference-patches/) and ready
+ * for upstream if the attribute-resolver seam lands.
+ *
+ * Where the default shim CANONICALIZES (copies localized attrs onto the
+ * element), resolver mode answers htmx's attribute lookups directly:
+ * core asks "what should I read for `hx-get` on this element?" and the
+ * resolver returns the localized name actually present (`hx-obtener`)
+ * for the element's language scope. Zero DOM mutation, fully
+ * devtools-faithful — the loka-js ideal.
+ *
+ * Two seams must both be fed (the loka-js lesson): the per-element
+ * resolver answers reads, and `additionalAttributeSelectors` feeds the
+ * document-level discovery scan, which a per-element function cannot
+ * drive. `installResolverMode()` wires both and keeps the selector list
+ * fresh as vocab modules register.
+ *
+ * Scope: value-bearing attributes only. The hx-on colon family stays
+ * with the shim/executor mode — its event name is part of the attribute
+ * NAME, which is a different question than "what name holds this
+ * value". Trigger VALUES (`hx-trigger="clic"`) are also name-level
+ * out-of-scope; keep authoring canonical event values, or pair with
+ * executor mode.
+ */
+/** True while resolver mode owns localization (the shim stands down). */
+declare function isResolverMode(): boolean;
+/** Mainly for tests; installResolverMode() manages this in production. */
+declare function setResolverMode(active: boolean): void;
+/**
+ * The per-element resolver htmx consults on attribute reads:
+ * `(elt, canonicalName) → localized name present on elt, or null`.
+ */
+declare function attributeResolver(elt: Element, name: string): string | null;
+/**
+ * CSS attribute selectors for every registered localized name, for
+ * htmx's discovery scan (`config.additionalAttributeSelectors`). The
+ * hx-on family is excluded — see the module header.
+ */
+declare function additionalAttributeSelectors(): string[];
+interface ResolverConfigurableHtmx {
+    config?: {
+        attributeResolver?: ((elt: Element, name: string) => string | null) | null;
+        additionalAttributeSelectors?: string[];
+    };
+}
+/**
+ * Wire resolver mode into a (reference-patched) htmx instance: install
+ * the resolver, feed the discovery selectors, keep them fresh on vocab
+ * registration, and stand the canonicalization shim down. Returns an
+ * uninstall function that restores shim behavior.
+ */
+declare function installResolverMode(htmx: ResolverConfigurableHtmx): () => void;
+
+/**
+ * hx-on body support — opt-in "executor mode".
+ *
+ * Upstream htmx evals `hx-on:*` bodies as JavaScript. In the hyperfixi
+ * ecosystem the convention is hyperscript bodies (`hx-on:click="toggle
+ * .active on me"`), which htmx's JS eval cannot run — and localized
+ * bodies (`hx-en:clic="alternar .active"`) doubly so. This module lets a
+ * page opt in to hyperscript-body semantics by configuring an executor:
+ *
+ *   setBodyExecutor((code, elt, evt) => _hyperscript.evaluate(code, { me: elt, event: evt }))
+ *   setBodyTranslator((body, lang) => HyperscriptI18n.preprocess(body, lang))
+ *
+ * With an executor set, the adapter CLAIMS every hx-on-family attribute
+ * (localized-named or canonical-named — all bodies are treated as
+ * hyperscript; mixed JS/hyperscript pages have no reliable detection):
+ * it installs a real event listener that runs the (lazily translated)
+ * body through the executor, and keeps htmx away from it:
+ *
+ * - 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.
+ *
+ * With no executor set (the default), none of this runs and bodies keep
+ * upstream JS semantics — the behavior-preservation invariant.
+ *
+ * Translation is lazy (first event fire, memoized) so a translator that
+ * 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.
+ */
+type BodyExecutor = (code: string, elt: Element, evt: Event) => unknown;
+type BodyTranslator = (body: string, lang: string) => string;
+/** Configure the body executor. Setting/clearing it notifies subscribers. */
+declare function setBodyExecutor(fn: BodyExecutor | null): void;
+/** Configure the body translator (localized body → English hyperscript). */
+declare function setBodyTranslator(fn: BodyTranslator | null): void;
+declare function hasBodyExecutor(): boolean;
+declare function hasBodyTranslator(): boolean;
+/** Subscribe to executor changes. Returns an unsubscribe fn. */
+declare function onBodyHooksChanged(listener: () => void): () => void;
+/**
+ * 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).
+ *
+ * `lang` is the element's language at claim time — used for lazy body
+ * translation. `events` is the language's event-name map (for the
+ * listener's event name; the shorthand/unknown cases pass through).
+ */
+declare function claimHxOnAttribute(elt: Element, attrName: string, lang: string, events: Record<string, string>): boolean;
+/**
+ * Auto-detect body hooks from page globals — called by the browser entry
+ * at load and again at DOMContentLoaded. Never overwrites hooks that
+ * were set explicitly.
+ *
+ * - `window._hyperscript` → executor (original _hyperscript; pairs with
+ *   `@lokascript/hyperscript-adapter` for multilingual `_=` too)
+ * - `window.HyperscriptI18n.preprocess` → translator (the
+ *   hyperscript-adapter browser bundles expose exactly this)
+ */
+declare function autoDetectBodyHooks(win: object): void;
+/** Reset all body-hook state. Mainly for tests. */
+declare function resetBodyHooks(): void;
+
+export { type BodyExecutor, type BodyTranslator, EXTENSION_NAME, type HtmxLike, type HtmxVocab, type VocabPayload, additionalAttributeSelectors, attributeResolver, autoDetectBodyHooks, canonicalizeElement, canonicalizeTree, claimHxOnAttribute, createExtension, hasAnyVocab, hasBodyExecutor, hasBodyTranslator, installAutoSweep, installResolverMode, isLangRegistered, isResolverMode, langOf, normLang, onBodyHooksChanged, onVocabUpdate, register, registerWith, resetBodyHooks, resetRegistry, setBodyExecutor, setBodyTranslator, setResolverMode, translateTriggerValue, vocabFor };