@verbb/formie-browser 1.0.13 → 1.0.15

package/src/js/core/client-rendered-modules.ts

@@ -0,0 +1,69 @@
+import { setFormBrowserRequestOptions } from '#utils/request-profile';
+import type { BrowserModuleKind, ClientFormInstance } from '@verbb/formie-core';
+import { hydrateFormieModules } from './hydrate-modules';
+import { ModuleRegistry, clientRenderedModuleRegistry } from '#modules/registry';
+
+// These modules are implemented by the shared core state engine or native
+// framework controls. Explicit delegation preserves every declared occurrence.
+const nativeModuleDelegations: Record<string, { kind: BrowserModuleKind; reason: string }> = {
+    conditions: { kind: 'core', reason: 'Core evaluates structured conditions and the adapter renders visibility.' },
+    repeater: { kind: 'field', reason: 'The adapter owns row markup and core owns row values.' },
+    signature: { kind: 'field', reason: 'The adapter owns its signature control and cleanup.' },
+    'file-upload': { kind: 'field', reason: 'The shared transport stages selected files and submits attachment capabilities.' },
+    'upload-manager': { kind: 'field', reason: 'Native file selection uses the shared staged upload transport.' },
+    'checkbox-radio': { kind: 'field', reason: 'Framework controls own checked state.' },
+    'text-limit': { kind: 'field', reason: 'Core validation enforces the structured minimum and maximum rules.' },
+    'date-picker': { kind: 'field', reason: 'The adapter renders the structured date input contract.' },
+};
+
+export async function mountClientRenderedModules(root: Element, instance: ClientFormInstance, registry = clientRenderedModuleRegistry) {
+    for (const [moduleName, delegation] of Object.entries(nativeModuleDelegations)) {
+        const moduleId = `formie:${moduleName}`;
+        if (registry.get(moduleId)) continue;
+        registry.register({
+            moduleId,
+            version: 2,
+            surfaces: ['client-rendered'],
+            kind: delegation.kind,
+            match: () => true,
+            setup: async(context) => {
+                await context.emit('formie:browser:module:delegated', { moduleId, reason: delegation.reason, target: context.target });
+                return { destroy: () => undefined };
+            },
+        });
+    }
+    const form = root instanceof HTMLFormElement ? root : root.querySelector('form');
+    const syncRequest = () => {
+        if (!form) return;
+        const state = instance.getState();
+        setFormBrowserRequestOptions(form, instance.getBrowserRequestOptions());
+        form.action = state.definition.submission.endpoint;
+        if (state.session.tokens.csrf) form.setAttribute('data-formie-csrf-param', state.session.tokens.csrf.name);
+        for (const [name, value] of Object.entries({ handle: state.definition.handle, ...(state.session.tokens.csrf ? { [state.session.tokens.csrf.name]: state.session.tokens.csrf.value } : {}) })) {
+            let input = form.querySelector<HTMLInputElement>(`input[type="hidden"][name="${CSS.escape(name)}"]`);
+            if (!input) { input = document.createElement('input'); input.type = 'hidden'; input.name = name; form.append(input); }
+            input.value = value;
+        }
+    };
+    syncRequest();
+    const unsubscribeRequest = instance.subscribe(syncRequest);
+    const host = await hydrateFormieModules({ root, modules: instance.getState().definition.modules, surface: 'client-rendered', registry });
+    instance.setBrowserModuleGuard(host.assertReady);
+    instance.setBrowserModulePreparation(host.prepare);
+    const unsubscribe = instance.on('formie:submit:result', (payload) => {
+        const result = payload as import('@verbb/formie-core').ClientSubmitResult;
+        const completion = result.completion;
+        if (result.success && completion) {
+            if (completion.behavior === 'redirect' && typeof completion.url === 'string') {
+                if (completion.target === 'new-tab') window.open(completion.url, '_blank', 'noopener,noreferrer');
+                else window.location.assign(completion.url);
+            } else if (completion.behavior === 'reload') {
+                window.location.reload();
+            } else if (completion.behavior === 'reset') {
+                instance.reset();
+            }
+        }
+        void host.result({ ok: result.success, outcome: result.outcome, version: result.version, submissionUid: result.submissionUid, errors: result.errors, session: result.session, completion: result.completion, meta: result as unknown as Record<string, unknown> });
+    });
+    return { ...host, get instances() { return host.instances; }, get failures() { return host.failures; }, destroy: async() => { unsubscribe(); unsubscribeRequest(); await host.destroy(); } };
+}

