@nocobase/app-template-default 1.0.0-beta.83 → 1.0.0-beta.84

package/.agents/rules/build-and-deploy.md

@@ -16,7 +16,7 @@ For a Docker source build, pass `--build-arg CDN_BASE_URL=https://cdn.example.co
 
 ## Packing the build for a deployment
 
-`pnpm build --tar` writes `storage/exports/dist.tar.gz` after the build. The archive holds `dist/` as a directory next to `config.example.yml`, so extracting it produces exactly those two paths rather than scattering `server/` and `node_modules/` into whatever directory you unpacked in.
+`pnpm build --tar` writes `storage/exports/dist.tar.gz` after the build. The archive holds `dist/` as a directory next to `config.example.yml`, with the `Dockerfile` and `Dockerfile.dockerignore`, so extracting it produces exactly those paths rather than scattering `server/` and `node_modules/` into whatever directory you unpacked in, and a server can build the image from it alone with `docker build --build-arg DIST=prebuilt .`.
 
 `config.example.yml` travels with it because a deployment has to write a `config.yml` before it can start — `pnpm nocobase config init`, run inside `dist/`, does that from the example, in place, and `pnpm nocobase config check` there verifies it, database connection included, before the first start — and the example is the only statement of what may go in it. Directories of executable shims are left out: a `.bin` entry points at a path on the machine that installed it, and a dangling one makes `pnpm install` in the extracted tree report a corrupt store rather than repair it.
 

package/.agents/rules/shell.md

@@ -33,3 +33,7 @@ Use `Loading` for page or panel waits and `Spinner` (the shadcn-compatible adapt
 The shared list of shell behaviors to keep when customizing is in [customizing the shell](../skills/nocobase-app-development/references/frontend/references/shell.md).
 
 The signed-in region waits in `client/routing/session-preparation.tsx` before mounting `AppLayout`: the authentication provider first reconnects active realtime subscriptions as the current session and waits for the open notification, including permission invalidation. A ten-second timeout shows a localized retry/sign-out screen. Keep this boundary inside `RequiredAuthentication`; guest login must remain reachable without realtime. Readiness is only for initial session preparation. Subsequent permission notifications and reconnects still use normal fail-closed route unmounting, including portal and effect cleanup.
+
+## List context
+
+Keep the identity-keyed `SessionPreparation` boundary: mounted private list conditions and ancestor query memory must be discarded when the signed-in user changes. Public list state uses `useTableUrlState`; tabbed datasets use `useListTabs`, with complete owned parameter keys and permission-filtered tabs. Follow the synchronized [list navigation rules](../skills/nocobase-app-development/references/frontend/references/child-routes.md#list-tab-breadcrumbs-and-private-conditions). Default back links use an empty ancestor query when no source visit exists; explicit return destinations remain application-owned.

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 This is a NocoBase 3 application. Do not apply globally installed NocoBase 2 Skills. You are building the application itself — its pages, its API, its database tables. Everything under this directory is application-owned source code that you may edit directly.
 
-Do not create a plugin to add a feature. Plugins are separately published packages for capabilities shared across several applications; building one for this application's own feature adds a package boundary, a version, and a release process to work that belongs in `client/` and `server/`. Create one only when the user explicitly asks for a reusable published package. Ordinary internal workspace packages under `packages/` may share code without becoming plugins or being published; follow [internal packages](.agents/rules/workspace.md) when the application needs that boundary.
+Build application-specific features directly in the application by default. Use a plugin when the user requests one or when code reuse or modular organization calls for a separately registered, maintainable feature. Local plugins belong under `packages/`; the App builds and packages registered local plugins for deployment, so publishing is optional and only needed when distributing the plugin through a package registry. Follow [the project plugin development Skill](.agents/skills/nocobase-app-plugin-development/SKILL.md). Ordinary internal packages can share code without plugin registration; follow [internal packages](.agents/rules/workspace.md) when that is the boundary the application needs.
 
 ## Default template scope
 
@@ -28,6 +28,8 @@ For creating or maintaining a plugin in this App, read [the project plugin devel
 
 `.agents/skills/nocobase-app-upgrade/` is a separate Skill for a separate job: merging a newer release of the template this application was generated from. Read it when the task is upgrading the template rather than building a feature — including when the user asks to upgrade NocoBase or its core version, because a newer template release is how this application moves to a newer NocoBase — and read it before touching anything — an upgrade done by copying the newest template over this application destroys the work that made it this application.
 
+When upgrading from an older installed Skill, also read the target template package’s `AGENTS.md` and `README.MD` and fetch its declared `@nocobase/app-skills` package before editing. Follow the target’s upgrade requirements in the same upgrade, including application-owned lists and installed Registry copies. Confirm the target baseline only after conflicts are resolved and dependency, source, behavior and retained-data checks pass; see the [upgrade Skill](.agents/skills/nocobase-app-upgrade/SKILL.md).
+
 `.agents/skills/nocobase-deployment/` covers moving this application from source to a production server: building for the target platform, what the archive does and does not carry, migrations and business data, production configuration, and what to verify afterwards. Read it before building for deployment, and when an application starts in production but does not work.
 
 ## Where things go
@@ -118,6 +120,10 @@ When the built-in mechanism genuinely cannot express what is being asked, changi
 - Comment what you changed and why the built-in path did not fit. On upgrade, an agent reconciling the template's version needs to know whether your change is still needed.
 - Record what the next agent needs to know in the matching `.agents/rules/` file, or a new one linked from the index below, so the guidance describes the application as it actually is without growing this file. If the framework's shared guidance is wrong for every application, update the source `@nocobase/app-skills` package instead of editing its synchronized copy.
 
+## Standard submissions
+
+Standard Repository writes require an operation key through the registered submission provider. Forms share `useSubmission` across all entries before asynchronous validation; custom effectful APIs explicitly join the receipt transaction. Follow [submission protection](.agents/skills/nocobase-app-development/references/submission.md) and [source upgrades](.agents/skills/nocobase-app-upgrade/references/submission-upgrade.md). Merge copied source and verify retained customizations on upgrade.
+
 ## Index
 
 | Read                                                                   | When                                                                                                         |

package/README.MD

@@ -4,6 +4,12 @@ A full-stack NocoBase 3 application. The server runs on `@nocobase/app-server` a
 
 You own everything in this directory. Add pages, API routes, database tables, and business logic directly here — this is your application's source code, not a framework you extend from the outside.
 
+## Upgrade this application
+
+Ask the application agent to upgrade NocoBase using the application-local [template upgrade Skill](.agents/skills/nocobase-app-upgrade/SKILL.md). This is the supported version-selection and three-way source reconciliation entry point. Before merging, read the selected target package’s `AGENTS.md`, this section and the upgrade Skill from its declared `@nocobase/app-skills` dependency, even if the application still has an older Skill. Fetch and inspect that guidance without first installing it.
+
+Complete the target’s requirements in that same upgrade: reconcile dependencies, copied template and Registry sources, application-owned table/card consumers and translations while preserving business customizations, grants, records and executed migrations. For list feedback, follow the target Skill’s `references/list-feedback-upgrade.md`. Do not finish with only a version bump, dependency update or Skill sync. Missing targets, unresolved business conflicts or failed acceptance stop completion; confirm `defaultTemplateVersion` only after the checks pass. See the target Skill’s `references/versioned-upgrade-verification.md` for package integrity records and verification after publication.
+
 ## Default and Examples
 
 Default provides the application shell and product capabilities without example plugins or business demo pages. Application-owned business API routes start empty, and new databases receive no article sample data. A bare create-app shows Home and, for unrestricted administrators only, System settings → App foundation. Foundation is installed and registered on both Client and Server; its read-only overview is available at `/foundation` under the application base path. As business capabilities are developed, the app development skill reconciles missing core administration on every iteration and registers the prepared Users and Roles and permissions contribution (`client/pages/settings/routes.ts`); each actually used configurable capability includes its administration as part of feature delivery. Its built-in Users integration lists direct Authorization Permission Sets as application roles, while access assigned to all authenticated users remains separate. Use `app-template-examples` for article management and runnable plugin demonstrations.
@@ -138,7 +144,7 @@ The three files named `runtime.ts`, `plugins.ts`, and `routes.ts` are compositio
 | `pnpm dev`         | Start the API server and client with hot reload                                      |
 | `pnpm build`       | Build the client and server into `dist/`                                             |
 | `pnpm start`       | Run the built server; requires `pnpm build` first                                    |
-| `pnpm build --tar` | Build, then pack `dist/` and `config.example.yml` into `storage/exports/dist.tar.gz` |
+| `pnpm build --tar` | Build, then pack `dist/`, `config.example.yml` and the `Dockerfile` with its `.dockerignore` into `storage/exports/dist.tar.gz` |
 
 ### Database
 
@@ -287,10 +293,12 @@ Pass the file's path relative to `dist/client/`, with or without a leading slash
 
 `pnpm build --tar` writes `storage/exports/dist.tar.gz`, the artifact `@nocobase/app-installer` installs on a server.
 
-The archive has two levels: `config.example.yml` and `dist/` sit at the root, and the build is inside `dist/`. What `dist/` holds varies with the application; this is the shape:
+The archive has two levels: `config.example.yml`, `dist/` and, when the application has them, the `Dockerfile` and `Dockerfile.dockerignore` sit at the root, and the build is inside `dist/`. A server builds the image from the extracted archive alone with `docker build --build-arg DIST=prebuilt .`. What `dist/` holds varies with the application; this is the shape:
 
 ```text
 dist.tar.gz
