@lenne.tech/nuxt-extensions 1.13.0 → 1.15.0

package/CLAUDE.md

@@ -186,22 +186,42 @@ export default defineNuxtRouteMiddleware((to) => {
 force-patched on hydration (vuejs/core#9083) while the label's `for` — a prop on reka-ui's
 `Label` component — is not. The label keeps the stale value and the association breaks.
 
-**What this module adds:** `runtime/plugins/form-label-association.client.ts` re-points
-dangling Nuxt UI field labels at the control in their own field, at `app:mounted` and for a
-bounded window afterwards (`maxRepairMs`, default 1500 ms).
+**What this module adds:** `runtime/plugins/form-label-association.client.ts` repairs three
+associations inside Nuxt UI fields whose label no longer resolves — `<label for>`,
+`aria-labelledby` on group roots, and `aria-describedby` on controls — at `app:mounted`, for a
+bounded window afterwards (`maxRepairMs`, default 1500 ms), and via a `MutationObserver` for
+subtrees that hydrate later (`observeDeferred`, default on).
 
 **What this means when you debug a consuming project:**
 
-- **A `for` attribute that changes after mount is this plugin, not a bug.** It logs a
-  `console.warn` in development naming how many labels it repaired.
-- **It refuses to guess.** The repair only fires when the field holds exactly one eligible
-  control. Radio and checkbox groups, hidden form-value proxies, `aria-hidden`/`disabled`
-  controls and button-only fields are skipped on purpose — binding a group caption to its
-  first option would submit a value the user never chose.
-- **Only Nuxt UI's own field labels are touched** (`label[data-slot="label"][for]`). Labels
-  your application wrote are never rewritten.
-- **Do not "fix" a skipped group by loosening the rule.** Inert beats wrong here; the correct
-  fix for a group is an SSR-stable id at the source.
+- **A `for` / `aria-labelledby` / `aria-describedby` that changes after mount is this plugin, not
+  a bug.** It logs once per page in development, naming the repaired fields. Repaired labels
+  carry `data-lt-label-repaired`.
+- **`aria-describedby` is the one people miss.** The error container's id IS force-patched on
+  hydration; the reference to it is not, so validation errors are visible but never announced
+  (WCAG 3.3.1 / 3.3.3). If a project reports "screen reader stays silent on form errors", check
+  whether this plugin is disabled before looking anywhere else.
+- **It refuses to guess.** The `for` repair fires only when the field holds exactly one eligible
+  control. Groups get `aria-labelledby` instead — a `for` on a `<div role="radiogroup">` is inert
+  however carefully it is chosen.
+- **`disabled` and `readonly` fields ARE repaired**, and must stay that way. They are rendered
+  and announced, so WCAG 1.3.1 / 4.1.2 apply unchanged; WCAG's only carve-out for inactive
+  components is contrast. Excluding `disabled` was tried in 1.13.0 and reproduced the very defect
+  the plugin repairs on every read-only form — and additionally mis-bound partially disabled radio
+  groups, so a click on one caption selected a different option.
+- **`[data-hidden]` alone does NOT mean "reka proxy".** The missing `id` is what means that.
+  `UFileUpload` renders the user's real file input through the same mechanism and stamps the
+  field id on it — excluding it unqualified takes out the field's only control.
+- **Only Nuxt UI's own field labels are touched** (`label[data-slot="label"][for]`). Labels your
+  application wrote are never rewritten, and naming the application set itself is never
+  overwritten.
+- **Never assert on a generated `for` or `id` value** in tests. Assert on the accessible name —
+  the ids come from `useId()` and are neither stable nor meaningful, and this plugin rewrites them.
+- **If you change a selector in that file, run the mutation check.** `test/upstream-dom-contract.test.ts`
+  pins what reka-ui and @nuxt/ui actually render (both are devDependencies for exactly this
+  reason); `test/form-label-association.test.ts` pins our own pairing rules. Every guard has a
+  case that fails when the guard is removed. The 1.13.0 defect shipped because a fixture was
+  invented rather than observed, and the invented selector matched the invented fixture.
 - This is a **stopgap** for a framework-level divergence. Opt out with
   `ltExtensions.formLabelAssociation.enabled: false`.
 
@@ -239,5 +259,14 @@ fields at `app:beforeMount` and restores them at `app:mounted`, dispatching a sy
 1. **ALWAYS read source code** in `dist/runtime/` to understand available composables and components
 2. **Use `useLtAuth()`** for authentication — never implement auth manually
 3. **Check existing composables** before creating new ones — this module may already provide what you need
-4. **Peer dependencies** (`better-auth`, `@better-auth/passkey`, `tus-js-client`) must be installed in the consuming project
+4. **Peer dependencies** (`better-auth`, `@better-auth/passkey`, `tus-js-client`) must be installed in the consuming project.
+   `better-auth` and `@better-auth/passkey` are pinned to **`>=1.7.1 <1.8.0`** — deliberately not a caret.
+   **They move in lock-step with `@lenne.tech/nest-server`.** better-auth is one protocol with two ends;
+   this module is the client end, nest-server the server end, and both declare the *same* narrow range.
+   Raising it means raising it in **both** framework repos and pinning the new version in **both** starters,
+   in one release. Never half of it, not even "just to unblock the frontend" — a split resolves as api on one
+   minor and app on another, 2FA activation fails at runtime, and *both* repos' `check` stays green because
+   each is internally consistent and only the assembled workspace has both halves.
+   `test/peer-dependency-ranges.test.ts` guards the declared range against the version actually tested;
+   `test/better-auth-contract.test.ts` pins the consumed better-auth surface.
 5. **AI types collision pitfall:** `LtAiPromptInput` is the CRUD input for the user-facing `LtAiPrompt` entity (used by `useLtAiPrompts().create/update`). The execution payload for `useLtAi.prompt()` / `.promptStream()` is `LtAiPromptRunInput`. Do not conflate them.

package/README.md

@@ -23,16 +23,48 @@ Reusable Nuxt 4 composables, components, and Better-Auth integration for lenne.t
 > npx @lenne.tech/cli fullstack init my-project
 > ```
 
+## Requirements
+
+| Dependency | Required version | Notes |
+|---|---|---|
+| Node | `>= 22` | |
+| Nuxt | `^4.0.0` | |
+| `better-auth` | `>=1.7.1 <1.8.0` | **required peer** — pin it, see below |
+| `@better-auth/passkey` | `>=1.7.1 <1.8.0` | optional peer, passkey/WebAuthn only |
+| `tus-js-client` | `>=4.0.0` | optional peer, resumable uploads only |
+| `@lenne.tech/nest-server` | `>= 11.37.0` | **only if you use the backend** — see the lock-step rule |
+
+**Why `better-auth` is pinned to one minor line, and why you must not widen it:**
+better-auth is one protocol with two ends. This module is the client end and
+`@lenne.tech/nest-server` is the server end, and they must resolve the **same**
+better-auth minor. better-auth breaks in *minor* releases — 1.7 removed subpath
+exports and changed the 2FA response shape — so a caret (`^1.7.1`) would re-open the
+hole at 1.8. If the api and the app drift apart, 2FA activation fails at runtime with a
+generic client error while **both** projects' checks stay green: each is internally
+consistent, and only the assembled workspace has both halves.
+
+Raising better-auth therefore means raising it in `@lenne.tech/nest-server` **and**
+`@lenne.tech/nuxt-extensions` in one step.
+
 ## Installation
 
 ```bash
-npm install @lenne.tech/nuxt-extensions better-auth
+npm install @lenne.tech/nuxt-extensions better-auth@1.7.1
 # Optional: For passkey support
-npm install @better-auth/passkey
+npm install @better-auth/passkey@1.7.1
 # Optional: For TUS file uploads
 npm install tus-js-client
 ```
 
+In a fullstack monorepo, pin it workspace-wide so the api and the app cannot drift:
+
+```yaml
+# pnpm-workspace.yaml
+overrides:
+  better-auth: 1.7.1
+  '@better-auth/passkey': 1.7.1
+```
+
 ## Features
 
 - **Better-Auth Integration** - Login, 2FA, Passkey/WebAuthn support
@@ -190,27 +222,39 @@ target, not a convenience. Tests using `getByRole('textbox', { name })` stop fin
 
 ### What the repair does
 
-After mount, and for a bounded window afterwards, every Nuxt UI field label whose target does
-not resolve is re-pointed at the control in its own field.
+After mount, and for a bounded window afterwards, three associations are repaired inside each
+Nuxt UI field whose label no longer resolves:
+
+| Association | Repaired how | Why it needs its own path |
+|---|---|---|
+| `<label for>` → control | re-pointed at the field's control | `for` carries **both** the accessible name and click-to-focus |
+| `aria-labelledby` on a group | caption id minted, group pointed at it | A radio group's id sits on a `<div role="radiogroup">`, and `for` only resolves against labelable elements — there it is inert however carefully it is chosen |
+| `aria-describedby` → error / help | dangling tokens re-pointed, token-wise | The error container's id **is** force-patched on hydration; the reference to it is not. So the message is visible and never announced (WCAG 3.3.1 / 3.3.3) |
 
 **It refuses to guess.** A repair that fires where it should not is worse than the defect: a
-dangling label is inert and visible, a mis-pointed one is confidently wrong and silent, and
-on a radio or checkbox a click on the caption would change a value the user never chose. So
-the repair only fires when the field contains exactly **one** eligible control. Skipped
-deliberately:
+dangling label is inert and visible, a mis-pointed one is confidently wrong and silent, and on a
+radio or checkbox a click on the caption would change a value the user never chose. So the `for`
+repair only fires when the field contains exactly **one** eligible control. Skipped deliberately:
 
 | Case | Why |
 |------|-----|
-| Radio / checkbox groups | One field root, many controls — binding every caption to the first option would submit a value nobody picked |
-| Hidden form-value proxies, `aria-hidden`, `disabled` | Not the user's control; pointing at one restores neither the name nor the click |
-| Fields whose only visible control is a `button` | Nothing safe to point at |
+| Radio / checkbox groups | One field root, many controls — binding every caption to one item would submit a value nobody picked. Named via `aria-labelledby` instead |
+| Reka's submit proxy (`[data-hidden]` with no `id`) | Not the user's control. The missing id is what identifies it — Nuxt UI's `UFileUpload` renders the *real* file input the same way, but stamps the field id on it |
+| Anything `aria-hidden`, `hidden`, `type="hidden"` or `display:none` | Outside the accessibility tree, so a label pointing there would carry no name — the repair would report success and change nothing |
+| A control that already has a working label | Multiple `<label>`s **concatenate** into one accessible name, so a second one produces a name matching no visible text |
+| An id that is not unique in the document | `for` resolves through `getElementById`, which returns the *first* match — the label's click would go to the other element |
 | Labels your application wrote | Only Nuxt UI's own field labels (`data-slot="label"`) are touched |
 
-`for` is repaired rather than `aria-labelledby` added, because `for` carries **both** the
-accessible name and click-to-focus.
+**`disabled` and `readonly` fields ARE repaired.** They are rendered, stay in the accessibility
+tree and are announced, so WCAG 1.3.1 / 4.1.2 apply unchanged — and WCAG's only carve-out for
+inactive components is contrast (1.4.3 / 1.4.11); there is no naming exemption. For a disabled
+field the repair restores the **name only**, since a disabled control prevents click dispatch and
+is not focusable. On a read-only form that is the whole value: it is a page people read rather
+than operate. Excluding `disabled` was tried in 1.13.0 and reproduced the very defect this plugin
+repairs on every read-only form.
 
-**This is a repair, not a cure.** The real fix is for the id not to diverge; this exists
-because the divergence sits in the framework stack rather than in any one application.
+**This is a repair, not a cure.** The real fix is for the id not to diverge; this exists because
+the divergence sits in the framework stack rather than in any one application.
 
 ### Opting out
 
@@ -219,15 +263,24 @@ export default defineNuxtConfig({
   ltExtensions: {
     formLabelAssociation: {
       enabled: false,
-      // or keep it on and only change how long deferred subtrees are waited for:
-      // maxRepairMs: 3000,
+      // Or keep it on and tune the two knobs:
+      // maxRepairMs: 3000,        // window for deferred subtrees; clamped to [0, 30000]
+      // observeDeferred: false,   // drop the MutationObserver for hydrate-on-visible content
     },
   },
 });
 ```
 
-Two real reasons to: your application assigns `for` itself and depends on those exact values,
-or your tests assert on literal `for` / `id` strings rather than on the accessible name.
+Two real reasons to turn it off: your application assigns `for` itself and depends on those exact
+values, or your tests assert on literal `for` / `id` strings rather than on the accessible name.
+Fix the second reason instead — assert on the accessible name, which is what a user perceives.
+
+### Debugging it in a consuming project
+
+- **A `for`, `aria-labelledby` or `aria-describedby` that changes after mount is this plugin.**
+  In development it logs once per page, naming the fields it repaired.
+- Repaired labels carry `data-lt-label-repaired`, so an E2E suite can assert the repair count is
+  zero once the upstream divergence is fixed — and delete the plugin at that point.
 
 ## Pre-Hydration Input Preservation
 

package/dist/module.d.mts

@@ -3,7 +3,7 @@ import { LtExtensionsModuleOptions } from '../dist/runtime/types/index.js';
 export * from '../dist/runtime/types/index.js';
 
 declare const name = "@lenne.tech/nuxt-extensions";
-declare const version = "1.13.0";
+declare const version = "1.15.0";
 declare const configKey = "ltExtensions";
 declare const DEFAULT_LT_AUTH_STATE_COOKIE = "lt-auth-state";
 declare const DEFAULT_LT_JWT_TOKEN_COOKIE = "lt-jwt-token";

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "configKey": "ltExtensions",
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,7 +1,8 @@
 import { defineNuxtModule, createResolver, tryResolveModule, addImports, addComponent, addPlugin, addRouteMiddleware } from '@nuxt/kit';
+import { pathToFileURL } from 'node:url';
 
 const name = "@lenne.tech/nuxt-extensions";
-const version = "1.13.0";
+const version = "1.15.0";
 const configKey = "ltExtensions";
 const DEFAULT_LT_AUTH_STATE_COOKIE = "lt-auth-state";
 const DEFAULT_LT_JWT_TOKEN_COOKIE = "lt-jwt-token";
@@ -74,7 +75,7 @@ const module$1 = defineNuxtModule({
       preHydrationInput: { ...defaultOptions.preHydrationInput, ...options.preHydrationInput },
       tus: { ...defaultOptions.tus, ...options.tus }
     };
-    const passkeyAvailable = !!await tryResolveModule("@better-auth/passkey/client", new URL(import.meta.url));
+    const passkeyAvailable = !!await tryResolveModule("@better-auth/passkey/client", [new URL(import.meta.url), pathToFileURL(`${nuxt.options.rootDir}/`)]);
     if (!passkeyAvailable) {
       const passkeyStub = resolve("./runtime/lib/passkey-stub");
       nuxt.options.alias["@better-auth/passkey/client"] = passkeyStub;
@@ -130,7 +131,8 @@ const module$1 = defineNuxtModule({
       },
       formLabelAssociation: {
         enabled: resolvedOptions.formLabelAssociation?.enabled ?? true,
-        maxRepairMs: resolvedOptions.formLabelAssociation?.maxRepairMs ?? 1500
+        maxRepairMs: resolvedOptions.formLabelAssociation?.maxRepairMs ?? 1500,
+        observeDeferred: resolvedOptions.formLabelAssociation?.observeDeferred ?? true
       },
       preHydrationInput: {
         enabled: resolvedOptions.preHydrationInput?.enabled ?? true,
@@ -232,11 +234,14 @@ const module$1 = defineNuxtModule({
     }
     nuxt.options.build.transpile.push(resolve("./runtime"));
     nuxt.options.build.transpile.push("tus-js-client");
-    console.log(`[${name}] Module loaded with config:`, {
-      auth: resolvedOptions.auth?.enabled ? "enabled" : "disabled",
-      i18nAutoMerge: resolvedOptions.i18n?.autoMerge,
-      tusEndpoint: resolvedOptions.tus?.defaultEndpoint
-    });
+    console.log(`[${name}] v${version}`);
+    if (nuxt.options.dev) {
+      console.log(`[${name}] Module loaded with config:`, {
+        auth: resolvedOptions.auth?.enabled ? "enabled" : "disabled",
+        i18nAutoMerge: resolvedOptions.i18n?.autoMerge,
+        tusEndpoint: resolvedOptions.tus?.defaultEndpoint
+      });
+    }
   }
 });
 

package/dist/runtime/lib/auth-client.d.ts

@@ -184,8 +184,8 @@ export declare function createLtAuthClient(config?: LtAuthClientConfig): {
             }>;
         }>;
     };
-    passkey: any;
-    admin: any;
+    passkey: Record<string, unknown> | undefined;
+    admin: Record<string, unknown> | undefined;
     $Infer: {
         Session: {
             user: import("better-auth").StripEmptyObjects<{
@@ -302,36 +302,7 @@ export declare function createLtAuthClient(config?: LtAuthClientConfig): {
     changePassword: (params: {
         currentPassword: string;
         newPassword: string;
-    }, options?: any) => Promise<(Omit<{
-        token: string | null;
-        user: {
-            id: string;
-            createdAt: Date;
-            updatedAt: Date;
-            email: string;
-            emailVerified: boolean;
-            name: string;
-            image?: string | null | undefined;
-        } & Record<string, any> & {
-            id: string;
-            createdAt: Date;
-            updatedAt: Date;
-            email: string;
-            emailVerified: boolean;
-            name: string;
-            image?: string | null | undefined;
-        };
-    }, "user"> & {
-        user: import("better-auth").StripEmptyObjects<{
-            id: string;
-            createdAt: Date;
-            updatedAt: Date;
-            email: string;
-            emailVerified: boolean;
-            name: string;
-            image?: string | null | undefined;
-        }>;
-    }) | {
+    }, options?: unknown) => Promise<{
         data: Omit<{
             token: string | null;
             user: {
@@ -378,9 +349,7 @@ export declare function createLtAuthClient(config?: LtAuthClientConfig): {
     resetPassword: (params: {
         newPassword: string;
         token: string;
-    }, options?: any) => Promise<{
-        status: boolean;
-    } | {
+    }, options?: unknown) => Promise<{
         data: {
             status: boolean;
         };
@@ -402,30 +371,7 @@ export declare function createLtAuthClient(config?: LtAuthClientConfig): {
             email: string;
             password: string;
             rememberMe?: boolean;
-        }, options?: any) => Promise<(Omit<{
-            redirect: boolean;
-            token: string;
-            url?: string | undefined;
-            user: {
-                id: string;
-                createdAt: Date;
-                updatedAt: Date;
-                email: string;
-                emailVerified: boolean;
-                name: string;
-                image?: string | null | undefined | undefined;
-            };
-        }, "user"> & {
-            user: import("better-auth").StripEmptyObjects<{
-                id: string;
-                createdAt: Date;
-                updatedAt: Date;
-                email: string;
-                emailVerified: boolean;
-                name: string;
-                image?: string | null | undefined;
-            }>;
-        }) | {
+        }, options?: unknown) => Promise<{
             data: Omit<{
                 redirect: boolean;
                 token: string;
@@ -464,7 +410,7 @@ export declare function createLtAuthClient(config?: LtAuthClientConfig): {
          * Sign in with passkey (pass through to base client - provided by passkeyClient plugin)
          * @see https://www.better-auth.com/docs/plugins/passkey
          */
-        passkey: any;
+        passkey: ((...args: unknown[]) => Promise<unknown>) | undefined;
         social: <FetchOptions extends import("better-auth").ClientFetchOption<Partial<{
             provider: (string & {}) | "linear" | "huggingface" | "github" | "apple" | "atlassian" | "cognito" | "discord" | "facebook" | "figma" | "microsoft" | "google" | "slack" | "spotify" | "twitch" | "twitter" | "dropbox" | "kick" | "linkedin" | "gitlab" | "tiktok" | "reddit" | "roblox" | "salesforce" | "vk" | "zoom" | "notion" | "kakao" | "naver" | "line" | "paybin" | "paypal" | "polar" | "railway" | "vercel" | "wechat";
             callbackURL?: string | undefined;
@@ -577,49 +523,7 @@ export declare function createLtAuthClient(config?: LtAuthClientConfig): {
             email: string;
             name: string;
             password: string;
-        } & Record<string, unknown>, options?: any) => Promise<(Omit<{
-            token: null;
-            user: {
-                id: string;
-                createdAt: Date;
-                updatedAt: Date;
-                email: string;
-                emailVerified: boolean;
-                name: string;
-                image?: string | null | undefined | undefined;
-            };
-        }, "user"> & {
-            user: import("better-auth").StripEmptyObjects<{
-                id: string;
-                createdAt: Date;
-                updatedAt: Date;
-                email: string;
-                emailVerified: boolean;
-                name: string;
-                image?: string | null | undefined;
-            }>;
-        }) | (Omit<{
-            token: string;
-            user: {
-                id: string;
-                createdAt: Date;
-                updatedAt: Date;
-                email: string;
-                emailVerified: boolean;
-                name: string;
-                image?: string | null | undefined | undefined;
-            };
-        }, "user"> & {
-            user: import("better-auth").StripEmptyObjects<{
-                id: string;
-                createdAt: Date;
-                updatedAt: Date;
-                email: string;
-                emailVerified: boolean;
-                name: string;
-                image?: string | null | undefined;
-            }>;
-        }) | {
+        } & Record<string, unknown>, options?: unknown) => Promise<{
             data: (Omit<{
                 token: null;
                 user: {
@@ -674,7 +578,34 @@ export declare function createLtAuthClient(config?: LtAuthClientConfig): {
             };
         }>;
     };
-    twoFactor: any;
+    twoFactor: {
+        /**
+         * Disable 2FA (password is hashed before sending)
+         */
+        disable: (params: {
+            password: string;
+        }, options?: unknown) => Promise<unknown>;
+        /**
+         * Enable 2FA (password is hashed before sending)
+         */
+        enable: (params: {
+            password: string;
+        }, options?: unknown) => Promise<unknown>;
+        /**
+         * Generate backup codes (password is hashed before sending)
+         */
+        generateBackupCodes: (params: {
+            password: string;
+        }, options?: unknown) => Promise<unknown>;
+        /**
+         * Verify TOTP code (pass through to base client)
+         */
+        verifyTotp: ((...args: unknown[]) => Promise<unknown>) | undefined;
+        /**
+         * Verify backup code (pass through to base client)
+         */
+        verifyBackupCode: ((...args: unknown[]) => Promise<unknown>) | undefined;
+    };
     verifyEmail: <FetchOptions extends import("better-auth").ClientFetchOption<never, Partial<{
         token: string;
         callbackURL?: string | undefined;

package/dist/runtime/lib/auth-client.js

@@ -78,15 +78,15 @@ export function createLtAuthClient(config = {}) {
     },
     plugins
   });
+  const withPlugins = baseClient;
+  const signInWithPlugins = baseClient.signIn;
   return {
     // Spread all base client properties and methods
     ...baseClient,
     // Explicitly pass through methods not captured by spread operator
     useSession: baseClient.useSession,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    passkey: baseClient.passkey,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    admin: baseClient.admin,
+    passkey: withPlugins.passkey,
+    admin: withPlugins.admin,
     $Infer: baseClient.$Infer,
     $fetch: baseClient.$fetch,
     $store: baseClient.$store,
@@ -94,7 +94,6 @@ export function createLtAuthClient(config = {}) {
     /**
      * Change password for an authenticated user (both passwords are hashed)
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     changePassword: async (params, options) => {
       const [hashedCurrent, hashedNew] = await Promise.all([ltSha256(params.currentPassword), ltSha256(params.newPassword)]);
       return baseClient.changePassword?.({ currentPassword: hashedCurrent, newPassword: hashedNew }, options);
@@ -102,7 +101,6 @@ export function createLtAuthClient(config = {}) {
     /**
      * Reset password with token (new password is hashed before sending)
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     resetPassword: async (params, options) => {
       const hashedPassword = await ltSha256(params.newPassword);
       return baseClient.resetPassword?.({ newPassword: hashedPassword, token: params.token }, options);
@@ -113,7 +111,6 @@ export function createLtAuthClient(config = {}) {
       /**
        * Sign in with email and password (password is hashed before sending)
        */
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       email: async (params, options) => {
         const hashedPassword = await ltSha256(params.password);
         return baseClient.signIn.email({ ...params, password: hashedPassword }, options);
@@ -122,8 +119,7 @@ export function createLtAuthClient(config = {}) {
        * Sign in with passkey (pass through to base client - provided by passkeyClient plugin)
        * @see https://www.better-auth.com/docs/plugins/passkey
        */
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      passkey: baseClient.signIn.passkey
+      passkey: signInWithPlugins.passkey
     },
     // Explicitly pass through signOut (not captured by spread operator)
     signOut: baseClient.signOut,
@@ -133,7 +129,6 @@ export function createLtAuthClient(config = {}) {
       /**
        * Sign up with email and password (password is hashed before sending)
        */
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       email: async (params, options) => {
         const hashedPassword = await ltSha256(params.password);
         return baseClient.signUp.email({ ...params, password: hashedPassword }, options);
@@ -141,42 +136,36 @@ export function createLtAuthClient(config = {}) {
     },
     // Override twoFactor to hash passwords (provided by twoFactorClient plugin)
     twoFactor: {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      ...baseClient.twoFactor,
+      ...withPlugins.twoFactor,
       /**
        * Disable 2FA (password is hashed before sending)
        */
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       disable: async (params, options) => {
         const hashedPassword = await ltSha256(params.password);
-        return baseClient.twoFactor.disable({ password: hashedPassword }, options);
+        return withPlugins.twoFactor?.disable({ password: hashedPassword }, options);
       },
       /**
        * Enable 2FA (password is hashed before sending)
        */
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       enable: async (params, options) => {
         const hashedPassword = await ltSha256(params.password);
-        return baseClient.twoFactor.enable({ password: hashedPassword }, options);
+        return withPlugins.twoFactor?.enable({ password: hashedPassword }, options);
       },
       /**
        * Generate backup codes (password is hashed before sending)
        */
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       generateBackupCodes: async (params, options) => {
         const hashedPassword = await ltSha256(params.password);
-        return baseClient.twoFactor.generateBackupCodes({ password: hashedPassword }, options);
+        return withPlugins.twoFactor?.generateBackupCodes({ password: hashedPassword }, options);
       },
       /**
        * Verify TOTP code (pass through to base client)
        */
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      verifyTotp: baseClient.twoFactor.verifyTotp,
+      verifyTotp: withPlugins.twoFactor?.verifyTotp,
       /**
        * Verify backup code (pass through to base client)
        */
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      verifyBackupCode: baseClient.twoFactor.verifyBackupCode
+      verifyBackupCode: withPlugins.twoFactor?.verifyBackupCode
     }
   };
 }

package/dist/runtime/lib/passkey-stub.d.ts

@@ -11,6 +11,16 @@
  * so the factory below is normally never called. It stays a no-op (rather than
  * throwing) to keep the direct `createLtAuthClient()` entry point working, whose
  * own `enablePasskey` default is `true`.
+ *
+ * WHY this file exports more than `passkeyClient`:
+ * the alias is installed into `nuxt.options.alias` and `nuxt.options.nitro.alias`,
+ * which rewrites the specifier for the WHOLE consumer app — not just for our
+ * `auth-client.ts`. A consumer (or another dependency) importing any other name
+ * from `@better-auth/passkey/client` would then hit
+ * `"PASSKEY_ERROR_CODES" is not exported by …/passkey-stub` — the same class of
+ * unresolved-export build failure this stub exists to prevent, merely relocated.
+ * So the stub mirrors the real package's full export surface.
+ * `test/optional-peers.test.ts` pins that surface against the real package.
  */
 /**
  * No-op replacement for the real `passkeyClient()` Better-Auth client plugin.
@@ -21,3 +31,86 @@
 export declare function passkeyClient(): {
     id: "lt-passkey-unavailable";
 };
+/**
+ * Mirror of the real package's error-code table.
+ *
+ * Frozen and value-complete so a consumer that reads a code for a message or an
+ * equality check still gets a defined value instead of a `TypeError` on
+ * `undefined`. The codes are the contract; the messages are best-effort copies.
+ */
+export declare const PASSKEY_ERROR_CODES: Readonly<{
+    AUTH_CANCELLED: {
+        code: string;
+        message: string;
+    };
+    AUTHENTICATION_FAILED: {
+        code: string;
+        message: string;
+    };
+    CHALLENGE_NOT_FOUND: {
+        code: string;
+        message: string;
+    };
+    FAILED_TO_UPDATE_PASSKEY: {
+        code: string;
+        message: string;
+    };
+    FAILED_TO_VERIFY_REGISTRATION: {
+        code: string;
+        message: string;
+    };
+    PASSKEY_NOT_FOUND: {
+        code: string;
+        message: string;
+    };
+    PREVIOUSLY_REGISTERED: {
+        code: string;
+        message: string;
+    };
+    REGISTRATION_CANCELLED: {
+        code: string;
+        message: string;
+    };
+    RESOLVE_USER_REQUIRED: {
+        code: string;
+        message: string;
+    };
+    RESOLVED_USER_INVALID: {
+        code: string;
+        message: string;
+    };
+    SESSION_REQUIRED: {
+        code: string;
+        message: string;
+    };
+    UNABLE_TO_CREATE_SESSION: {
+        code: string;
+        message: string;
+    };
+    UNKNOWN_ERROR: {
+        code: string;
+        message: string;
+    };
+    USER_NOT_FOUND: {
+        code: string;
+        message: string;
+    };
+    YOU_ARE_NOT_ALLOWED_TO_REGISTER_THIS_PASSKEY: {
+        code: string;
+        message: string;
+    };
+}>;
+/**
+ * No-op replacement for the real `getPasskeyActions()`.
+ *
+ * Every action rejects rather than resolving falsely: a passkey ceremony that
+ * silently "succeeds" without the package would leave the caller believing a
+ * credential exists. The rejection names the missing dependency.
+ */
+export declare function getPasskeyActions(..._args: unknown[]): {
+    addPasskey: () => Promise<never>;
+    deletePasskey: () => Promise<never>;
+    listUserPasskeys: () => Promise<never>;
+    signInPasskey: () => Promise<never>;
+    updatePasskey: () => Promise<never>;
+};

package/dist/runtime/lib/passkey-stub.js

@@ -1,10 +1,50 @@
 let warned = false;
-export function passkeyClient() {
-  if (!warned) {
-    warned = true;
-    console.warn(
-      '[@lenne.tech/nuxt-extensions] Passkey support is unavailable: the optional peer dependency "@better-auth/passkey" is not installed. Install it to use passkeys, or pass `enablePasskey: false` to createLtAuthClient() to silence this warning.'
-    );
+function warnOnce(entryPoint) {
+  if (warned) {
+    return;
   }
+  warned = true;
+  console.warn(
+    `[@lenne.tech/nuxt-extensions] Passkey support is unavailable: the optional peer dependency "@better-auth/passkey" is not installed. Install it to use passkeys, or pass \`enablePasskey: false\` to createLtAuthClient() to silence this warning. (reached via ${entryPoint})`
+  );
+}
+export function passkeyClient() {
+  warnOnce("passkeyClient()");
   return { id: "lt-passkey-unavailable" };
 }
+export const PASSKEY_ERROR_CODES = Object.freeze({
+  AUTH_CANCELLED: { code: "AUTH_CANCELLED", message: "Auth cancelled" },
+  AUTHENTICATION_FAILED: { code: "AUTHENTICATION_FAILED", message: "Authentication failed" },
+  CHALLENGE_NOT_FOUND: { code: "CHALLENGE_NOT_FOUND", message: "Challenge not found" },
+  FAILED_TO_UPDATE_PASSKEY: { code: "FAILED_TO_UPDATE_PASSKEY", message: "Failed to update passkey" },
+  FAILED_TO_VERIFY_REGISTRATION: { code: "FAILED_TO_VERIFY_REGISTRATION", message: "Failed to verify registration" },
+  PASSKEY_NOT_FOUND: { code: "PASSKEY_NOT_FOUND", message: "Passkey not found" },
+  PREVIOUSLY_REGISTERED: { code: "PREVIOUSLY_REGISTERED", message: "Previously registered" },
+  REGISTRATION_CANCELLED: { code: "REGISTRATION_CANCELLED", message: "Registration cancelled" },
+  RESOLVE_USER_REQUIRED: {
+    code: "RESOLVE_USER_REQUIRED",
+    message: "Passkey registration requires either an authenticated session or a resolveUser callback when requireSession is false"
+  },
+  RESOLVED_USER_INVALID: { code: "RESOLVED_USER_INVALID", message: "Resolved user is invalid" },
+  SESSION_REQUIRED: { code: "SESSION_REQUIRED", message: "Passkey registration requires an authenticated session" },
+  UNABLE_TO_CREATE_SESSION: { code: "UNABLE_TO_CREATE_SESSION", message: "Unable to create session" },
+  UNKNOWN_ERROR: { code: "UNKNOWN_ERROR", message: "Unknown error" },
+  USER_NOT_FOUND: { code: "USER_NOT_FOUND", message: "User not found" },
+  YOU_ARE_NOT_ALLOWED_TO_REGISTER_THIS_PASSKEY: {
+    code: "YOU_ARE_NOT_ALLOWED_TO_REGISTER_THIS_PASSKEY",
+    message: "You are not allowed to register this passkey"
+  }
+});
+export function getPasskeyActions(..._args) {
+  warnOnce("getPasskeyActions()");
+  const unavailable = async () => {
+    throw new Error('[@lenne.tech/nuxt-extensions] Passkey action unavailable: the optional peer dependency "@better-auth/passkey" is not installed.');
+  };
+  return {
+    addPasskey: unavailable,
+    deletePasskey: unavailable,
+    listUserPasskeys: unavailable,
+    signInPasskey: unavailable,
+    updatePasskey: unavailable
+  };
+}

package/dist/runtime/plugins/form-label-association.client.d.ts

@@ -78,5 +78,50 @@
  * @returns how many labels were repaired.
  */
 export declare function repairDanglingLabels(root: Document | ParentNode): number;
+/**
+ * Name composite widgets whose label cannot be repaired with `for`.
+ *
+ * A `<div role="radiogroup">` is not labelable, so the `for` repair above skips it and leaves
+ * the group with no accessible name at all — the group's caption stays in the tree as loose
+ * text, and a screen reader announces the radiogroup unnamed. `aria-labelledby` is the correct
+ * instrument here: it names the group without touching any item, so it cannot mis-select
+ * anything, which makes it strictly safer than the `for` repair.
+ *
+ * Gated exactly like `for`: one candidate root per field, and only when the label's own `for`
+ * does not already resolve.
+ *
+ * @returns how many group roots were named.
+ */
+export declare function repairGroupLabels(root: Document | ParentNode): number;
+/**
+ * Re-point `aria-describedby` tokens that hydration left dangling.
+ *
+ * The SAME divergence that breaks `for` breaks this, for the same reason, and it is arguably
+ * worse. `FormField` renders its error / help / description containers with `:id` as a compiled
+ * element binding, so those ids ARE in `dynamicProps` and Vue force-patches them to the client
+ * value. The matching `aria-describedby` reaches the control through `useFormField().ariaAttrs`
+ * inside a `v-bind` spread, which is NOT in `dynamicProps` — so it keeps the server value.
+ *
+ * The result on exactly the pages this plugin was written for: every validation error, help
+ * text and description points at an id that no longer exists. A sighted user sees "Required
+ * field"; a screen-reader user gets silence. That is WCAG 3.3.1 / 3.3.3 — the error is visible
+ * but never announced on the field it belongs to.
+ *
+ * Repaired token-wise rather than wholesale, so a describedby token the application wrote and
+ * that still resolves is left exactly as it is.
+ *
+ * @returns how many controls had at least one token repaired.
+ */
+export declare function repairDescribedBy(root: Document | ParentNode): number;
+/**
+ * Run every repair over `root` and report what each one did.
+ *
+ * @returns the per-repair counts, so the dev warning can name the mechanism rather than a total.
+ */
+export declare function repairFieldAssociations(root: Document | ParentNode): {
+    describedBy: number;
+    groups: number;
+    labels: number;
+};
 declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
 export default _default;

package/dist/runtime/plugins/form-label-association.client.js

@@ -1,12 +1,27 @@
 import { defineNuxtPlugin, useRuntimeConfig } from "#imports";
 const COMPONENT_ROOT = '[data-slot="root"]';
 const FIELD_LABEL = 'label[data-slot="label"][for]';
-const CONTROL = "input, textarea, select";
-const NOT_A_USER_CONTROL = '[type="hidden"], [hidden], [aria-hidden="true"], [disabled]';
+const CONTROL = 'input, textarea, select, button[data-slot="base"]';
+const NATIVE_HIDDEN = '[type="hidden"], [hidden]';
+const NOT_IN_A11Y_TREE = '[aria-hidden="true"]';
+const REKA_SUBMIT_PROXY = "[data-hidden]:not([id])";
+const NOT_A_USER_CONTROL = `${NATIVE_HIDDEN}, ${NOT_IN_A11Y_TREE}, ${REKA_SUBMIT_PROXY}`;
+const GROUP_ROOT = '[role="radiogroup"], [role="group"]';
+const DESCRIBING_SLOTS = '[data-slot="error"], [data-slot="help"], [data-slot="description"], [data-slot="hint"]';
+function isVisuallyRemoved(element) {
+  const style = element.style;
+  return style?.display === "none" || style?.visibility === "hidden";
+}
 function findControlForLabel(field) {
-  const eligible = [...field.querySelectorAll(CONTROL)].filter((control) => !control.matches(NOT_A_USER_CONTROL));
+  const eligible = [...field.querySelectorAll(CONTROL)].filter((control) => !control.matches(NOT_A_USER_CONTROL) && !isVisuallyRemoved(control));
   return eligible.length === 1 && eligible[0].id !== "" ? eligible[0] : null;
 }
+function isSafeToBind(label, control) {
+  if (control.labels?.length) {
+    return false;
+  }
+  return label.ownerDocument.getElementById(control.id) === control;
+}
 export function repairDanglingLabels(root) {
   let repaired = 0;
   for (const label of root.querySelectorAll(FIELD_LABEL)) {
@@ -19,14 +34,72 @@ export function repairDanglingLabels(root) {
       continue;
     }
     const control = findControlForLabel(field);
-    if (control === null || control.id === label.htmlFor) {
+    if (control === null || control.id === label.htmlFor || !isSafeToBind(label, control)) {
       continue;
     }
     label.htmlFor = control.id;
+    label.dataset.ltLabelRepaired = "";
+    repaired += 1;
+  }
+  return repaired;
+}
+export function repairGroupLabels(root) {
+  let repaired = 0;
+  for (const label of root.querySelectorAll(FIELD_LABEL)) {
+    const field = label.closest(COMPONENT_ROOT);
+    if (field === null) {
+      continue;
+    }
+    const target = label.ownerDocument.getElementById(label.htmlFor);
+    if (target !== null && field.contains(target)) {
+      continue;
+    }
+    const groups = field.querySelectorAll(GROUP_ROOT);
+    if (groups.length !== 1) {
+      continue;
+    }
+    const group = groups[0];
+    if (group.hasAttribute("aria-labelledby") || group.hasAttribute("aria-label")) {
+      continue;
+    }
+    if (label.id === "") {
+      label.id = `${group.id === "" ? label.htmlFor : group.id}-lt-label`;
+    }
+    group.setAttribute("aria-labelledby", label.id);
+    label.dataset.ltLabelRepaired = "";
     repaired += 1;
   }
   return repaired;
 }
+export function repairDescribedBy(root) {
+  let repaired = 0;
+  for (const control of root.querySelectorAll("[aria-describedby]")) {
+    const field = control.closest(COMPONENT_ROOT);
+    if (field === null) {
+      continue;
+    }
+    const tokens = control.getAttribute("aria-describedby").split(/\s+/).filter(Boolean);
+    const dangling = tokens.filter((token) => control.ownerDocument.getElementById(token) === null);
+    if (dangling.length === 0) {
+      continue;
+    }
+    const candidates = [...field.querySelectorAll(DESCRIBING_SLOTS)].filter((element) => element.id !== "");
+    if (candidates.length !== dangling.length) {
+      continue;
+    }
+    const replacements = new Map(dangling.map((token, index) => [token, candidates[index].id]));
+    control.setAttribute("aria-describedby", tokens.map((token) => replacements.get(token) ?? token).join(" "));
+    repaired += 1;
+  }
+  return repaired;
+}
+export function repairFieldAssociations(root) {
+  return {
+    describedBy: repairDescribedBy(root),
+    groups: repairGroupLabels(root),
+    labels: repairDanglingLabels(root)
+  };
+}
 export default defineNuxtPlugin({
   // After the app's own plugins, so a page that assigns ids itself has already run.
   enforce: "post",
@@ -36,30 +109,69 @@ export default defineNuxtPlugin({
     if (options?.enabled === false) {
       return;
     }
-    const maxRepairMs = options?.maxRepairMs ?? 1500;
+    const configured = options?.maxRepairMs ?? 1500;
+    const maxRepairMs = Number.isFinite(configured) && configured > 0 ? Math.min(configured, 3e4) : 0;
+    const observeDeferred = options?.observeDeferred !== false;
     let sweeping = null;
+    let closing = null;
+    let observer = null;
+    let warned = false;
     const sweep = () => {
-      const repaired = repairDanglingLabels(document);
-      if (repaired > 0 && import.meta.dev) {
+      const { describedBy, groups, labels } = repairFieldAssociations(document);
+      if (import.meta.dev && !warned && describedBy + groups + labels > 0) {
+        warned = true;
+        const names = [...document.querySelectorAll("[data-lt-label-repaired]")].map((label) => label.textContent?.trim()).filter(Boolean);
         console.warn(
-          `[@lenne.tech/nuxt-extensions] repaired ${repaired} form label association(s) broken by an SSR/client useId() divergence. This is a stopgap \u2014 see runtime/plugins/form-label-association.client.ts.`
+          `[@lenne.tech/nuxt-extensions] repaired ${labels} label association(s), ${groups} group name(s) and ${describedBy} aria-describedby reference(s) broken by an SSR/client useId() divergence${names.length > 0 ? `: ${names.join(", ")}` : ""}. This is a stopgap \u2014 see runtime/plugins/form-label-association.client.ts.`
         );
       }
     };
     const sweepFor = () => {
       sweep();
-      if (maxRepairMs <= 0 || sweeping !== null) {
+      if (maxRepairMs <= 0) {
         return;
       }
-      sweeping = setInterval(sweep, 250);
-      setTimeout(() => {
+      if (sweeping === null) {
+        sweeping = setInterval(sweep, 250);
+      }
+      if (closing !== null) {
+        clearTimeout(closing);
+      }
+      closing = setTimeout(() => {
         if (sweeping !== null) {
           clearInterval(sweeping);
           sweeping = null;
         }
+        closing = null;
       }, maxRepairMs);
     };
-    nuxtApp.hook("app:mounted", sweepFor);
+    const observeDeferredHydration = () => {
+      if (!observeDeferred || observer !== null || typeof MutationObserver === "undefined") {
+        return;
+      }
+      let queued = false;
+      observer = new MutationObserver((records) => {
+        if (queued) {
+          return;
+        }
+        const carriesLabel = records.some(
+          (record) => [...record.addedNodes].some((node) => node instanceof Element && (node.matches(FIELD_LABEL) || node.querySelector(FIELD_LABEL) !== null))
+        );
+        if (!carriesLabel) {
+          return;
+        }
+        queued = true;
+        requestAnimationFrame(() => {
+          queued = false;
+          sweep();
+        });
+      });
+      observer.observe(document.body, { childList: true, subtree: true });
+    };
+    nuxtApp.hook("app:mounted", () => {
+      sweepFor();
+      observeDeferredHydration();
+    });
     nuxtApp.hook("page:finish", () => {
       requestAnimationFrame(sweepFor);
     });

package/dist/runtime/plugins/pre-hydration-input.client.js

@@ -26,7 +26,8 @@ export default defineNuxtPlugin({
     if (options?.enabled === false) {
       return;
     }
-    const maxRestoreMs = options?.maxRestoreMs ?? 1500;
+    const configuredRestoreMs = options?.maxRestoreMs ?? 1500;
+    const maxRestoreMs = Number.isFinite(configuredRestoreMs) && configuredRestoreMs > 0 ? Math.min(configuredRestoreMs, 3e4) : 0;
     let edited = /* @__PURE__ */ new Map();
     nuxtApp.hook("app:beforeMount", () => {
       edited = collectEditedFields(document);

package/dist/runtime/types/module.d.ts

@@ -179,13 +179,30 @@ export interface LtFormLabelAssociationOptions {
     enabled?: boolean;
     /**
      * How long after mount to keep repairing, in milliseconds. Defaults to `1500`; `0` sweeps
-     * once and stops.
+     * once and stops. Values above 30000 are clamped, and a non-finite value is treated as `0` —
+     * a delay past 2^31 overflows `setTimeout` and fires immediately, silently turning an
+     * over-large window into no window at all.
      *
-     * Most fields are repaired in the first pass. The window exists for server-rendered
-     * subtrees whose hydration is deferred — `hydrate-on-visible`, an unresolved `<Suspense>`,
-     * an island — which carry the same divergence but hydrate after `app:mounted`.
+     * Most fields are repaired in the first pass. The window exists for server-rendered subtrees
+     * whose hydration is deferred — an unresolved `<Suspense>`, an island — which carry the same
+     * divergence but hydrate after `app:mounted`. It does NOT reach `hydrate-on-visible` or
+     * `hydrate-on-interaction`, which can fire minutes later; `observeDeferred` covers those.
      */
     maxRepairMs?: number;
+    /**
+     * Keep watching for server-rendered subtrees that hydrate after the window closes.
+     * Defaults to `true`.
+     *
+     * `hydrate-on-visible` fires on scroll and `hydrate-on-interaction` on a click — either can
+     * be long after mount, and both carry the very same divergence, so no fixed window reaches
+     * them. A `MutationObserver` does, and it costs nothing while nothing changes: it reacts
+     * only to added subtrees that actually contain a field label, and coalesces a burst into one
+     * sweep per frame.
+     *
+     * Turn it off if your application renders no lazily hydrated server content and you would
+     * rather not carry an observer at all; the bounded window then remains the only mechanism.
+     */
+    observeDeferred?: boolean;
 }
 /**
  * Pre-hydration input preservation.
@@ -275,6 +292,7 @@ export interface LtExtensionsPublicRuntimeConfig {
         formLabelAssociation: {
             enabled: boolean;
             maxRepairMs: number;
+            observeDeferred: boolean;
         };
         preHydrationInput: {
             enabled: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "Reusable Nuxt 4 composables, components, and Better-Auth integration for lenne.tech projects",
   "repository": {
     "type": "git",
@@ -78,9 +78,9 @@
     "@nuxt/kit": "^4.0.0"
   },
   "peerDependencies": {
-    "@better-auth/passkey": ">=1.0.0",
+    "@better-auth/passkey": ">=1.7.1 <1.8.0",
     "@playwright/test": ">=1.0.0",
-    "better-auth": ">=1.0.0",
+    "better-auth": ">=1.7.1 <1.8.0",
     "nuxt": "^4.0.0",
     "tus-js-client": ">=4.0.0"
   },
@@ -102,6 +102,7 @@
     "@better-auth/passkey": "1.7.1",
     "@nuxt/module-builder": "1.0.3",
     "@nuxt/schema": "4.5.2",
+    "@nuxt/ui": "4.11.0",
     "@playwright/test": "1.62.1",
     "@types/node": "26.2.0",
     "@vitest/coverage-v8": "4.1.11",
@@ -111,6 +112,7 @@
     "nuxt": "4.5.2",
     "oxfmt": "0.64.0",
     "oxlint": "1.79.0",
+    "reka-ui": "2.10.3",
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
     "vitest": "4.1.11",