package/src/js/core/create-formie-client.ts

@@ -1,3 +1,5 @@
+import { setFormBrowserRequestOptions } from '#utils/request-profile';
+import { assertBrowserModuleManifest } from '@verbb/formie-core';
 import type {
     FormieClient,
     FormieFormInstance,
@@ -7,8 +9,8 @@ import { bindLegacyDomEventCompatibility } from '#compatibility/dom-adapter';
 import { resolveLegacyCompatibilityOptions } from '#compatibility/event-map';
 import { bindLegacyValidatorCompatibility } from '#compatibility/validator-adapter';
 import type { FormAction, FormMode, FormTransport } from '#contracts/common';
-import type { FormieModuleDefinition, FormieModuleInstance } from '#contracts/modules';
-import type { FormEndpointPayload, FormModuleManifest, FormSubmitResult } from '#contracts/schema';
+import type { BrowserModuleDefinition, BrowserModuleInstance } from '#contracts/modules';
+import type { FormEndpointPayload, BrowserModuleEntry, FormSubmitResult } from '#contracts/schema';
 import type { ThemeClassMap } from '#contracts/theme';
 import { dispatchFormieDomEvent } from '#core/dom-events';
 import { getErrorAriaLivePreference } from '#core/error-aria-live';
@@ -20,16 +22,17 @@ import {
     hasServerRenderedValidationErrors,
 } from '#core/validation-focus';
 import { clearSubmitFeedback, executeAjaxSubmitFlow, shouldKeepSubmitLoading } from '#core/submit-flow';
-import { applySubmitResultUi } from '#core/submit-result-ui';
+import { applySubmitResultUi, renderFieldErrors, renderFormErrors } from '#core/submit-result-ui';
 import { applyPageState, clearSubmitLoading, setSubmitLoading } from '#core/submit-result-state';
 import { EventBus } from '#events/event-bus';
 import { ModuleRegistry } from '#modules/registry';
-import { loadModulesFromManifest } from '#modules/loader';
+import { loadModulesFromManifest, type BrowserModuleRuntime } from '#modules/loader';
 import { registerThemeClassMap } from '#theme/theme-classes';
 import { runSubmitPipeline } from '#submit/pipeline';
 import { clearSubmissionOnUnload, requestGraphqlRender, requestRefreshTokens, requestRender, requestSetPage } from '#transport/forms-api';
 import { ensureFormStartedAt } from '#utils/form-started-at';
 import { createDebug } from '#utils/debug';
+import { waitForElementRemoval } from '#utils/async';
 import { createFormUnloadWarningGuard } from '#utils/unload-warning';
 import { getValidationScope } from '#validation/scope';
 import { FormieValidator } from '#validation/validator';
@@ -41,7 +44,7 @@ type InternalInstanceState = {
     bus: EventBus;
     form: HTMLFormElement | null;
     validator: FormieValidator | null;
-    modules: FormieModuleInstance[];
+    modules: BrowserModuleRuntime;
     unbinds: Array<() => void>;
     instance: FormieFormInstance;
 };
@@ -73,12 +76,12 @@ function parseBooleanOption(value: string | undefined, defaultValue: boolean): b
 }
 
 function inferStaticCacheOnLoadFromDataset(dataset: DOMStringMap): boolean {
-    if (dataset.formieRefreshTokens != null && dataset.formieRefreshTokens !== '') {
-        return parseBooleanOption(dataset.formieRefreshTokens, false);
+    if (dataset.formieRefreshTokens != null) {
+        return parseBooleanOption(dataset.formieRefreshTokens, true);
     }
 
-    if (dataset.formieStaticCache != null && dataset.formieStaticCache !== '') {
-        return parseBooleanOption(dataset.formieStaticCache, false);
+    if (dataset.formieStaticCache != null) {
+        return parseBooleanOption(dataset.formieStaticCache, true);
     }
 
     return false;
@@ -90,6 +93,7 @@ function inferOptionsFromElement(target: Element): FormMountOptions {
     return {
         mode: 'server-rendered',
         transport: (dataset.formieTransport as FormTransport) || 'rest',
+        profile: dataset.formieRequestProfile as FormMountOptions['profile'],
         formHandle: dataset.formieHandle,
         endpoint: dataset.formieEndpoint,
         staticCache: inferStaticCacheOnLoadFromDataset(dataset),
@@ -99,7 +103,10 @@ function inferOptionsFromElement(target: Element): FormMountOptions {
 }
 
 function normalizeMode(mode: FormMountOptions['mode'] | undefined): FormMode {
-    return mode || 'server-rendered';
+    if (mode && mode !== 'server-rendered') {
+        throw new Error('@verbb/formie-browser enhances server-rendered HTML only. Use @verbb/formie-core for client-rendered forms.');
+    }
+    return 'server-rendered';
 }
 
 function normalizeTransport(transport: FormMountOptions['transport'] | undefined): FormTransport {
@@ -153,7 +160,7 @@ function resolveHeadlessEndpoint(baseOrEndpoint: string | undefined, actionPath:
         return actionPath;
     }
 
-    if (candidate.includes('/actions/')) {
+    if (candidate.includes(actionPath)) {
         return candidate;
     }
 
@@ -206,7 +213,7 @@ function mergeSearchParams(sourceUrl: string | null, destinationUrl: string): st
     }
 }
 
-function normalizeHeadlessManagedUrls(target: Element, form: HTMLFormElement, options: FormMountOptions): void {
+function normalizeServerRenderedUrls(target: Element, form: HTMLFormElement, options: FormMountOptions): void {
     const baseEndpoint = options.endpoint || (target as HTMLElement).dataset.formieEndpoint;
     const submitAction = resolveHeadlessEndpoint(baseEndpoint, DEFAULT_HEADLESS_SUBMIT_ACTION);
     const existingAction = form.getAttribute('action');
@@ -228,11 +235,7 @@ function normalizeHeadlessManagedUrls(target: Element, form: HTMLFormElement, op
     });
 }
 
-function ensureSupportedHeadlessTransport(transport: FormTransport, mode: FormMode): void {
-    if (transport === 'graphql' && mode !== 'server-rendered') {
-        throw new Error(`Formie ${mode} mode does not support GraphQL transport yet.`);
-    }
-}
+
 
 function parseBooleanDatasetValue(value: string | undefined): boolean {
     if (value == null) {
@@ -339,6 +342,7 @@ function parseJsonAttribute<T>(element: Element | null, attributeName: string):
     try {
         return JSON.parse(rawValue) as T;
     } catch (error) {
+        if (attributeName === 'data-formie-modules') throw new Error('Invalid browser-module manifest JSON. Update Formie and its browser packages together.');
         console.error(`[formie] Failed to parse ${attributeName}.`, error);
         return null;
     }
@@ -354,7 +358,8 @@ function getEmbeddedPayload(target: Element, form: HTMLFormElement | null): Form
     // Server-rendered forms carry the same minimal payload shape that endpoint-
     // rendered forms receive, which keeps mount behavior identical in both flows.
     const modules = parseJsonAttribute<FormEndpointPayload['modules']>(payloadRoot, 'data-formie-modules');
-    const theme = parseJsonAttribute<FormEndpointPayload['theme']>(payloadRoot, 'data-formie-theme');
+    const theme = parseJsonAttribute<FormEndpointPayload['theme']>(payloadRoot, 'data-formie-theme-classes')
+        || parseJsonAttribute<FormEndpointPayload['theme']>(payloadRoot, 'data-formie-theme');
 
     if (!modules && !theme) {
         return null;
@@ -425,6 +430,8 @@ function applyRefreshTokensToForm(form: HTMLFormElement, refreshTokens: FormEndp
             csrfInput.name = refreshTokens.csrf.param;
             csrfInput.value = refreshTokens.csrf.token;
             csrfInput.setAttribute('autocomplete', 'off');
+            // Match server-rendered CSRF inputs so helpers can resolve custom token names.
+            csrfInput.setAttribute('data-formie-csrf', '');
             form.prepend(csrfInput);
         }
     }
@@ -443,6 +450,19 @@ function applyRefreshTokensToForm(form: HTMLFormElement, refreshTokens: FormEndp
         }
     }
 
+    if (refreshTokens.uploadCreateToken) {
+        let uploadCreateInput = form.querySelector('input[name="uploadCreateToken"]') as HTMLInputElement | null;
+
+        if (!uploadCreateInput) {
+            uploadCreateInput = document.createElement('input');
+            uploadCreateInput.type = 'hidden';
+            uploadCreateInput.name = 'uploadCreateToken';
+            form.append(uploadCreateInput);
+        }
+
+        uploadCreateInput.value = refreshTokens.uploadCreateToken;
+    }
+
     if (refreshTokens.captchas && typeof refreshTokens.captchas === 'object') {
         Object.values(refreshTokens.captchas).forEach((captchaEntry) => {
             if (!captchaEntry || typeof captchaEntry !== 'object') {
@@ -478,7 +498,6 @@ async function ensureHtmlRender(target: Element, options: FormMountOptions): Pro
         return options.payload;
     }
 
-    ensureSupportedHeadlessTransport(transport, mode);
 
     const hasForm = !!getFormFromTarget(target);
     const formHandle = options.formHandle || (target as HTMLElement).dataset.formieHandle;
@@ -501,11 +520,11 @@ async function ensureHtmlRender(target: Element, options: FormMountOptions): Pro
         ? resolveGraphqlEndpoint(options, target)
         : resolveHtmlRenderEndpoint(options, target);
     const payload = transport === 'graphql'
-        ? await requestGraphqlRender(endpoint, formHandle, renderOptions)
+        ? await requestGraphqlRender(endpoint, formHandle, renderOptions, options)
         : await requestRender(endpoint, formHandle, {
             ...renderOptions,
             endpoint,
-        });
+        }, options);
 
     if (payload?.html) {
         (target as HTMLElement).innerHTML = payload.html;
@@ -519,7 +538,6 @@ async function refreshTokensAfterSubmitIfNeeded(target: Element, options: FormMo
         return;
     }
 
-    ensureSupportedHeadlessTransport(normalizeTransport(options.transport), normalizeMode(options.mode));
 
     const formHandle = options.formHandle || (target as HTMLElement).dataset.formieHandle;
     if (!formHandle) {
@@ -531,7 +549,7 @@ async function refreshTokensAfterSubmitIfNeeded(target: Element, options: FormMo
     const endpoint = resolveRefreshTokensEndpoint(options, target);
     const renderIdInput = form.querySelector('input[name="renderId"]') as HTMLInputElement | null;
     const renderId = renderIdInput?.value || undefined;
-    const refreshTokens = await requestRefreshTokens(endpoint, formHandle, renderId);
+    const refreshTokens = await requestRefreshTokens(endpoint, formHandle, renderId, options, form?.querySelector<HTMLInputElement>('input[name="requestToken"]')?.value);
     applyRefreshTokensToForm(form, refreshTokens);
     dispatchFormieDomEvent(target, 'formie:refresh-tokens:refreshed', refreshTokens);
 }
@@ -543,7 +561,10 @@ function bindFormEvents(
     bus: EventBus,
     validator: FormieValidator | null,
     unbinds: Array<() => void>,
-): void {
+): () => void {
+    let captureBaseline = () => {};
+    form.dataset.formieRequestProfile = options.profile ?? 'same-origin-browser';
+    if (options.profile === 'cross-origin-public') form.dataset.formieSubmitMethod = 'ajax';
     const submitMethod = String(
         form.dataset.formieSubmitMethod || '',
     ).trim().toLowerCase();
@@ -567,6 +588,7 @@ function bindFormEvents(
                 return !hasInternalNavigation(form);
             },
         });
+        captureBaseline = unloadWarning.scheduleBaselineCapture;
         const handleSubmitResult = (event: Event): void => {
             if (!(event instanceof CustomEvent)) {
                 return;
@@ -578,7 +600,7 @@ function bindFormEvents(
                 return;
             }
 
-            if (result.action === 'save') {
+            if (result.action === 'save' || result.outcome === 'revised') {
                 unloadWarning.scheduleBaselineCapture();
             }
         };
@@ -625,8 +647,7 @@ function bindFormEvents(
                 return;
             }
 
-            // Ajax multipage navigation updates UI immediately, then persists page
-            // continuity in the background so refresh/recovery stays in sync.
+            // The server validates forward navigation before selecting the page.
             event.preventDefault();
 
             const currentTarget = event.currentTarget as HTMLAnchorElement | null;
@@ -637,7 +658,6 @@ function bindFormEvents(
                 return;
             }
 
-            applyPageState(form, nextPageId);
             dispatchFormieDomEvent(target, 'formie:page:navigate', {
                 pageId: nextPageId,
                 href,
@@ -645,6 +665,15 @@ function bindFormEvents(
 
             try {
                 const response = await requestSetPage(href, form, nextPageId);
+                if (response.pageId) applyPageState(form, String(response.pageId));
+                if (!response.success) {
+                    const { form: formErrors = [], ...fieldErrors } = response.errors ?? {};
+                    clearSubmitFeedback(form);
+                    renderFieldErrors(form, fieldErrors);
+                    renderFormErrors(form, formErrors);
+                    focusFirstValidationError(form);
+                    return;
+                }
 
                 dispatchFormieDomEvent(target, 'formie:page:navigate:after', {
                     pageId: nextPageId,
@@ -829,6 +858,8 @@ function bindFormEvents(
     unbinds.push(() => {
         form.removeEventListener('submit', submitHandler);
     });
+
+    return captureBaseline;
 }
 
 async function refreshTokensIfNeeded(target: Element, options: FormMountOptions, form: HTMLFormElement | null): Promise<void> {
@@ -840,7 +871,6 @@ async function refreshTokensIfNeeded(target: Element, options: FormMountOptions,
         return;
     }
 
-    ensureSupportedHeadlessTransport(normalizeTransport(options.transport), normalizeMode(options.mode));
 
     const formHandle = options.formHandle || (target as HTMLElement).dataset.formieHandle;
     const endpoint = resolveRefreshTokensEndpoint(options, target);
@@ -853,7 +883,7 @@ async function refreshTokensIfNeeded(target: Element, options: FormMountOptions,
 
     // Refresh-tokens-before-ready is the cache-safe path: forms can render from SSR/cache
     // and still receive fresh transport tokens before the user submits anything.
-    const refreshTokens = await requestRefreshTokens(endpoint, formHandle, renderId);
+    const refreshTokens = await requestRefreshTokens(endpoint, formHandle, renderId, options, form?.querySelector<HTMLInputElement>('input[name="requestToken"]')?.value);
 
     if (!refreshTokens || !form) {
         return;
@@ -869,14 +899,14 @@ export function createFormieClient(): FormieClient {
     const moduleRegistry = new ModuleRegistry();
     const pendingVisibilityMounts = new Map<Element, () => void>();
     const pendingUnmounts = new Map<Element, Promise<void>>();
-    const stageNames: Array<'prepare' | 'normalize' | 'validate' | 'screen' | 'authorize' | 'dispatch' | 'finalize'> = [
+    const stageNames: Array<'prepare' | 'normalize' | 'validate' | 'challenge' | 'payment' | 'send' | 'result'> = [
         'prepare',
         'normalize',
         'validate',
-        'screen',
-        'authorize',
-        'dispatch',
-        'finalize',
+        'challenge',
+        'payment',
+        'send',
+        'result',
     ];
 
     const unmount = async(target: Element): Promise<void> => {
@@ -913,10 +943,7 @@ export function createFormieClient(): FormieClient {
         state.validator?.destroy();
         state.validator = null;
 
-        for (const moduleInstance of state.modules) {
-            await moduleInstance.destroy();
-        }
-        state.modules = [];
+        await state.modules.destroy();
 
         state.bus.clear();
         instances.delete(target);
@@ -965,20 +992,37 @@ export function createFormieClient(): FormieClient {
             mode: normalizeMode(options.mode ?? mergedFromDom.mode),
             transport: normalizeTransport(options.transport ?? mergedFromDom.transport),
         };
-        const compatibilityOptions = resolveLegacyCompatibilityOptions(normalizedOptions.compatibility);
+        const renderPayload = await ensureHtmlRender(target, normalizedOptions);
+        const form = getFormFromTarget(target);
 
-        if (normalizedOptions.mode !== 'server-rendered' && !getFormFromTarget(target)) {
-            throw new Error(`Formie ${normalizedOptions.mode} mode is not implemented yet in the browser client.`);
+        // Fetched HTML carries the plugin setting on the form, not its mount wrapper.
+        if (options.compatibility === undefined && form?.hasAttribute('data-formie-compatibility')) {
+            normalizedOptions.compatibility = inferOptionsFromElement(form).compatibility;
         }
 
-        const renderPayload = await ensureHtmlRender(target, normalizedOptions);
-        const form = getFormFromTarget(target);
+        const compatibilityOptions = resolveLegacyCompatibilityOptions(normalizedOptions.compatibility);
+        if (form) setFormBrowserRequestOptions(form, normalizedOptions);
         normalizedOptions.staticCache =
             options.staticCache ??
             (form
                 ? inferStaticCacheOnLoadFromDataset(form.dataset)
                 : inferStaticCacheOnLoadFromDataset((target as HTMLElement).dataset));
-        const embeddedPayload = getEmbeddedPayload(target, form);
+        let embeddedPayload: FormEndpointPayload | null;
+        try {
+            embeddedPayload = getEmbeddedPayload(target, form);
+            if (renderPayload?.modules) assertBrowserModuleManifest(renderPayload.modules);
+            if (embeddedPayload?.modules) assertBrowserModuleManifest(embeddedPayload.modules);
+        } catch (error) {
+            // Unknown semantics must not fall back to an unguarded native send.
+            if (form) {
+                form.addEventListener('submit', (event) => { event.preventDefault(); event.stopImmediatePropagation(); }, true);
+                const alert = document.createElement('div');
+                alert.setAttribute('role', 'alert');
+                alert.textContent = 'This form requires a compatible Formie browser package. Update Formie and its browser packages together.';
+                form.prepend(alert);
+            }
+            throw error;
+        }
         const payload = renderPayload || embeddedPayload
             ? {
                 ...(renderPayload || {}),
@@ -987,14 +1031,13 @@ export function createFormieClient(): FormieClient {
             : null;
         const themeClassMap = payload?.theme as ThemeClassMap | undefined;
         const stateStore: Record<string, unknown> = {};
-        const moduleManifest = ((payload?.modules || []) as FormModuleManifest[]).filter((item) => {
-            return !!item?.id && !!item?.type;
-        });
+        const moduleManifest = payload?.modules ?? { contractVersion: 2, surface: 'server-rendered' as const, entries: [] };
+        assertBrowserModuleManifest(moduleManifest);
         debug.log('Resolved mount payload.', {
             target: getTargetDebugLabel(target),
             hasRenderPayload: !!renderPayload,
             hasEmbeddedPayload: !!embeddedPayload,
-            moduleCount: moduleManifest.length,
+            moduleCount: moduleManifest.entries.length,
         });
         const resolvedThemeClassMap = registerThemeClassMap(target, themeClassMap, form);
 
@@ -1028,16 +1071,8 @@ export function createFormieClient(): FormieClient {
         if (form) {
             ensureFormStartedAt(form);
 
-            if (normalizedOptions.themeConfig && typeof normalizedOptions.themeConfig === 'object') {
-                form.setAttribute('data-formie-theme-config', JSON.stringify(normalizedOptions.themeConfig));
-            }
-
-            if (normalizedOptions.theme && normalizedOptions.theme !== 'formie') {
-                form.setAttribute('data-formie-frontend-theme', normalizedOptions.theme);
-            }
-
             if (renderPayload || normalizedOptions.endpoint || (target as HTMLElement).dataset.formieEndpoint) {
-                normalizeHeadlessManagedUrls(target, form, normalizedOptions);
+                normalizeServerRenderedUrls(target, form, normalizedOptions);
             }
 
             if (normalizedOptions.mode === 'server-rendered' && hasServerRenderedValidationErrors(form)) {
@@ -1054,6 +1089,13 @@ export function createFormieClient(): FormieClient {
             });
         }
 
+        // Craft's async CSRF element initializes the session. Let it finish before
+        // captcha modules request session-bound tokens, otherwise the concurrent
+        // responses can race and replace each other's session cookie.
+        if (form?.querySelector('craft-csrf-input')) {
+            await waitForElementRemoval('craft-csrf-input', form);
+        }
+
         // Modules run against the mounted DOM surface, not against server payload
         // objects, so the loader resolves real targets before calling setup().
         const modules = await loadModulesFromManifest(moduleManifest, {
@@ -1061,7 +1103,7 @@ export function createFormieClient(): FormieClient {
             matchContext: {
                 root: target,
                 form,
-                mode: normalizedOptions.mode,
+                surface: moduleManifest.surface,
             },
             setupContext: {
                 formId: id,
@@ -1069,6 +1111,7 @@ export function createFormieClient(): FormieClient {
                 form,
                 target,
                 scope: 'form',
+                surface: moduleManifest.surface,
                 state: stateStore,
                 on: (eventName, callback) => {
                     return bus.on(eventName, callback);
@@ -1088,7 +1131,7 @@ export function createFormieClient(): FormieClient {
         });
         debug.log('Module setup complete.', {
             target: getTargetDebugLabel(target),
-            moduleInstances: modules.length,
+            moduleInstances: modules.instances.length,
         });
 
         const instance: FormieFormInstance = {
@@ -1184,7 +1227,7 @@ export function createFormieClient(): FormieClient {
         }
 
         if (form) {
-            bindFormEvents(target, form, normalizedOptions, bus, validator, unbinds);
+            const captureBaseline = bindFormEvents(target, form, normalizedOptions, bus, validator, unbinds);
 
             if (validator) {
                 unbinds.push(bindSubmitReadiness(form, validator, target));
@@ -1195,23 +1238,28 @@ export function createFormieClient(): FormieClient {
 
             // Recapture after captcha/token hydration and field-module init settle so
             // programmatic post-mount value changes do not leave a false dirty state.
-            form.dispatchEvent(new CustomEvent('formie:state:reset'));
-            window.setTimeout(() => {
-                form.dispatchEvent(new CustomEvent('formie:state:reset'));
-            }, 350);
+            captureBaseline();
+            const baselineTimer = window.setTimeout(captureBaseline, 350);
+            unbinds.push(() => window.clearTimeout(baselineTimer));
         }
 
         stageNames.forEach((stageName) => {
-            // Stage fan-out keeps submit pipeline ownership centralized while still
-            // letting modules participate before and after each stage.
             const beforeDomUnbind = bus.on(`formie:stage:${stageName}:before`, async(payload) => {
                 dispatchFormieDomEvent(target, `formie:stage:${stageName}:before`, payload);
             });
 
             const beforeUnbind = bus.on(`formie:stage:${stageName}:before`, async(payload) => {
-                for (const moduleInstance of modules) {
-                    if (moduleInstance.onBeforeStage) {
-                        await moduleInstance.onBeforeStage(payload as Parameters<NonNullable<FormieModuleInstance['onBeforeStage']>>[0]);
+                const hookStage = { core: 'prepare', field: 'prepare', address: 'prepare', captcha: 'challenge', payment: 'payment' } as const;
+                const stagePayload = payload as Parameters<NonNullable<BrowserModuleInstance['beforeSubmit']>>[0] & { stage: string };
+
+                if (stageName === 'prepare') {
+                    try { modules.assertReady(); }
+                    catch { stagePayload.abort('A required form feature could not start. Reload the page or contact the site administrator.'); return; }
+                }
+                for (const moduleInstance of modules.instances) {
+                    if (moduleInstance.beforeSubmit && hookStage[moduleInstance.kind ?? 'core'] === stageName) {
+                        const { form, action, formData, abort, isAborted, abortReason } = stagePayload;
+                        await moduleInstance.beforeSubmit({ form, action, formData, abort, isAborted, abortReason });
                     }
                 }
             });
@@ -1220,19 +1268,7 @@ export function createFormieClient(): FormieClient {
                 dispatchFormieDomEvent(target, `formie:stage:${stageName}:after`, payload);
             });
 
-            const afterUnbind = bus.on(`formie:stage:${stageName}:after`, async(payload) => {
-                const stagePayload = payload as {
-                    result?: FormSubmitResult;
-                } & Parameters<NonNullable<FormieModuleInstance['onAfterStage']>>[0];
-
-                for (const moduleInstance of modules) {
-                    if (moduleInstance.onAfterStage) {
-                        await moduleInstance.onAfterStage(stagePayload, stagePayload.result);
-                    }
-                }
-            });
-
-            unbinds.push(beforeDomUnbind, beforeUnbind, afterDomUnbind, afterUnbind);
+            unbinds.push(beforeDomUnbind, beforeUnbind, afterDomUnbind);
         });
 
         const submitBeforeUnbind = bus.on('formie:submit:before', async(payload) => {
@@ -1241,6 +1277,16 @@ export function createFormieClient(): FormieClient {
 
         const submitAfterUnbind = bus.on('formie:submit:after', async(payload) => {
             dispatchFormieDomEvent(target, 'formie:submit:after', payload);
+
+            if (!form) return;
+            const result = payload as FormSubmitResult;
+            if (result.code === 'PREFLIGHT_COMPLETE') return;
+            const context = {
+                form,
+                action: result.action ?? 'submit' as const,
+                formData: new FormData(form),
+            };
+            for (const moduleInstance of modules.instances) await moduleInstance.afterSubmit?.(context, result);
         });
 
         const submitFinalBeforeUnbind = bus.on('formie:submit:final:before', async(payload) => {
@@ -1435,7 +1481,7 @@ export function createFormieClient(): FormieClient {
             return;
         }
 
-        const refreshTokens = await requestRefreshTokens(endpoint, formHandle, renderId);
+        const refreshTokens = await requestRefreshTokens(endpoint, formHandle, renderId, options, form?.querySelector<HTMLInputElement>('input[name="requestToken"]')?.value);
 
         if (!refreshTokens) {
             return;
@@ -1446,7 +1492,7 @@ export function createFormieClient(): FormieClient {
     };
 
     const registerModule = (
-        moduleDefinition: FormieModuleDefinition,
+        moduleDefinition: BrowserModuleDefinition,
         options?: Parameters<ModuleRegistry['register']>[1],
     ): boolean => {
         return moduleRegistry.register(moduleDefinition, options);
@@ -1456,7 +1502,7 @@ export function createFormieClient(): FormieClient {
         moduleRegistry.unregister(moduleId);
     };
 
-    const getRegisteredModules = (): FormieModuleDefinition[] => {
+    const getRegisteredModules = (): BrowserModuleDefinition[] => {
         return moduleRegistry.getAll();
     };