@verbb/formie-browser 1.0.13 → 1.0.15

package/src/js/core/field-error-aria.ts

@@ -0,0 +1,93 @@
+/**
+ * Field-error ARIA helpers.
+ *
+ * Pair `aria-errormessage` with `aria-describedby` pointing at the same error
+ * message id. `aria-errormessage` alone is inconsistently announced (notably
+ * iOS Safari + VoiceOver); Adrian Roselli's cross-AT testing found the pairing
+ * more reliable without clobbering instruction ids already on describedby.
+ */
+
+export function appendDescribedBy(input: HTMLElement, describedById: string): void {
+    const current = (input.getAttribute('aria-describedby') || '').trim();
+    const items = current ? current.split(/\s+/) : [];
+
+    if (!items.includes(describedById)) {
+        items.push(describedById);
+    }
+
+    input.setAttribute('aria-describedby', items.join(' ').trim());
+}
+
+export function removeDescribedBy(input: HTMLElement, describedById: string): void {
+    const current = (input.getAttribute('aria-describedby') || '').trim();
+
+    if (!current) {
+        return;
+    }
+
+    const filtered = current.split(/\s+/).filter((item) => {
+        return item !== describedById;
+    });
+
+    if (filtered.length) {
+        input.setAttribute('aria-describedby', filtered.join(' '));
+        return;
+    }
+
+    input.removeAttribute('aria-describedby');
+}
+
+/**
+ * Drop describedby ids whose targets no longer exist (Formie removes error
+ * message nodes from the DOM when clearing). Keeps instruction/other ids.
+ */
+export function pruneMissingDescribedBy(input: HTMLElement, doc: Document = document): void {
+    const current = (input.getAttribute('aria-describedby') || '').trim();
+
+    if (!current) {
+        return;
+    }
+
+    const remaining = current.split(/\s+/).filter((id) => {
+        return !!id && !!doc.getElementById(id);
+    });
+
+    if (remaining.length) {
+        input.setAttribute('aria-describedby', remaining.join(' '));
+        return;
+    }
+
+    input.removeAttribute('aria-describedby');
+}
+
+export function setErrorMessageReference(input: HTMLElement, errorMessageId: string): void {
+    input.setAttribute('aria-errormessage', errorMessageId);
+    // Same id in describedby so AT that ignore aria-errormessage still hear it.
+    appendDescribedBy(input, errorMessageId);
+}
+
+export function clearErrorMessageReference(input: HTMLElement, errorMessageId: string): void {
+    if (input.getAttribute('aria-errormessage') === errorMessageId) {
+        input.removeAttribute('aria-errormessage');
+    }
+
+    removeDescribedBy(input, errorMessageId);
+}
+
+/**
+ * Clear errormessage refs and prune any describedby ids that no longer resolve
+ * (covers message nodes removed from the DOM and legacy container ids).
+ */
+export function clearFieldErrorAria(input: HTMLElement, errorMessageIds: string[] = []): void {
+    errorMessageIds.forEach((errorMessageId) => {
+        if (input.getAttribute('aria-errormessage') === errorMessageId) {
+            input.removeAttribute('aria-errormessage');
+        }
+    });
+
+    if (!errorMessageIds.length && input.hasAttribute('aria-errormessage')) {
+        input.removeAttribute('aria-errormessage');
+    }
+
+    pruneMissingDescribedBy(input);
+}

package/src/js/core/hydrate-modules.ts

@@ -1,7 +1,6 @@
 import type { FormEventUnsubscribe } from '#contracts/client';
-import type { FormMode } from '#contracts/common';
-import type { FormieModuleDefinition, FormieModuleInstance, ModuleRegistrationOptions } from '#contracts/modules';
-import type { FormModuleManifest } from '#contracts/schema';
+import type { BrowserModuleDefinition, BrowserModuleHydrationReport, ModuleRegistrationOptions } from '#contracts/modules';
+import type { BrowserModuleEntry } from '#contracts/schema';
 import { EventBus } from '#events/event-bus';
 import { loadModulesFromManifest } from '#modules/loader';
 import { ModuleRegistry } from '#modules/registry';
