@lenne.tech/nuxt-extensions 1.12.0 → 1.14.0

package/CLAUDE.md

@@ -76,6 +76,10 @@ export default defineNuxtConfig({
       enabled: true,
       basePath: '/ai',               // Must match the nest-server AI controller
     },
+    formLabelAssociation: {
+      enabled: true,                 // repair <label for> broken by an SSR/client useId() divergence
+      maxRepairMs: 1500,             // how long to keep repairing deferred subtrees
+    },
     preHydrationInput: {
       enabled: true,                 // keep text typed before hydration instead of losing it
       maxRestoreMs: 1500,            // how long to keep repairing deferred subtrees
@@ -175,6 +179,52 @@ export default defineNuxtRouteMiddleware((to) => {
 });
 ```
 
+## Form Label Repair
+
+**The defect:** Nuxt UI's `FormField` derives the label's `for` and the control's `id` from one
+`useId()` call. When `useId()` diverges between server and client, the control's `id` is
+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` 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` / `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`.
+
 ## Pre-Hydration Input Preservation
 
 **The defect:** until Vue hydrates a server-rendered `<input>`, it carries no framework

package/README.md

@@ -42,6 +42,7 @@ npm install tus-js-client
 - **i18n Support** - English and German translations (works without i18n too)
 - **Auto-imports** - All composables and components are auto-imported
 - **Pre-hydration input preservation** - text typed before hydration is kept, not erased
+- **Form label repair** - restores `<label for>` associations that hydration breaks
 
 ## Environment Variables
 
@@ -157,6 +158,98 @@ export default defineNuxtConfig({
 });
 ```
 
+## Form Label Repair
+
+Restores `<label for>` associations that hydration breaks. Active by default.
+
+### The problem
+
+Nuxt UI's `FormField` derives the label's `for` and the control's `id` from a single
+`useId()` call, so they cannot disagree — unless `useId()` itself returns different values on
+server and client, which happens when the two walk a different number of async boundaries.
+
+Measured against `@nuxt/ui` 4.11.x:
+
+| | label `for` | control `id` |
+|---|---|---|
+| SSR payload | `v-0-4-2` | `v-0-4-2` |
+| after hydration | `v-0-4-2` | `v-0-1-2` |
+
+Vue 3.5.39 did not cause this, it exposed it
+([vuejs/core#9083](https://github.com/vuejs/core/pull/9083) force-patches an element's
+dynamic props on hydration). The control's `id` is such a prop; the label's `for`, passed
+through reka-ui's `Label` component, is not — so only the label keeps the stale value.
+
+### What it costs when it breaks
+
+The control loses its programmatic label. Without a placeholder it has no accessible name at
+all and a screen reader announces "edit text, blank"; **with** a placeholder that becomes the
+name instead, so the visible label is no longer part of it and speech input stops working.
+Clicking the label focuses nothing either — which on a checkbox or radio is the primary hit
+target, not a convenience. Tests using `getByRole('textbox', { name })` stop finding fields.
+
+### What the repair does
+
+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 `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 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 |
+
+**`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.
+
+### Opting out
+
+```ts
+export default defineNuxtConfig({
+  ltExtensions: {
+    formLabelAssociation: {
+      enabled: false,
+      // 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 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
 
 Text typed before a page has hydrated is kept instead of being silently thrown away.

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.12.0";
+declare const version = "1.14.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.12.0",
+  "version": "1.14.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,7 +1,7 @@
 import { defineNuxtModule, createResolver, tryResolveModule, addImports, addComponent, addPlugin, addRouteMiddleware } from '@nuxt/kit';
 
 const name = "@lenne.tech/nuxt-extensions";
-const version = "1.12.0";
+const version = "1.14.0";
 const configKey = "ltExtensions";
 const DEFAULT_LT_AUTH_STATE_COOKIE = "lt-auth-state";
 const DEFAULT_LT_JWT_TOKEN_COOKIE = "lt-jwt-token";
@@ -36,6 +36,9 @@ const defaultOptions = {
     enabled: true,
     defaultLocale: "de"
   },
+  formLabelAssociation: {
+    enabled: true
+  },
   i18n: {
     autoMerge: true
   },
@@ -66,6 +69,7 @@ const module$1 = defineNuxtModule({
         systemSetup: { ...defaultOptions.auth.systemSetup, ...options.auth?.systemSetup }
       },
       errorTranslation: { ...defaultOptions.errorTranslation, ...options.errorTranslation },
+      formLabelAssociation: { ...defaultOptions.formLabelAssociation, ...options.formLabelAssociation },
       i18n: { ...defaultOptions.i18n, ...options.i18n },
       preHydrationInput: { ...defaultOptions.preHydrationInput, ...options.preHydrationInput },
       tus: { ...defaultOptions.tus, ...options.tus }
@@ -124,6 +128,11 @@ const module$1 = defineNuxtModule({
         enabled: resolvedOptions.errorTranslation?.enabled ?? true,
         defaultLocale: resolvedOptions.errorTranslation?.defaultLocale || "de"
       },
+      formLabelAssociation: {
+        enabled: resolvedOptions.formLabelAssociation?.enabled ?? true,
+        maxRepairMs: resolvedOptions.formLabelAssociation?.maxRepairMs ?? 1500,
+        observeDeferred: resolvedOptions.formLabelAssociation?.observeDeferred ?? true
+      },
       preHydrationInput: {
         enabled: resolvedOptions.preHydrationInput?.enabled ?? true,
         maxRestoreMs: resolvedOptions.preHydrationInput?.maxRestoreMs ?? 1500
@@ -219,6 +228,9 @@ const module$1 = defineNuxtModule({
     if (resolvedOptions.preHydrationInput.enabled !== false) {
       addPlugin(resolve("./runtime/plugins/pre-hydration-input.client"));
     }
+    if (resolvedOptions.formLabelAssociation.enabled !== false) {
+      addPlugin(resolve("./runtime/plugins/form-label-association.client"));
+    }
     nuxt.options.build.transpile.push(resolve("./runtime"));
     nuxt.options.build.transpile.push("tus-js-client");
     console.log(`[${name}] Module loaded with config:`, {

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

@@ -0,0 +1,127 @@
+/**
+ * Repair `<label for>` associations that hydration leaves pointing at nothing.
+ *
+ * ## The defect
+ *
+ * Nuxt UI's `FormField` generates ONE id with `useId()` and uses it for both halves of
+ * the association: `<Label :for="id">` and, via `provide`/`inject`, the control's `id`.
+ * One source, so the two cannot disagree — unless `useId()` itself returns different
+ * values on the server and on the client.
+ *
+ * It does. Measured on a Nuxt 4 app page (SVL, DEV-3093), against `@nuxt/ui` 4.11.x:
+ *
+ * | | label `for` | control `id` |
+ * | -- | -- | -- |
+ * | SSR payload | `v-0-4-2` | `v-0-4-2` |
+ * | after hydration | `v-0-4-2` | `v-0-1-2` |
+ *
+ * The middle segment is Vue's per-branch id prefix, which is extended at every async
+ * boundary. Server and client walked a different number of them, so the ids diverge.
+ *
+ * **Vue >= 3.5.39 did not cause this — it exposed it.** "force patch dynamic props when
+ * hydrating" (vuejs/core#9083, merged 2026-06-25) makes a hydrated element adopt its
+ * freshly computed client value, where previously the server value simply stayed.
+ *
+ * Note WHY only the label is left behind, because it points at the real fix: the control's
+ * `id` is a compiled element binding (`<input :id="id">`), so it is in the element's
+ * `dynamicProps` and gets force-patched. The label's `for` is a PROP on reka-ui's `Label`
+ * component and arrives at the `<label>` through `$attrs`, which is not part of that set.
+ * The asymmetry is the component boundary, not the id generation. Fixing the divergence
+ * upstream — or having `FormField` pass an SSR-stable id — removes the need for this file.
+ *
+ * ## Why it is worth a plugin
+ *
+ * A control whose label does not resolve loses its programmatic label: the visible text is
+ * no longer its accessible name (WCAG 1.3.1). Where the field has no placeholder it has no
+ * accessible name at all and a screen reader announces "edit text, blank" (4.1.2). Where it
+ * has one, the placeholder becomes the name instead — which is arguably worse, because the
+ * name no longer contains the visible label and speech input stops working (2.5.3 Label in
+ * Name). Clicking the label also no longer focuses the control, and for a checkbox or radio
+ * that is not a convenience but the primary hit target.
+ *
+ * And any test that addresses fields the way assistive technology does
+ * (`getByRole('textbox', { name })`, the recommended Playwright locator) stops finding
+ * them, which is how this surfaced: 39 specs at once.
+ *
+ * ## What this does, and what it deliberately does not
+ *
+ * After mount — and for a bounded window afterwards — every Nuxt UI field label whose
+ * target does not resolve is re-pointed at the control inside its own field.
+ *
+ * It **refuses to guess**, which is the rule that matters most here. 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 then change a value the user never chose. So the repair only happens
+ * when the field contains exactly ONE eligible control. A group of radios or checkboxes
+ * shares one field root and is therefore skipped, not guessed at.
+ *
+ * `for` is repaired rather than `aria-labelledby` added, because `for` carries BOTH the
+ * accessible name and click-to-focus. Adding `aria-labelledby` would restore the name
+ * and leave the label dead to the mouse.
+ *
+ * This is a repair, not a cure: the right fix is for the id not to diverge in the first
+ * place (see the component-boundary note above). It is applied here because the divergence
+ * sits in the framework stack rather than in any one application, and because a nameless
+ * form is not something to leave in place while that is resolved upstream.
+ *
+ * Default on; opt out with `ltExtensions.formLabelAssociation.enabled: false`.
+ */
+/**
+ * Re-point every dangling field label at the control in its own field.
+ *
+ * Exported for the unit test: it runs against a DOM fixture rather than a live app, so the
+ * pairing rules stay verifiable without a browser. Not part of the package's public API.
+ *
+ * @param root Where to look. Ids are resolved against the owning document regardless, since
+ *   `id` is document-scoped — so a scoped root narrows which labels are visited, not which
+ *   ids count as resolvable.
+ * @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

@@ -0,0 +1,179 @@
+import { defineNuxtPlugin, useRuntimeConfig } from "#imports";
+const COMPONENT_ROOT = '[data-slot="root"]';
+const FIELD_LABEL = 'label[data-slot="label"][for]';
+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) && !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)) {
+    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 control = findControlForLabel(field);
+    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",
+  name: "lt-form-label-association",
+  setup(nuxtApp) {
+    const options = useRuntimeConfig().public.ltExtensions?.formLabelAssociation;
+    if (options?.enabled === false) {
+      return;
+    }
+    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 { 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 ${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) {
+        return;
+      }
+      if (sweeping === null) {
+        sweeping = setInterval(sweep, 250);
+      }
+      if (closing !== null) {
+        clearTimeout(closing);
+      }
+      closing = setTimeout(() => {
+        if (sweeping !== null) {
+          clearInterval(sweeping);
+          sweeping = null;
+        }
+        closing = null;
+      }, maxRepairMs);
+    };
+    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/index.d.ts

@@ -1,5 +1,5 @@
 export type { LtAuthClientConfig, LtAuthMode, LtAuthResponse, LtAuthState, LtPasskeyAuthResult, LtPasskeyRegisterResult, LtUser, UseLtAuthReturn } from './auth.js';
 export type { LtFileInfo, LtUploadItem, LtUploadOptions, LtUploadProgress, LtUploadStatus, UseLtFileReturn, UseLtTusUploadReturn } from './upload.js';
-export type { LtAiModuleOptions, LtAuthCookieNamesOptions, LtAuthModuleOptions, LtErrorTranslationModuleOptions, LtExtensionsModuleOptions, LtExtensionsPublicRuntimeConfig, LtI18nModuleOptions, LtPreHydrationInputOptions, LtSystemSetupModuleOptions, LtTusModuleOptions, } from './module.js';
+export type { LtAiModuleOptions, LtAuthCookieNamesOptions, LtAuthModuleOptions, LtErrorTranslationModuleOptions, LtExtensionsModuleOptions, LtExtensionsPublicRuntimeConfig, LtFormLabelAssociationOptions, LtI18nModuleOptions, LtPreHydrationInputOptions, LtSystemSetupModuleOptions, LtTusModuleOptions, } from './module.js';
 export type { LtErrorTranslationResponse, LtParsedError, UseLtErrorTranslationReturn } from './error.js';
 export type { LtAiAction, LtAiAvailableConnection, LtAiBudgetLimit, LtAiBudgetSummary, LtAiConnection, LtAiConnectionInput, LtAiConnectionPreference, LtAiEffectiveSlot, LtAiInteraction, LtAiMessage, LtAiMode, LtAiPlaceholder, LtAiPrompt, LtAiPromptHint, LtAiPromptHintInput, LtAiPromptInput, LtAiPromptRunInput, LtAiResponse, LtAiSlot, LtAiSlotInput, LtAiStreamEvent, LtAiStreamHandlers, LtAiUsage, LtAiUsageInfo, LtAiUsageScope, UseLtAiAdminReturn, UseLtAiChatOptions, UseLtAiChatReturn, UseLtAiConnectionsReturn, UseLtAiPlaceholdersReturn, UseLtAiPromptsReturn, UseLtAiReturn, UseLtAiUsageReturn, } from './ai.js';

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

@@ -127,6 +127,8 @@ export interface LtExtensionsModuleOptions {
     auth?: LtAuthModuleOptions;
     /** Error translation configuration */
     errorTranslation?: LtErrorTranslationModuleOptions;
+    /** Form label association repair configuration */
+    formLabelAssociation?: LtFormLabelAssociationOptions;
     /** i18n configuration */
     i18n?: LtI18nModuleOptions;
     /** Pre-hydration input preservation configuration */
@@ -134,6 +136,74 @@ export interface LtExtensionsModuleOptions {
     /** TUS upload module configuration */
     tus?: LtTusModuleOptions;
 }
+/**
+ * Repair of `<label for>` associations broken by an SSR/client `useId()` divergence.
+ *
+ * Nuxt UI's `FormField` derives the label's `for` and the control's `id` from ONE `useId()`
+ * call, so they cannot disagree — unless `useId()` itself returns different values on server
+ * and client, which it does whenever the two walk a different number of async boundaries.
+ * The label then keeps the server value while the control adopts the client one.
+ *
+ * The control loses its programmatic label. Without a placeholder it has no accessible name
+ * at all and a screen reader announces "edit text, blank"; with one, the placeholder becomes
+ * the name instead, so the visible label is no longer part of it and speech input stops
+ * working. Either way clicking the label focuses nothing — which on a checkbox or radio is
+ * the primary hit target, not a convenience.
+ *
+ * Vue >= 3.5.39 did not cause this, it exposed it: vuejs/core#9083 force-patches an element's
+ * dynamic props during hydration, and the control's `id` is one while the label's `for` —
+ * passed through reka-ui's `Label` component and `$attrs` — is not.
+ *
+ * The repair refuses to guess: it only fires when the field contains exactly one eligible
+ * control, so a radio or checkbox group is skipped rather than having every caption bound to
+ * its first option.
+ *
+ * @example
+ * ```ts
+ * export default defineNuxtConfig({
+ *   ltExtensions: {
+ *     formLabelAssociation: { enabled: false },
+ *   },
+ * });
+ * ```
+ */
+export interface LtFormLabelAssociationOptions {
+    /**
+     * Enable the repair. Defaults to `true`.
+     *
+     * Turn it off only with a reason. Two real ones: an application that assigns `for` itself
+     * and depends on those exact values, or a test suite asserting on literal `for` / `id`
+     * strings rather than on the accessible name. The alternative is a form whose fields carry
+     * no programmatic label.
+     */
+    enabled?: boolean;
+    /**
+     * How long after mount to keep repairing, in milliseconds. Defaults to `1500`; `0` sweeps
+     * 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 — 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.
  *
@@ -219,6 +289,11 @@ export interface LtExtensionsPublicRuntimeConfig {
             enabled: boolean;
             defaultLocale: string;
         };
+        formLabelAssociation: {
+            enabled: boolean;
+            maxRepairMs: number;
+            observeDeferred: boolean;
+        };
         preHydrationInput: {
             enabled: boolean;
             maxRestoreMs: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "Reusable Nuxt 4 composables, components, and Better-Auth integration for lenne.tech projects",
   "repository": {
     "type": "git",
@@ -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",