+├── Dockerfile
+├── Dockerfile.dockerignore
 ├── config.example.yml
 └── dist/
     ├── cli/

package/client/components/back-button.tsx

@@ -1,7 +1,7 @@
 import { useTranslation } from '@nocobase/i18n/client';
 import { ArrowLeftIcon } from 'lucide-react';
 import type { ReactElement, ReactNode } from 'react';
-import { Link, type To, useLocation, useResolvedPath } from 'react-router';
+import { Link, type To, useResolvedPath } from 'react-router';
 
 import { useRouteSearches } from '../routing/route-context.js';
 
@@ -10,7 +10,7 @@ import { cn } from 'cn';
 export interface BackButtonProps {
   /**
    * Where it leads. Defaults to the parent route with its last visited query; a directly opened detail falls back
-   * to the current query, as closing a route overlay does. An explicit destination is kept unchanged.
+   * to the default parent list. An explicit destination is kept unchanged.
    */
   readonly to?: To;
   /** The label, "Back" by default. */
@@ -33,7 +33,6 @@ export function BackButton({
   to,
 }: BackButtonProps = {}): ReactElement {
   const { t } = useTranslation();
-  const location = useLocation();
   const parent = useResolvedPath('..');
   const searches = useRouteSearches();
 
@@ -48,8 +47,7 @@ export function BackButton({
         to ?? {
           pathname: '..',
           search:
-            searches.get(parent.pathname.replace(/\/+$/u, '') || '/') ??
-            location.search,
+            searches.get(parent.pathname.replace(/\/+$/u, '') || '/') ?? '',
         }
       }
     >

package/client/components/default-access-editor.tsx

@@ -83,6 +83,7 @@ export function DefaultAccessEditor({
           <Input
             id={`${id}-key`}
             name='ruleKey'
+            data-field-path='key'
             value={ruleKey}
             required
             disabled={existing || readOnly}
@@ -91,7 +92,11 @@ export function DefaultAccessEditor({
             onChange={(event) => onKeyChange(event.target.value)}
           />
           {keyError && (
-            <p id={`${id}-key-error`} className='text-sm text-destructive'>
+            <p
+              data-feedback-field-error
+              id={`${id}-key-error`}
+              className='text-sm text-destructive'
+            >
               {keyError}
             </p>
           )}
@@ -108,6 +113,7 @@ export function DefaultAccessEditor({
           >
             <SelectTrigger
               id={`${id}-resource`}
+              data-field-path='resource'
               className='w-full'
               aria-invalid={Boolean(resourceError)}
               aria-describedby={
@@ -127,7 +133,11 @@ export function DefaultAccessEditor({
             </SelectContent>
           </Select>
           {resourceError && (
-            <p id={`${id}-resource-error`} className='text-sm text-destructive'>
+            <p
+              data-feedback-field-error
+              id={`${id}-resource-error`}
+              className='text-sm text-destructive'
+            >
               {resourceError}
             </p>
           )}
@@ -187,6 +197,7 @@ export function DefaultAccessEditor({
                     </Select>
                     {scope.error && (
                       <p
+                        data-feedback-field-error
                         id={`${id}-${scope.id}-error`}
                         className='text-sm text-destructive'
                       >

package/client/components/feedback-form.tsx

@@ -0,0 +1,474 @@
+import {
+  FormFeedback,
+  formFeedbackErrors,
+  type FormFeedbackAttempt,
+  type FormFeedbackField,
+  type FormFeedbackOptions,
+  type FormFeedbackState,
+} from '@nocobase/app-client';
+import { useTranslation } from '@nocobase/i18n/client';
+import {
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type ComponentProps,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { createPortal } from 'react-dom';
+
+export interface FeedbackFormProps extends Omit<
+  ComponentProps<'form'>,
+  'onSubmit'
+> {
+  readonly onSubmit?: (
+    event: React.FormEvent<HTMLFormElement>,
+  ) => void | Promise<void>;
+  /** Pass the caught request error; input state continues to belong to the caller. */
+  readonly error?: unknown;
+  /** Trusted application copy/actions for a request failure; never pass raw server content. */
+  readonly errorContent?: ReactNode;
+  readonly submitting?: boolean;
+  /** For unmounted tabs, repeated rows and extension controls, register stable descriptors. */
+  readonly feedback?: FormFeedback;
+  readonly fieldMessage?: FormFeedbackOptions['fieldMessage'];
+  /** React Hook Form errors. Set shouldFocusError: false so layout order owns focus. */
+  readonly validationErrors?: unknown;
+}
+
+/** Native fields use name (or data-field-path). Custom controls use a FormFeedback descriptor. */
+export function FeedbackForm({
+  children,
+  onSubmit,
+  error,
+  errorContent,
+  feedback: supplied,
+  fieldMessage,
+  validationErrors,
+  noValidate,
+  submitting = false,
+  ref,
+  ...props
+}: FeedbackFormProps): ReactElement {
+  const { t } = useTranslation();
+  const options = useMemo<FormFeedbackOptions>(
+    () => ({
+      messages: {
+        field: t('formFeedback.field', {
+          defaultValue: 'This value was rejected. Check it and try again.',
+        }),
+        invalid: t('formFeedback.invalid', {
+          defaultValue: 'Check the highlighted fields and try again.',
+        }),
+        failed: t('formFeedback.failed', {
+          defaultValue: 'Unable to save. Your input has been kept. Try again.',
+        }),
+        network: t('formFeedback.network', {
+          defaultValue:
+            'Unable to connect. Check your connection and try again. Your input has been kept.',
+        }),
+        denied: t('formFeedback.denied', {
+          defaultValue:
+            'You cannot submit this form with your current access. Your input has been kept.',
+        }),
+      },
+      ...(fieldMessage ? { fieldMessage } : {}),
+    }),
+    [t, fieldMessage],
+  );
+  const [owned] = useState(() => new FormFeedback(options));
+  const feedback = supplied ?? owned;
+  useLayoutEffect(() => {
+    feedback.configure(options);
+  }, [feedback, options]);
+  const state = useSyncExternalStore(
+    feedback.subscribe,
+    feedback.getSnapshot,
+    feedback.getSnapshot,
+  );
+  const [unfocusableState, setUnfocusableState] = useState<FormFeedbackState>();
+  const formRef = useRef<HTMLFormElement>(null);
+  const messageRef = useRef<HTMLDivElement>(null);
+  const attemptRef = useRef<FormFeedbackAttempt | undefined>(undefined);
+  const prefixId = useId();
+  const localValidationRef = useRef(false);
+  const focusPendingRef = useRef(false);
+  const controlsRef = useRef(
+    new Map<
+      HTMLElement,
+      { field: FormFeedbackField; unregister: () => void }
+    >(),
+  );
+  const generatedRef = useRef(0);
+  const [, redraw] = useReducer((value: number) => value + 1, 0);
+
+  useEffect(() => {
+    const element = formRef.current;
+    if (!element) return;
+    const registered = controlsRef.current;
+    const collect = () => {
+      for (const [control, entry] of registered)
+        if (!element.contains(control)) {
+          entry.unregister();
+          registered.delete(control);
+        }
+      for (const control of element.querySelectorAll<HTMLElement>(
+        'input[name], textarea[name], select[name], [data-field-path]',
+      )) {
+        if (registered.has(control)) continue;
+        // Application descriptors take precedence for custom/virtualized fields.
+        const path = () =>
+          control.dataset.fieldPath ?? control.getAttribute('name') ?? '';
+        if (feedback.hasPath(path())) continue;
+        const id = `${prefixId}-field-${++generatedRef.current}`;
+        const field: FormFeedbackField = {
+          id,
+          path,
+          label: () => fieldLabel(control),
+          anchor: () => control,
+          control: () => control,
+          value: () => {
+            if (control instanceof HTMLInputElement) {
+              if (control.type === 'file')
+                return Array.from(control.files ?? []);
+              if (control.type === 'checkbox' || control.type === 'radio')
+                return control.checked;
+            }
+            return 'value' in control ? control.value : control.textContent;
+          },
+          accessible: () =>
+            element.contains(control) &&
+            !control.closest(
+              '[data-feedback-hidden], [hidden], [inert], [aria-hidden="true"]',
+            ) &&
+            ancestors(control).every((element) => {
+              const style = getComputedStyle(element);
+              return style.display !== 'none' && style.visibility !== 'hidden';
+            }) &&
+            !(control instanceof HTMLInputElement && control.type === 'hidden'),
+          editable: () =>
+            !control.matches(':disabled, [aria-disabled="true"], [readonly]'),
+          reveal: () => {
+            for (const details of ancestors(control))
+              if (details instanceof HTMLDetailsElement) details.open = true;
+          },
+        };
+        registered.set(control, {
+          field,
+          unregister: feedback.register(field),
+        });
+      }
+    };
+    collect();
+    const observer = new MutationObserver(() => {
+      collect();
+      redraw();
+    });
+    observer.observe(element, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: [
+        'hidden',
+        'inert',
+        'aria-hidden',
+        'disabled',
+        'data-feedback-hidden',
+      ],
+    });
+    const change = (event: Event) => {
+      const control = event.target;
+      if (control instanceof HTMLElement) {
+        const entry = registered.get(control);
+        if (entry) feedback.clear(entry.field.id);
+        else feedback.clearControl(control);
+      }
+    };
+    element.addEventListener('input', change);
+    element.addEventListener('change', change);
+    return () => {
+      observer.disconnect();
+      element.removeEventListener('input', change);
+      element.removeEventListener('change', change);
+      for (const entry of registered.values()) entry.unregister();
+      registered.clear();
+    };
+  }, [feedback, prefixId]);
+
+  useEffect(() => {
+    if (!error || !attemptRef.current) return;
+    if (feedback.getAttemptSequence() !== attemptRef.current.sequence) return;
+    focusPendingRef.current = true;
+    feedback.failure(error, attemptRef.current);
+  }, [error, feedback]);
+
+  useEffect(() => {
+    if (
+      (state.message || state.fields.length) &&
+      focusPendingRef.current &&
+      !submitting
+    ) {
+      focusPendingRef.current = false;
+      void feedback.focus(messageRef.current, undefined, () => {
+        if (!state.message && feedback.getSnapshot() === state)
+          setUnfocusableState(state);
+      });
+    }
+  }, [state, feedback, submitting]);
+
+  // Existing controlled validators keep their messages and state. Adopt their invalid controls once per submission.
+  useEffect(() => {
+    if (
+      validationErrors !== undefined ||
+      !localValidationRef.current ||
+      !attemptRef.current
+    )
+      return;
+    if (state.fields.length) {
+      localValidationRef.current = false;
+      return;
+    }
+    const invalid = [...controlsRef.current.keys()].filter(
+      (control) => control.getAttribute('aria-invalid') === 'true',
+    );
+    if (!invalid.length) return;
+    localValidationRef.current = false;
+    focusPendingRef.current = true;
+    feedback.invalid(
+      invalid.map((control) => {
+        return {
+          field:
+            control.dataset.fieldPath ?? control.getAttribute('name') ?? '',
+          message:
+            (existingFieldError(control)?.textContent ||
+              options.messages.field) ??
+            options.messages.invalid,
+        };
+      }),
+      attemptRef.current,
+    );
+  });
+
+  const validationKey = JSON.stringify(formFeedbackErrors(validationErrors));
+  const attemptSequence = feedback.getAttemptSequence();
+  useEffect(() => {
+    if (
+      !localValidationRef.current ||
+      submitting ||
+      !attemptSequence ||
+      !attemptRef.current
+    )
+      return;
+    localValidationRef.current = false;
+    if (validationKey === '[]') return;
+    const errors = formFeedbackErrors(validationErrors);
+    if (errors.length) {
+      focusPendingRef.current = true;
+      feedback.invalid(errors, attemptRef.current);
+    }
+  }, [validationErrors, validationKey, feedback, attemptSequence, submitting]);
+
+  const errors = feedback.errors();
+  const inaccessible = state.fields.length > 0 && errors.length === 0;
+  const formMessage =
+    state.message ||
+    (inaccessible || unfocusableState === state
+      ? options.messages.failed
+      : undefined);
+  useLayoutEffect(() => {
+    if (inaccessible || unfocusableState === state) messageRef.current?.focus();
+  }, [state, inaccessible, unfocusableState]);
+  useLayoutEffect(() => {
+    const restore: (() => void)[] = [];
+    for (const entry of errors) {
+      const control = feedback.field(entry.id)?.control();
+      if (!control) continue;
+      const describedBy = control.getAttribute('aria-describedby');
+      const invalid = control.getAttribute('aria-invalid');
+      const ownsInvalid = invalid !== 'true';
+      const existing = existingFieldError(control);
+      const previousId = existing?.getAttribute('id');
+      const id = existing?.id || `${entry.id}-error`;
+      const ownsDescription = !(describedBy?.split(/\s+/) ?? []).includes(id);
+      if (existing && !existing.id) existing.id = id;
+      control.setAttribute('aria-invalid', 'true');
+      control.setAttribute(
+        'aria-describedby',
+        [...new Set([...(describedBy?.split(/\s+/) ?? []), id])]
+          .filter(Boolean)
+          .join(' '),
+      );
+      restore.push(() => {
+        if (existing && previousId === null && existing.id === id)
+          existing.removeAttribute('id');
+        // React may already have committed new caller-owned attributes. Remove only our additions.
+        if (ownsDescription) {
+          const remaining = (control.getAttribute('aria-describedby') ?? '')
+            .split(/\s+/)
+            .filter((value) => value && value !== id);
+          if (remaining.length)
+            control.setAttribute('aria-describedby', remaining.join(' '));
+          else control.removeAttribute('aria-describedby');
+        }
+        if (ownsInvalid && control.getAttribute('aria-invalid') === 'true') {
+          if (invalid === null) control.removeAttribute('aria-invalid');
+          else control.setAttribute('aria-invalid', invalid);
+        }
+      });
+    }
+    return () => {
+      for (const reset of restore) reset();
+    };
+  });
+
+  return (
+    <form
+      {...props}
+      noValidate
+      ref={(element) => {
+        formRef.current = element;
+        if (typeof ref === 'function') return ref(element);
+        if (ref) ref.current = element;
+      }}
+      onSubmit={(event) => {
+        event.preventDefault();
+        const current = feedback.begin();
+        attemptRef.current = current;
+        localValidationRef.current = true;
+        const invalid = [...event.currentTarget.elements].filter(
+          (
+            control,
+          ): control is
+            HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement =>
+            (control instanceof HTMLInputElement ||
+              control instanceof HTMLSelectElement ||
+              control instanceof HTMLTextAreaElement) &&
+            !noValidate &&
+            control.willValidate &&
+            !control.validity.valid,
+        );
+        if (invalid.length) {
+          event.preventDefault();
+          focusPendingRef.current = true;
+          feedback.invalid(
+            invalid.map((control) => ({
+              field: control.dataset.fieldPath ?? control.name,
+              message: control.validationMessage,
+            })),
+            current,
+          );
+          return;
+        }
+        try {
+          const result = onSubmit?.(event);
+          if (result)
+            void result.catch((next: unknown) => {
+              if (feedback.getAttemptSequence() !== current.sequence) return;
+              focusPendingRef.current = true;
+              feedback.failure(next, current);
+            });
+        } catch (next) {
+          if (feedback.getAttemptSequence() !== current.sequence) return;
+          focusPendingRef.current = true;
+          feedback.failure(next, current);
+        }
+      }}
+    >
+      {(formMessage ||
+        (!attemptSequence && Boolean(error) && errorContent != null)) && (
+        <div
+          ref={messageRef}
+          role='alert'
+          tabIndex={-1}
+          className='space-y-2 text-sm text-destructive'
+        >
+          {error && errors.length === 0 && errorContent != null ? (
+            errorContent
+          ) : (
+            <p>{formMessage}</p>
+          )}
+        </div>
+      )}
+      {children}
+      {errors.map((entry) => {
+        const control = feedback.field(entry.id)?.control();
+        return control?.parentElement && !existingFieldError(control)
+          ? createPortal(
+              <p
+                id={`${entry.id}-error`}
+                data-form-feedback-error
+                className='text-sm text-destructive'
+              >
+                {entry.message}
+              </p>,
+              control.parentElement,
+              entry.id,
+            )
+          : null;
+      })}
+    </form>
+  );
+}
+
+function ancestors(control: HTMLElement): HTMLElement[] {
+  const result: HTMLElement[] = [];
+  for (
+    let parent = control.parentElement;
+    parent;
+    parent = parent.parentElement
+  )
+    result.unshift(parent);
+  return result;
+}
+
+/** Only explicitly associated application error nodes are trusted, never arbitrary nearby text. */
+function existingFieldError(control: HTMLElement): HTMLElement | undefined {
+  const errorIds = (control.getAttribute('aria-errormessage') ?? '').split(
+    /\s+/,
+  );
+  const described = (control.getAttribute('aria-describedby') ?? '')
+    .split(/\s+/)
+    .map((id) => control.ownerDocument.getElementById(id))
+    .filter((node) =>
+      node?.matches('[data-slot="field-error"], [data-feedback-field-error]'),
+    );
+  const slot = control
+    .closest('[data-slot="field"]')
+    ?.querySelector<HTMLElement>('[data-slot="field-error"]');
+  return [
+    ...errorIds.map((id) => control.ownerDocument.getElementById(id)),
+    ...described,
+    slot,
+  ].find((node): node is HTMLElement =>
+    Boolean(node && !node.hasAttribute('data-form-feedback-error')),
+  );
+}
+
+/** Resolve explicit accessible names; group entry buttons may use their visible text. */
+function fieldLabel(control: HTMLElement): string {
+  const labelledBy = (control.getAttribute('aria-labelledby') ?? '')
+    .split(/\s+/)
+    .map((id) => control.ownerDocument.getElementById(id)?.textContent?.trim())
+    .filter(Boolean)
+    .join(' ');
+  if (labelledBy) return labelledBy;
+  const ariaLabel = control.getAttribute('aria-label')?.trim();
+  if (ariaLabel) return ariaLabel;
+  if ('labels' in control) {
+    const labels = Array.from(
+      (control as HTMLInputElement).labels ?? [],
+      (label) => label.textContent?.trim(),
+    )
+      .filter(Boolean)
+      .join(' ');
+    if (labels) return labels;
+  }
+  return control.matches('button, [role="button"]')
+    ? (control.textContent?.trim() ?? '')
+    : '';
+}