@@ -10,34 +9,38 @@ import { createDebug } from '#utils/debug';
 export type FormieModuleHydratorOptions = {
     root: Element;
     form?: HTMLFormElement | null;
-    modules?: FormModuleManifest[];
-    mode?: FormMode;
+    modules?: import('@verbb/formie-core').BrowserModuleManifest;
+    surface?: import('@verbb/formie-core').BrowserSurface;
     registry?: ModuleRegistry;
 };
 
-export type FormieModuleHydrator = {
+export type FormieModuleHydrator = BrowserModuleHydrationReport & {
+    assertReady: () => void;
+    prepare: (action: import('@verbb/formie-core').ClientSubmitAction) => Promise<Record<string, unknown>>;
+    result: (result: import('#contracts/schema').FormSubmitResult) => Promise<void>;
+    update: (manifest: import('@verbb/formie-core').BrowserModuleManifest) => Promise<void>;
     destroy: () => Promise<void>;
     on: (eventName: string, callback: (payload: unknown) => void | Promise<void>) => FormEventUnsubscribe;
     emit: (eventName: string, payload?: unknown) => Promise<void>;
-    registerModule: (moduleDefinition: FormieModuleDefinition, options?: ModuleRegistrationOptions) => boolean;
+    registerModule: (moduleDefinition: BrowserModuleDefinition, options?: ModuleRegistrationOptions) => boolean;
     unregisterModule: (moduleId: string) => void;
-    getRegisteredModules: () => FormieModuleDefinition[];
+    getRegisteredModules: () => BrowserModuleDefinition[];
 };
 
 const debug = createDebug('general', 'module-hydrator');
 
 export async function hydrateFormieModules(options: FormieModuleHydratorOptions): Promise<FormieModuleHydrator> {
     const root = options.root;
-    const form = options.form ?? (root instanceof HTMLFormElement ? root : root.closest('form'));
-    const modules = options.modules ?? [];
-    const mode = options.mode ?? 'server-rendered';
+    const form = options.form ?? (root instanceof HTMLFormElement ? root : root.closest('form') ?? root.querySelector('form'));
+    const surface = options.surface ?? 'cp-edit';
+    const modules = options.modules ?? { contractVersion: 2, surface, entries: [] };
     const registry = options.registry ?? new ModuleRegistry();
     const bus = new EventBus();
 
     // This helper reuses the canonical module manifest loader without mounting the
-    // full form client, which lets non-frontend hosts like the CP opt into shared
+    // full form client, which lets CP edit hosts opt into shared
     // field modules without inheriting submit or pagination ownership.
-    const instances = await loadModulesFromManifest(modules, {
+    const runtime = await loadModulesFromManifest(modules, {
         registry,
         setupContext: {
             formId: form?.id || (root as HTMLElement).id || 'formie-modules',
@@ -45,31 +48,64 @@ export async function hydrateFormieModules(options: FormieModuleHydratorOptions)
             form,
             target: root,
             scope: 'form',
+            surface,
             state: {},
             options: {},
             on: (eventName, callback) => {
                 return bus.on(eventName, callback);
             },
             emit: async(eventName, payload) => {
+                root.dispatchEvent(new CustomEvent(eventName, { detail: payload, bubbles: true }));
                 await bus.emit(eventName, payload);
             },
         },
         matchContext: {
             root,
             form,
-            mode,
+            surface,
         },
     });
 
     debug.log('Hydrated module manifest.', {
-        moduleCount: modules.length,
-        instanceCount: instances.length,
-        mode,
+        moduleCount: modules.entries.length,
+        instanceCount: runtime.instances.length,
+        surface,
     });
 
     return {
+        get instances() { return runtime.instances; },
+        get failures() { return runtime.failures; },
+        prepare: async(action) => {
+            if (!form) throw new Error('Browser modules require a mounted form element.');
+            runtime.assertReady();
+            runtime.instances.forEach((instance) => instance.assertReady?.());
+            let reason: string | undefined;
+            const context = {
+                form, action: action === 'back' || action === 'save' ? action : 'submit' as const,
+                formData: new FormData(form),
+                abort: (message?: string) => { reason = message || 'A form feature could not complete.'; },
+                isAborted: () => Boolean(reason), abortReason: () => reason,
+            };
+            const priority = { core: 0, field: 0, address: 0, captcha: 1, payment: 2 };
+            for (const instance of [...runtime.instances].sort((a, b) => priority[a.kind ?? 'core'] - priority[b.kind ?? 'core'])) {
+                await instance.beforeSubmit?.(context);
+                if (reason) throw new Error(reason);
+            }
+            // Only transient module inputs cross this seam. PHP reads CAPTCHA data
+            // and payment fields without allowing arbitrary request/authority overrides.
+            return Object.fromEntries(Array.from(form.querySelectorAll<HTMLInputElement>('input[type="hidden"][name]')).map((input) => [input.name, input.value]));
+        },
+        result: async(result) => {
+            if (!form) return;
+            const context = { form, action: result.action ?? 'submit' as const, formData: new FormData(form) };
+            await bus.emit('formie:submit:result', result);
+            for (const instance of runtime.instances) await instance.afterSubmit?.(context, result);
+            form.dispatchEvent(new CustomEvent('formie:submit:result', { detail: result, bubbles: true }));
+        },
+        update: (manifest) => runtime.updateManifest(manifest),
+        assertReady: () => { runtime.assertReady(); runtime.instances.forEach((instance) => instance.assertReady?.()); },
         destroy: async() => {
-            await destroyModuleInstances(instances);
+            await runtime.destroy();
             bus.clear();
         },
         on: (eventName, callback) => {
@@ -89,14 +125,3 @@ export async function hydrateFormieModules(options: FormieModuleHydratorOptions)
         },
     };
 }
-
-async function destroyModuleInstances(instances: FormieModuleInstance[]): Promise<void> {
-    for (const instance of instances) {
-        try {
-            await instance.destroy();
-        } catch (error) {
-            console.error('[formie] Failed to destroy module instance.', error);
-            debug.warn('Failed destroying module instance.', { error });
-        }
-    }
-}

package/src/js/core/submit-result-state.ts

@@ -99,22 +99,17 @@ function getProgressState(progress: number): 'start' | 'middle' | 'end' {
     return 'middle';
 }
 
-function getConfiguredSubmitAction(form: HTMLFormElement): string {
-    return (form.dataset.formieSubmitAction || '').trim();
+function getConfiguredCompletionBehavior(form: HTMLFormElement): string {
+    return (form.dataset.formieCompletionBehavior || form.dataset.formieSubmitAction || '').trim();
 }
 
-function getResolvedSubmitAction(form: HTMLFormElement, result: FormSubmitResult): string {
-    const fromResponse = result.meta?.effectiveSubmitAction;
-
-    if (typeof fromResponse === 'string' && fromResponse.trim() !== '') {
-        return fromResponse.trim();
-    }
-
-    return getConfiguredSubmitAction(form);
+function getResolvedCompletionBehavior(form: HTMLFormElement, result: FormSubmitResult): string {
+    if (result.completion) return String(result.completion.behavior);
+    return getConfiguredCompletionBehavior(form);
 }
 
 function shouldHideFormOnSuccess(form: HTMLFormElement): boolean {
-    const rawValue = form.dataset.formieSubmitActionFormHide;
+    const rawValue = form.dataset.formieHideFormAfterSubmit ?? form.dataset.formieSubmitActionFormHide;
 
     if (rawValue === undefined) {
         return false;
@@ -199,7 +194,7 @@ function applyCompletedProgressState(form: HTMLFormElement): void {
 
 function scheduleFinalSubmitReset(form: HTMLFormElement): void {
     clearPendingFinalSubmitReset(form);
-    const preserveHiddenState = getConfiguredSubmitAction(form) === 'message' && shouldHideFormOnSuccess(form);
+    const preserveHiddenState = getConfiguredCompletionBehavior(form) === 'message' && shouldHideFormOnSuccess(form);
 
     if (DEFAULT_FINAL_SUBMIT_RESET_DELAY_MS < 1) {
         resetSubmissionState(form, { preserveHiddenState });
@@ -300,12 +295,10 @@ export function clearSubmitLoading(form: HTMLFormElement): void {
         button.removeAttribute('data-formie-loading-text');
     });
 
-    if (form.dataset.formieDisableSubmitUntilValid === 'true') {
-        const formWithValidation = form as FormWithValidationApi;
+    const formWithValidation = form as FormWithValidationApi;
 
-        if (formWithValidation.formieValidation) {
-            syncSubmitReadiness(form, formWithValidation.formieValidation);
-        }
+    if (formWithValidation.formieValidation) {
+        syncSubmitReadiness(form, formWithValidation.formieValidation);
     }
 }
 
@@ -370,27 +363,41 @@ export function applyPageState(form: HTMLFormElement, nextPageId: string): void
     setHiddenInputValue(form, 'pageId', nextPageId);
     syncPageTabErrors(form);
 
-    if (form.dataset.formieDisableSubmitUntilValid === 'true') {
-        const formWithValidation = form as FormWithValidationApi;
+    const formWithValidation = form as FormWithValidationApi;
 
-        if (formWithValidation.formieValidation) {
-            syncSubmitReadiness(form, formWithValidation.formieValidation);
-        }
+    if (formWithValidation.formieValidation) {
+        syncSubmitReadiness(form, formWithValidation.formieValidation);
     }
 }
 
 function syncSubmissionIdentity(form: HTMLFormElement, result: FormSubmitResult): void {
+    if (result.meta?.resetSubmissionIdentity === true) {
+        // Saved spam is terminal. Preserve the entered values for correction,
+        // but do not try to continue the rejected record on the next submit.
+        removeHiddenInput(form, 'submissionId');
+        removeHiddenInput(form, 'submissionUid');
+        removeHiddenInput(form, 'progressId');
+        setHiddenInputValue(form, 'expectedVersion', '0');
+        clearResumeTokenState(form);
+        return;
+    }
+
+    const session = result.meta?.session as { version?: number } | undefined;
+    const version = session?.version ?? result.meta?.version;
+    if (typeof version === 'number') {
+        setHiddenInputValue(form, 'expectedVersion', String(version));
+    }
     const submissionUid = result.meta?.submissionUid;
     if (typeof submissionUid === 'string' && submissionUid.trim() !== '') {
         setHiddenInputValue(form, 'submissionUid', submissionUid);
     }
 
-    const continuationToken = (result.meta?.session as { continuation?: { continuationToken?: unknown } } | undefined)
-        ?.continuation?.continuationToken;
-    if (typeof continuationToken === 'string' && continuationToken.trim() !== '') {
-        setHiddenInputValue(form, 'continuationToken', continuationToken);
+    const progressId = (result.meta?.session as { continuation?: { progressId?: unknown } } | undefined)
+        ?.continuation?.progressId;
+    if (typeof progressId === 'string' && progressId.trim() !== '') {
+        setHiddenInputValue(form, 'progressId', progressId);
     } else {
-        removeHiddenInput(form, 'continuationToken');
+        removeHiddenInput(form, 'progressId');
     }
 }
 
@@ -457,8 +464,9 @@ function resetSubmissionState(form: HTMLFormElement, options: ResetSubmissionSta
         setFormHiddenState(form, false);
     }
     removeHiddenInput(form, 'submissionId');
+    setHiddenInputValue(form, 'expectedVersion', '0');
     removeHiddenInput(form, 'submissionUid');
-    removeHiddenInput(form, 'continuationToken');
+    removeHiddenInput(form, 'progressId');
     removeHiddenInput(form, 'pageId');
     clearResumeTokenState(form);
     validator?.resetLiveState();
@@ -508,15 +516,7 @@ function dispatchSubmitDataEvents(form: HTMLFormElement, result: FormSubmitResul
         }
     }
 
-    // Fallback: some payment action-required responses can carry action payloads
-    // as `paymentAction`/`paymentDecision` metadata without submitData entries.
-    const meta = (result.meta || {}) as Record<string, unknown>;
-    const paymentAction = (
-        (meta.paymentAction && typeof meta.paymentAction === 'object' ? meta.paymentAction : null)
-        || (meta.paymentDecision && typeof meta.paymentDecision === 'object'
-            ? ((meta.paymentDecision as Record<string, unknown>).action as Record<string, unknown> | null)
-            : null)
-    ) as Record<string, unknown> | null;
+    const paymentAction = result.payment?.action;
 
     const actionEvent = paymentAction ? String(paymentAction.event || '') : '';
     const actionPayload = paymentAction ? paymentAction.payload : undefined;
@@ -553,6 +553,12 @@ export function applySubmitResultState(form: HTMLFormElement, result: FormSubmit
         return;
     }
 
+    // Provider handlers may navigate as soon as their action event is dispatched.
+    // Treat checkout navigation like the generic redirect before invoking them.
+    if (result.payment?.action?.type === 'redirect' && result.payment.action.url) {
+        markInternalNavigation(form, 'payment-redirect');
+    }
+
     // Dispatch payment/redirect events from submitData (e.g. formie:payment:mollie:redirect)
     const eventDispatchResult = dispatchSubmitDataEvents(form, result);
 
@@ -564,7 +570,7 @@ export function applySubmitResultState(form: HTMLFormElement, result: FormSubmit
         });
         clearPendingFinalSubmitReset(form);
         if (result.redirect.target === 'new-tab') {
-            window.open(result.redirect.url, '_blank');
+            window.open(result.redirect.url, '_blank', 'noopener,noreferrer');
         } else {
             markInternalNavigation(form, 'redirect');
             window.location.href = result.redirect.url;
@@ -609,18 +615,18 @@ export function applySubmitResultState(form: HTMLFormElement, result: FormSubmit
         return;
     }
 
-    if (action === 'submit' && !result.redirect?.url) {
-        const configuredSubmitAction = getResolvedSubmitAction(form, result);
-        const preserveHiddenState = configuredSubmitAction === 'message' && shouldHideFormOnSuccess(form);
+    if (result.completion && action === 'submit' && !result.redirect?.url) {
+        const completionBehavior = getResolvedCompletionBehavior(form, result);
+        const preserveHiddenState = completionBehavior === 'message' && shouldHideFormOnSuccess(form);
 
-        if (configuredSubmitAction === 'reload') {
+        if (completionBehavior === 'reload') {
             clearPendingFinalSubmitReset(form);
             markInternalNavigation(form, 'reload');
             window.location.reload();
             return;
         }
 
-        if (configuredSubmitAction === 'reset') {
+        if (completionBehavior === 'reset') {
             resetSubmissionState(form);
             return;
         }
@@ -633,8 +639,8 @@ export function applySubmitResultState(form: HTMLFormElement, result: FormSubmit
     }
 
     if (action === 'submit' && result.redirect?.url && result.redirect.target === 'new-tab') {
-        const configuredSubmitAction = getResolvedSubmitAction(form, result);
-        const preserveHiddenState = configuredSubmitAction === 'message' && shouldHideFormOnSuccess(form);
+        const completionBehavior = getResolvedCompletionBehavior(form, result);
+        const preserveHiddenState = completionBehavior === 'message' && shouldHideFormOnSuccess(form);
         clearPendingFinalSubmitReset(form);
         resetSubmissionState(form, { preserveHiddenState });
         return;

package/src/js/core/submit-result-ui.ts

@@ -1,5 +1,10 @@
 import type { FormSubmitResult } from '#contracts/schema';
 import { applyErrorAriaLive, getErrorAriaLivePreference, resolveSubmitErrorAriaLive } from '#core/error-aria-live';
+import {
+    appendDescribedBy,
+    clearFieldErrorAria,
+    setErrorMessageReference,
+} from '#core/field-error-aria';
 import { ensureFieldErrorContainer as resolveFieldErrorContainer } from '#core/field-error-container';
 import { syncPageTabErrors } from '#core/page-tab-errors';
 import { focusFirstValidationError } from '#core/validation-focus';
@@ -8,8 +13,8 @@ import { addThemeClasses, removeThemeClasses } from '#theme/theme-classes';
 
 const successHideTimers = new WeakMap<HTMLFormElement, number>();
 
-function getConfiguredSubmitAction(form: HTMLFormElement): string {
-    return (form.dataset.formieSubmitAction || '').trim();
+function getConfiguredCompletionBehavior(form: HTMLFormElement): string {
+    return (form.dataset.formieCompletionBehavior || form.dataset.formieSubmitAction || '').trim();
 }
 
 function getErrorMessagePosition(form: HTMLFormElement): string {
@@ -17,11 +22,11 @@ function getErrorMessagePosition(form: HTMLFormElement): string {
 }
 
 function getSuccessMessagePosition(form: HTMLFormElement): string {
-    return (form.dataset.formieSubmitActionMessagePosition || '').trim();
+    return (form.dataset.formieSuccessMessagePosition || form.dataset.formieSubmitActionMessagePosition || '').trim();
 }
 
 function getSuccessMessageTimeoutMs(form: HTMLFormElement): number | null {
-    const rawValue = (form.dataset.formieSubmitActionMessageTimeout || '').trim();
+    const rawValue = (form.dataset.formieSuccessMessageTimeout || form.dataset.formieSubmitActionMessageTimeout || '').trim();
 
     if (!rawValue) {
         return null;
@@ -37,7 +42,7 @@ function getSuccessMessageTimeoutMs(form: HTMLFormElement): number | null {
 }
 
 function shouldHideFormOnSuccess(form: HTMLFormElement): boolean {
-    const rawValue = form.dataset.formieSubmitActionFormHide;
+    const rawValue = form.dataset.formieHideFormAfterSubmit ?? form.dataset.formieSubmitActionFormHide;
 
     if (rawValue === undefined) {
         return false;
@@ -160,40 +165,10 @@ function ensureFieldErrorContainer(fieldNode: Element): HTMLElement {
     });
 }
 
-function removeDescribedBy(input: HTMLElement, describedById: string): void {
-    const current = (input.getAttribute('aria-describedby') || '').trim();
-
-    if (!current) {
-        return;
-    }
-
-    const nextValue = current.split(/\s+/).filter((item) => {
-        return item !== describedById;
-    }).join(' ').trim();
-
-    if (nextValue) {
-        input.setAttribute('aria-describedby', nextValue);
-        return;
-    }
-
-    input.removeAttribute('aria-describedby');
-}
-
-function setErrorMessageReference(input: HTMLElement, errorMessageId: string): void {
-    input.setAttribute('aria-errormessage', errorMessageId);
-}
-
-function clearErrorMessageReference(input: HTMLElement, errorMessageId: string): void {
-    if (input.getAttribute('aria-errormessage') === errorMessageId) {
-        input.removeAttribute('aria-errormessage');
-    }
-}
-
 export function clearFieldErrors(form: HTMLFormElement): void {
     form.querySelectorAll('[data-formie-field-handle]').forEach((fieldNode) => {
         const fieldElement = fieldNode as HTMLElement;
         const container = fieldElement.querySelector('[data-formie-field-errors]') as HTMLElement | null;
-        const containerId = container?.id || '';
         const errorMessageIds = Array.from(fieldElement.querySelectorAll('[data-formie-field-error]')).map((node) => {
             return (node as HTMLElement).id;
         }).filter(Boolean);
@@ -214,14 +189,7 @@ export function clearFieldErrors(form: HTMLFormElement): void {
             element.removeAttribute('aria-invalid');
             removeThemeClasses(element, form, 'fieldControlError');
             element.removeAttribute('data-formie-input-has-error');
-
-            if (containerId) {
-                removeDescribedBy(element, containerId);
-            }
-
-            errorMessageIds.forEach((errorMessageId) => {
-                clearErrorMessageReference(element, errorMessageId);
-            });
+            clearFieldErrorAria(element, errorMessageIds);
         });
     });
 
@@ -275,7 +243,7 @@ export function clearFormSuccess(form: HTMLFormElement): void {
         }
     });
 
-    if (!(getConfiguredSubmitAction(form) === 'message' && shouldHideFormOnSuccess(form))) {
+    if (!(getConfiguredCompletionBehavior(form) === 'message' && shouldHideFormOnSuccess(form))) {
         setFormHiddenState(form, false);
     }
 }
@@ -286,22 +254,13 @@ export function clearAriaInvalid(form: HTMLFormElement): void {
     });
 }
 
-function appendDescribedBy(input: HTMLElement, describedById: string): void {
-    const current = (input.getAttribute('aria-describedby') || '').trim();
-    const items = current ? current.split(/\s+/) : [];
-
-    if (!items.includes(describedById)) {
-        items.push(describedById);
-    }
-
-    input.setAttribute('aria-describedby', items.join(' ').trim());
-}
-
 export function renderFieldErrors(form: HTMLFormElement, fieldErrors: Record<string, string[]>): void {
     const errorAriaLive = resolveSubmitErrorAriaLive(getErrorAriaLivePreference(form));
 
     Object.entries(fieldErrors).forEach(([handle, messages]) => {
-        const fieldNode = form.querySelector(`[data-formie-field-handle="${handle}"]`);
+        const inputName = `fields[${handle.split('.').join('][')}]`;
+        const exactInput = form.querySelector(`[name="${CSS.escape(inputName)}"], [name="${CSS.escape(inputName + '[]')}"]`);
+        const fieldNode = exactInput?.closest('[data-formie-field-handle]') || form.querySelector(`[data-formie-field-handle="${CSS.escape(handle)}"]`);
 
         if (!fieldNode) {
             return;
@@ -319,7 +278,6 @@ export function renderFieldErrors(form: HTMLFormElement, fieldErrors: Record<str
         messages.forEach((message, index) => {
             const errorNode = document.createElement('div');
             errorNode.setAttribute('data-formie-field-error', 'true');
-            errorNode.setAttribute('role', 'alert');
             errorNode.id = `${containerId}-${index + 1}`;
             addThemeClasses(errorNode, form, 'fieldError');
             errorNode.textContent = message;
@@ -327,7 +285,8 @@ export function renderFieldErrors(form: HTMLFormElement, fieldErrors: Record<str
         });
 
         // Point every control in the field at the first rendered message while
-        // still rendering the full list for visual output.
+        // still rendering the full list for visual output. Pair aria-errormessage
+        // with aria-describedby on that message id (#2946).
         const primaryErrorId = (container.querySelector('[data-formie-field-error]') as HTMLElement | null)?.id;
 
         fieldNode.querySelectorAll('input, select, textarea').forEach((input) => {
@@ -335,7 +294,6 @@ export function renderFieldErrors(form: HTMLFormElement, fieldErrors: Record<str
             element.setAttribute('aria-invalid', 'true');
             addThemeClasses(element, form, 'fieldControlError');
             element.setAttribute('data-formie-input-has-error', 'true');
-            appendDescribedBy(element, containerId);
 
             if (primaryErrorId) {
                 setErrorMessageReference(element, primaryErrorId);
@@ -372,10 +330,9 @@ function isPaymentFollowUpResult(result: FormSubmitResult): boolean {
         return false;
     }
 
-    const meta = (result.meta || {}) as Record<string, unknown>;
-    const paymentStatus = String(meta.paymentStatus || '');
+    const paymentStatus = result.payment?.status;
 
-    return paymentStatus === 'actionRequired' || paymentStatus === 'pending';
+    return paymentStatus === 'requiresAction' || paymentStatus === 'pending' || paymentStatus === 'unknown';
 }
 
 export function renderFormNotice(form: HTMLFormElement, message: string): void {
@@ -403,10 +360,10 @@ function shouldRenderSuccessMessage(form: HTMLFormElement, result: FormSubmitRes
         return true;
     }
 
-    return getConfiguredSubmitAction(form) === 'message' && getSuccessMessagePosition(form) !== '';
+    return getConfiguredCompletionBehavior(form) === 'message' && getSuccessMessagePosition(form) !== '';
 }
 
-export function renderFormSuccess(form: HTMLFormElement, message: string): void {
+export function renderFormSuccess(form: HTMLFormElement, message: string, options: { hideForm?: boolean } = {}): void {
     const position = getSuccessMessagePosition(form);
 
     if (!position) {
@@ -427,7 +384,7 @@ export function renderFormSuccess(form: HTMLFormElement, message: string): void
     successNode.innerHTML = message;
     container.appendChild(successNode);
 
-    if (shouldHideFormOnSuccess(form)) {
+    if (options.hideForm !== false && shouldHideFormOnSuccess(form)) {
         setFormHiddenState(form, true);
     }
 
@@ -451,7 +408,8 @@ export function applySubmitResultUi(form: HTMLFormElement, result: FormSubmitRes
 
     if (result.ok) {
         if (shouldRenderSuccessMessage(form, result)) {
-            renderFormSuccess(form, result.message || '');
+            // Saving progress acknowledges persistence without completing the form.
+            renderFormSuccess(form, result.message || '', { hideForm: result.action !== 'save' });
         }
 
         return;
@@ -459,8 +417,7 @@ export function applySubmitResultUi(form: HTMLFormElement, result: FormSubmitRes
 
     if (!result.ok) {
         if (isPaymentFollowUpResult(result)) {
-            const meta = (result.meta || {}) as Record<string, unknown>;
-            const message = String(meta.paymentMessage || '').trim();
+            const message = String(result.payment?.message || '').trim();
 
             if (message) {
                 renderFormNotice(form, message);