From 49a4f242a831545bc40b3090bd9843346eaf555c Mon Sep 17 00:00:00 2001
From: Gabriel <gabriel_paes@live.com>
Date: Mon, 9 Mar 2026 07:15:42 -0300
Subject: [PATCH 1/5] fix: apply biome formatting across all packages

---
 apps/docs/package.json                    |   2 +-
 packages/core/src/use-action-form-core.ts | 256 +++++++++++-----------
 2 files changed, 133 insertions(+), 125 deletions(-)

diff --git a/apps/docs/package.json b/apps/docs/package.json
index 250c25d..e2346a0 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -28,4 +28,4 @@
     "tailwindcss": "^3.4.17",
     "typescript": "^5.7.3"
   }
-}
\ No newline at end of file
+}
diff --git a/packages/core/src/use-action-form-core.ts b/packages/core/src/use-action-form-core.ts
index b95c5c5..573f2c4 100644
--- a/packages/core/src/use-action-form-core.ts
+++ b/packages/core/src/use-action-form-core.ts
@@ -1,8 +1,8 @@
-"use client";
+'use client'
 
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { type DefaultValues, type FieldPath, type FieldValues, useForm } from "react-hook-form";
-import type { ZodError, ZodSchema } from "zod";
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { type DefaultValues, type FieldPath, type FieldValues, useForm } from 'react-hook-form'
+import type { ZodError, ZodSchema } from 'zod'
 
 import type {
   ActionFormState,
@@ -14,30 +14,37 @@ import type {
   SubmitFunction,
   UseActionFormCoreOptions,
   UseActionFormCoreReturn,
-} from "./core-types";
-import { defaultErrorMapper } from "./core-types";
-import { clearPersistedValues, debounce, loadPersistedValues, savePersistedValues } from "./persist";
-import { hasUseOptimistic, useOptimistic as useOptimisticReact19, useTransition } from "./react-shim";
+} from './core-types'
+import { defaultErrorMapper } from './core-types'
+import { clearPersistedValues, debounce, loadPersistedValues, savePersistedValues } from './persist'
+import {
+  hasUseOptimistic,
+  useOptimistic as useOptimisticReact19,
+  useTransition,
+} from './react-shim'
 
 // ---------------------------------------------------------------------------
 // Internal: client-side Zod validation helper
 // ---------------------------------------------------------------------------
 
-function validateWithSchema(schema: ZodSchema, values: Record<string, unknown>): FieldErrorRecord | null {
-  const result = schema.safeParse(values);
-  if (result.success) return null;
+function validateWithSchema(
+  schema: ZodSchema,
+  values: Record<string, unknown>,
+): FieldErrorRecord | null {
+  const result = schema.safeParse(values)
+  if (result.success) return null
 
-  const zodError = result.error as ZodError;
-  const flat = zodError.flatten();
-  const errors: FieldErrorRecord = {};
+  const zodError = result.error as ZodError
+  const flat = zodError.flatten()
+  const errors: FieldErrorRecord = {}
 
   for (const [field, messages] of Object.entries(flat.fieldErrors)) {
     if (messages && messages.length > 0) {
-      errors[field] = messages as string[];
+      errors[field] = messages as string[]
     }
   }
 
-  return Object.keys(errors).length > 0 ? errors : null;
+  return Object.keys(errors).length > 0 ? errors : null
 }
 
 // ---------------------------------------------------------------------------
@@ -45,8 +52,8 @@ function validateWithSchema(schema: ZodSchema, values: Record<string, unknown>):
 // ---------------------------------------------------------------------------
 
 function useOptimisticFallback<T>(initial: T): [T, (value: T) => void] {
-  const [state, setState] = useState<T>(initial);
-  return [state, setState];
+  const [state, setState] = useState<T>(initial)
+  return [state, setState]
 }
 
 // ---------------------------------------------------------------------------
@@ -79,50 +86,50 @@ export function useActionFormCore<
 ): UseActionFormCoreReturn<TFieldValues, TResult, TOptimistic> {
   const {
     defaultValues: optionDefaults,
-    mode = "onSubmit",
+    mode = 'onSubmit',
     persistKey,
     errorMapper = defaultErrorMapper as ErrorMapper<TResult>,
     onSuccess,
     onError,
     persistDebounce = 300,
     schema: optionsSchema,
-    validationMode = "onSubmit",
+    validationMode = 'onSubmit',
     optimisticKey,
     optimisticData,
     optimisticInitial,
     plugins = [],
-  } = options;
+  } = options
 
   // ----- Resolve Zod schema -----------------------------------------------
 
-  const resolvedSchema = useMemo(() => optionsSchema ?? undefined, [optionsSchema]);
+  const resolvedSchema = useMemo(() => optionsSchema ?? undefined, [optionsSchema])
 
   // ----- Resolve initial values (persisted > options) ----------------------
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: intentionally run once on mount
   const resolvedDefaults = useMemo<DefaultValues<TFieldValues> | undefined>(() => {
     if (persistKey) {
-      const persisted = loadPersistedValues<TFieldValues>(persistKey);
+      const persisted = loadPersistedValues<TFieldValues>(persistKey)
       if (persisted) {
         return {
           ...(optionDefaults as Record<string, unknown> | undefined),
           ...persisted,
-        } as DefaultValues<TFieldValues>;
+        } as DefaultValues<TFieldValues>
       }
     }
-    return optionDefaults;
-  }, []);
+    return optionDefaults
+  }, [])
 
   // ----- React Hook Form ---------------------------------------------------
 
   const form = useForm<TFieldValues>({
     defaultValues: resolvedDefaults,
     mode,
-  });
+  })
 
   // ----- useTransition (React 18 & 19) ------------------------------------
 
-  const [isTransitioning, startTransition] = useTransition();
+  const [isTransitioning, startTransition] = useTransition()
 
   // ----- Action state ------------------------------------------------------
 
@@ -132,110 +139,111 @@ export function useActionFormCore<
     submitErrors: null,
     actionResult: null,
     isPending: false,
-  });
+  })
 
   // ----- Submission history (for DevTools) ----------------------------------
 
-  const submissionHistoryRef = useRef<SubmissionRecord<TResult>[]>([]);
+  const submissionHistoryRef = useRef<SubmissionRecord<TResult>[]>([])
 
   // ----- Optimistic UI (React 19 only) -------------------------------------
 
-  const hasOptimistic = optimisticKey != null && optimisticData != null;
+  const hasOptimistic = optimisticKey != null && optimisticData != null
 
-  const useOptimisticHook = hasUseOptimistic && useOptimisticReact19 ? useOptimisticReact19 : useOptimisticFallback;
+  const useOptimisticHook =
+    hasUseOptimistic && useOptimisticReact19 ? useOptimisticReact19 : useOptimisticFallback
 
-  const [optimisticState, setOptimistic] = useOptimisticHook(optimisticInitial as TOptimistic);
+  const [optimisticState, setOptimistic] = useOptimisticHook(optimisticInitial as TOptimistic)
 
-  const confirmedOptimisticRef = useRef<TOptimistic>(optimisticInitial as TOptimistic);
+  const confirmedOptimisticRef = useRef<TOptimistic>(optimisticInitial as TOptimistic)
 
   const rollbackOptimistic = useCallback(() => {
-    setOptimistic(confirmedOptimisticRef.current);
-  }, [setOptimistic]);
+    setOptimistic(confirmedOptimisticRef.current)
+  }, [setOptimistic])
 
   // ----- Persistence -------------------------------------------------------
 
   const debouncedSave = useMemo(() => {
-    if (!persistKey) return null;
+    if (!persistKey) return null
     return debounce((values: TFieldValues) => {
-      savePersistedValues(persistKey, values);
-    }, persistDebounce);
-  }, [persistKey, persistDebounce]);
+      savePersistedValues(persistKey, values)
+    }, persistDebounce)
+  }, [persistKey, persistDebounce])
 
   useEffect(() => {
-    if (!persistKey || !debouncedSave) return;
+    if (!persistKey || !debouncedSave) return
 
     const subscription = form.watch((values) => {
-      debouncedSave(values as TFieldValues);
-    });
+      debouncedSave(values as TFieldValues)
+    })
 
-    return () => subscription.unsubscribe();
-  }, [persistKey, debouncedSave, form]);
+    return () => subscription.unsubscribe()
+  }, [persistKey, debouncedSave, form])
 
   // ----- Client-side Zod validation (onChange / onBlur) ---------------------
 
   useEffect(() => {
-    if (!resolvedSchema || validationMode === "onSubmit") return;
+    if (!resolvedSchema || validationMode === 'onSubmit') return
 
     const subscription = form.watch((values, { name, type }) => {
-      if (!name) return;
+      if (!name) return
 
-      if (validationMode === "onChange" || type === "blur") {
-        const fieldResult = resolvedSchema.safeParse(values);
+      if (validationMode === 'onChange' || type === 'blur') {
+        const fieldResult = resolvedSchema.safeParse(values)
         if (fieldResult.success) {
-          form.clearErrors(name as FieldPath<TFieldValues>);
+          form.clearErrors(name as FieldPath<TFieldValues>)
         } else {
-          const zodError = fieldResult.error as ZodError;
-          const flat = zodError.flatten();
-          const fieldErrors = flat.fieldErrors[name];
+          const zodError = fieldResult.error as ZodError
+          const flat = zodError.flatten()
+          const fieldErrors = flat.fieldErrors[name]
 
           if (fieldErrors && fieldErrors.length > 0) {
             form.setError(name as FieldPath<TFieldValues>, {
-              type: "validation",
+              type: 'validation',
               message: fieldErrors[0],
-            });
+            })
           } else {
-            form.clearErrors(name as FieldPath<TFieldValues>);
+            form.clearErrors(name as FieldPath<TFieldValues>)
           }
         }
       }
-    });
+    })
 
-    return () => subscription.unsubscribe();
-  }, [resolvedSchema, validationMode, form]);
+    return () => subscription.unsubscribe()
+  }, [resolvedSchema, validationMode, form])
 
   // ----- Plugin lifecycle: onMount -----------------------------------------
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: plugins identity changes every render; run once on mount
   useEffect(() => {
-    const cleanups = plugins.map((p) => p.onMount?.()).filter(Boolean) as (() => void)[];
+    const cleanups = plugins.map((p) => p.onMount?.()).filter(Boolean) as (() => void)[]
 
     return () => {
       for (const cleanup of cleanups) {
-        cleanup();
+        cleanup()
       }
-    };
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps -- run once on mount
+    }
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps -- run once on mount
 
   // ----- Manual persist / clear --------------------------------------------
 
   const persist = useCallback(() => {
-    if (!persistKey) return;
-    savePersistedValues(persistKey, form.getValues());
-  }, [persistKey, form]);
+    if (!persistKey) return
+    savePersistedValues(persistKey, form.getValues())
+  }, [persistKey, form])
 
   const clearPersisted = useCallback(() => {
-    if (!persistKey) return;
-    clearPersistedValues(persistKey);
-  }, [persistKey]);
+    if (!persistKey) return
+    clearPersistedValues(persistKey)
+  }, [persistKey])
 
   // ----- Set a server error on a field -------------------------------------
 
   const setSubmitError = useCallback(
     (field: keyof TFieldValues & string, message: string) => {
-      form.setError(field as never, { type: "server", message });
+      form.setError(field as never, { type: 'server', message })
     },
     [form],
-  );
+  )
 
   // ----- Map server errors to RHF ------------------------------------------
 
@@ -244,40 +252,40 @@ export function useActionFormCore<
       for (const [field, messages] of Object.entries(errors)) {
         if (messages && messages.length > 0) {
           form.setError(field as never, {
-            type: "server",
+            type: 'server',
             message: messages[0],
-          });
+          })
         }
       }
     },
     [form],
-  );
+  )
 
   // ----- Core submit logic -------------------------------------------------
 
   const executeSubmit = useCallback(
     async (data: TFieldValues) => {
       // Client-side schema validation (for onSubmit mode)
-      if (resolvedSchema && validationMode === "onSubmit") {
-        const clientErrors = validateWithSchema(resolvedSchema, data as Record<string, unknown>);
+      if (resolvedSchema && validationMode === 'onSubmit') {
+        const clientErrors = validateWithSchema(resolvedSchema, data as Record<string, unknown>)
         if (clientErrors) {
-          applyServerErrors(clientErrors);
+          applyServerErrors(clientErrors)
           setActionState({
             isSubmitting: false,
             isSubmitSuccessful: false,
             submitErrors: clientErrors,
             actionResult: null,
             isPending: false,
-          });
-          return;
+          })
+          return
         }
       }
 
       // Plugin: onBeforeSubmit
       for (const plugin of plugins) {
         if (plugin.onBeforeSubmit) {
-          const shouldContinue = await plugin.onBeforeSubmit(data);
-          if (shouldContinue === false) return;
+          const shouldContinue = await plugin.onBeforeSubmit(data)
+          if (shouldContinue === false) return
         }
       }
 
@@ -286,20 +294,20 @@ export function useActionFormCore<
         isSubmitting: true,
         isPending: true,
         submitErrors: null,
-      }));
+      }))
 
       // Apply optimistic update before the action runs
       if (hasOptimistic && optimisticData) {
-        const optimisticResult = optimisticData(confirmedOptimisticRef.current, data);
-        setOptimistic(optimisticResult);
+        const optimisticResult = optimisticData(confirmedOptimisticRef.current, data)
+        setOptimistic(optimisticResult)
       }
 
-      const startTime = Date.now();
+      const startTime = Date.now()
 
       try {
-        const result = await submit(data);
+        const result = await submit(data)
 
-        const fieldErrors = errorMapper(result);
+        const fieldErrors = errorMapper(result)
 
         // Record submission for DevTools
         const record: SubmissionRecord<TResult> = {
@@ -310,14 +318,14 @@ export function useActionFormCore<
           error: null,
           duration: Date.now() - startTime,
           success: !fieldErrors || Object.keys(fieldErrors).length === 0,
-        };
-        submissionHistoryRef.current = [...submissionHistoryRef.current.slice(-49), record];
+        }
+        submissionHistoryRef.current = [...submissionHistoryRef.current.slice(-49), record]
 
         if (fieldErrors && Object.keys(fieldErrors).length > 0) {
-          applyServerErrors(fieldErrors);
+          applyServerErrors(fieldErrors)
 
           if (hasOptimistic) {
-            rollbackOptimistic();
+            rollbackOptimistic()
           }
 
           setActionState({
@@ -326,22 +334,22 @@ export function useActionFormCore<
             submitErrors: fieldErrors,
             actionResult: result,
             isPending: false,
-          });
+          })
 
           // Plugin: onError
           for (const plugin of plugins) {
-            plugin.onError?.(result, data);
+            plugin.onError?.(result, data)
           }
 
-          onError?.(result);
+          onError?.(result)
         } else {
           // Success – update confirmed optimistic state
           if (hasOptimistic && optimisticData) {
-            confirmedOptimisticRef.current = optimisticData(confirmedOptimisticRef.current, data);
+            confirmedOptimisticRef.current = optimisticData(confirmedOptimisticRef.current, data)
           }
 
           // Clear persisted data
-          if (persistKey) clearPersistedValues(persistKey);
+          if (persistKey) clearPersistedValues(persistKey)
 
           setActionState({
             isSubmitting: false,
@@ -349,14 +357,14 @@ export function useActionFormCore<
             submitErrors: null,
             actionResult: result,
             isPending: false,
-          });
+          })
 
           // Plugin: onSuccess
           for (const plugin of plugins) {
-            plugin.onSuccess?.(result, data);
+            plugin.onSuccess?.(result, data)
           }
 
-          onSuccess?.(result);
+          onSuccess?.(result)
         }
       } catch (error) {
         // Record failed submission for DevTools
@@ -368,11 +376,11 @@ export function useActionFormCore<
           error: error instanceof Error ? error : new Error(String(error)),
           duration: Date.now() - startTime,
           success: false,
-        };
-        submissionHistoryRef.current = [...submissionHistoryRef.current.slice(-49), record];
+        }
+        submissionHistoryRef.current = [...submissionHistoryRef.current.slice(-49), record]
 
         if (hasOptimistic) {
-          rollbackOptimistic();
+          rollbackOptimistic()
         }
 
         setActionState((prev) => ({
@@ -380,16 +388,16 @@ export function useActionFormCore<
           isSubmitting: false,
           isSubmitSuccessful: false,
           isPending: false,
-        }));
+        }))
 
-        const wrappedError = error instanceof Error ? error : new Error(String(error));
+        const wrappedError = error instanceof Error ? error : new Error(String(error))
 
         // Plugin: onError
         for (const plugin of plugins) {
-          plugin.onError?.(wrappedError as TResult & Error, data);
+          plugin.onError?.(wrappedError as TResult & Error, data)
         }
 
-        onError?.(wrappedError);
+        onError?.(wrappedError)
       }
     },
     [
@@ -407,23 +415,23 @@ export function useActionFormCore<
       rollbackOptimistic,
       plugins,
     ],
-  );
+  )
 
   // ----- handleSubmit wrapper ----------------------------------------------
 
   const handleSubmit = useCallback(
     (onValid?: (data: TFieldValues) => void | Promise<void>) => {
       return form.handleSubmit(async (data) => {
-        if (onValid) await onValid(data);
+        if (onValid) await onValid(data)
 
         // @ts-ignore – React 19 supports async transitions; React 18 ignores the promise
         startTransition(async () => {
-          await executeSubmit(data);
-        });
-      });
+          await executeSubmit(data)
+        })
+      })
     },
     [form, executeSubmit, startTransition],
-  );
+  )
 
   // ----- Compose return value ----------------------------------------------
 
@@ -444,30 +452,30 @@ export function useActionFormCore<
       isPending: isTransitioning || actionState.isPending,
     }),
     [form.formState, actionState, isTransitioning],
-  );
+  )
 
   // ----- Compose optimistic return -----------------------------------------
 
   const optimisticReturn = useMemo(() => {
-    if (!hasOptimistic) return undefined;
+    if (!hasOptimistic) return undefined
     return {
       data: optimisticState,
       isPending: isTransitioning || actionState.isPending,
       rollback: rollbackOptimistic,
-    } as OptimisticState<TOptimistic>;
-  }, [hasOptimistic, optimisticState, isTransitioning, actionState.isPending, rollbackOptimistic]);
+    } as OptimisticState<TOptimistic>
+  }, [hasOptimistic, optimisticState, isTransitioning, actionState.isPending, rollbackOptimistic])
 
   // ----- Compose control with DevTools metadata ----------------------------
 
   const enhancedControl = useMemo(() => {
     const ctrl = form.control as typeof form.control & {
-      _submissionHistory: SubmissionRecord<TResult>[];
-      _actionFormState: ActionFormState<TResult>;
-    };
-    ctrl._submissionHistory = submissionHistoryRef.current;
-    ctrl._actionFormState = actionState;
-    return ctrl;
-  }, [form.control, actionState]);
+      _submissionHistory: SubmissionRecord<TResult>[]
+      _actionFormState: ActionFormState<TResult>
+    }
+    ctrl._submissionHistory = submissionHistoryRef.current
+    ctrl._actionFormState = actionState
+    return ctrl
+  }, [form.control, actionState])
 
   return {
     ...form,
@@ -478,5 +486,5 @@ export function useActionFormCore<
     persist,
     clearPersistedData: clearPersisted,
     optimistic: optimisticReturn,
-  } as UseActionFormCoreReturn<TFieldValues, TResult, TOptimistic>;
+  } as UseActionFormCoreReturn<TFieldValues, TResult, TOptimistic>
 }

From dde300aea6cffbe76f306be84b0159e16ed25ea0 Mon Sep 17 00:00:00 2001
From: Gabriel <gabriel_paes@live.com>
Date: Mon, 9 Mar 2026 08:16:31 -0300
Subject: [PATCH 2/5] feat-docs-core-update

---
 MESSAGING.md                                  |  102 +
 README.md                                     |  749 ++++++--
 apps/docs/ADVANCED_PATTERNS.md                | 1640 +++++++++++++++++
 apps/docs/app/api-reference/page.tsx          |   59 +-
 apps/docs/app/devtools/page.tsx               |    2 +-
 .../examples/_components/example-shell.tsx    |   50 +
 apps/docs/app/examples/catalog.ts             |  125 ++
 .../page.tsx                                  |   40 +
 .../page.tsx                                  |   41 +
 apps/docs/app/examples/login/login-form.tsx   |    6 +-
 apps/docs/app/examples/login/page.tsx         |    6 +-
 .../page.tsx                                  |   54 +
 .../next-optimistic-list-rollback/page.tsx    |   25 +
 .../next-optimistic-profile-update/page.tsx   |   46 +
 .../examples/next-quickstart-login/page.tsx   |   39 +
 .../examples/next-schema-once-signup/page.tsx |   32 +
 .../next-wizard-onboarding-persist/page.tsx   |   37 +
 .../optimistic/optimistic-todo-form.tsx       |   73 +-
 apps/docs/app/examples/optimistic/page.tsx    |    4 +-
 apps/docs/app/examples/page.tsx               |  113 ++
 .../standalone-quickstart-login/page.tsx      |   56 +
 .../standalone-rest-error-mapper/page.tsx     |   40 +
 apps/docs/app/examples/validation/page.tsx    |    2 +-
 .../examples/validation/validation-form.tsx   |   76 +-
 apps/docs/app/examples/wizard/page.tsx        |    2 +-
 apps/docs/app/examples/wizard/wizard-form.tsx |    6 +-
 apps/docs/app/faq/page.tsx                    |  146 ++
 apps/docs/app/layout.tsx                      |   74 +-
 apps/docs/app/page.tsx                        |  790 +++++---
 .../app/recipes/custom-error-mapper/page.tsx  |  307 +++
 .../app/recipes/edit-server-data/page.tsx     |  273 +++
 apps/docs/app/recipes/field-array/page.tsx    |  306 +++
 apps/docs/app/recipes/file-upload/page.tsx    |  308 ++++
 apps/docs/app/recipes/login-form/page.tsx     |  240 +++
 apps/docs/app/recipes/modal-form/page.tsx     |  363 ++++
 .../app/recipes/multi-step-wizard/page.tsx    |  351 ++++
 apps/docs/app/recipes/nested-fields/page.tsx  |  339 ++++
 apps/docs/app/recipes/optimistic-ui/page.tsx  |  281 +++
 apps/docs/app/recipes/page.tsx                |  253 +++
 .../app/recipes/reset-after-success/page.tsx  |  301 +++
 .../app/recipes/signup-server-errors/page.tsx |  279 +++
 .../app/recipes/standalone-fetch/page.tsx     |  336 ++++
 apps/docs/app/standalone/page.tsx             |    2 +-
 apps/docs/app/submit-lifecycle/page.tsx       |  229 +++
 apps/docs/app/troubleshooting/page.tsx        |  125 ++
 apps/docs/app/why/page.tsx                    |  415 +++++
 packages/core/README.md                       |   12 +-
 packages/core/package.json                    |    2 +-
 .../src/__tests__/client-validation.test.ts   |  276 +--
 .../core/src/__tests__/optimistic.test.ts     |  189 +-
 .../core/src/__tests__/persistence.test.ts    |  144 +-
 .../__tests__/use-action-form-core.test.ts    |  362 ++--
 .../src/__tests__/use-action-form.test.ts     |  373 ++--
 packages/core/src/core-types.ts               |  179 +-
 packages/core/src/types.ts                    |  168 +-
 packages/core/src/use-action-form-core.ts     |  290 +--
 packages/core/src/use-action-form.ts          |  322 ++--
 packages/devtools/package.json                |    2 +-
 packages/devtools/src/FormDevTool.tsx         |  333 ++--
 packages/next/README.md                       |   57 +-
 packages/next/package.json                    |    2 +-
 packages/standalone/README.md                 |   18 +-
 packages/standalone/package.json              |    2 +-
 .../src/__tests__/use-action-form.test.ts     |  206 +--
 64 files changed, 10082 insertions(+), 1998 deletions(-)
 create mode 100644 MESSAGING.md
 create mode 100644 apps/docs/ADVANCED_PATTERNS.md
 create mode 100644 apps/docs/app/examples/_components/example-shell.tsx
 create mode 100644 apps/docs/app/examples/catalog.ts
 create mode 100644 apps/docs/app/examples/cross-adapter-parity-next-vs-standalone/page.tsx
 create mode 100644 apps/docs/app/examples/devtools-debug-submission-history/page.tsx
 create mode 100644 apps/docs/app/examples/migration-rhf-manual-to-hookform-action/page.tsx
 create mode 100644 apps/docs/app/examples/next-optimistic-list-rollback/page.tsx
 create mode 100644 apps/docs/app/examples/next-optimistic-profile-update/page.tsx
 create mode 100644 apps/docs/app/examples/next-quickstart-login/page.tsx
 create mode 100644 apps/docs/app/examples/next-schema-once-signup/page.tsx
 create mode 100644 apps/docs/app/examples/next-wizard-onboarding-persist/page.tsx
 create mode 100644 apps/docs/app/examples/page.tsx
 create mode 100644 apps/docs/app/examples/standalone-quickstart-login/page.tsx
 create mode 100644 apps/docs/app/examples/standalone-rest-error-mapper/page.tsx
 create mode 100644 apps/docs/app/faq/page.tsx
 create mode 100644 apps/docs/app/recipes/custom-error-mapper/page.tsx
 create mode 100644 apps/docs/app/recipes/edit-server-data/page.tsx
 create mode 100644 apps/docs/app/recipes/field-array/page.tsx
 create mode 100644 apps/docs/app/recipes/file-upload/page.tsx
 create mode 100644 apps/docs/app/recipes/login-form/page.tsx
 create mode 100644 apps/docs/app/recipes/modal-form/page.tsx
 create mode 100644 apps/docs/app/recipes/multi-step-wizard/page.tsx
 create mode 100644 apps/docs/app/recipes/nested-fields/page.tsx
 create mode 100644 apps/docs/app/recipes/optimistic-ui/page.tsx
 create mode 100644 apps/docs/app/recipes/page.tsx
 create mode 100644 apps/docs/app/recipes/reset-after-success/page.tsx
 create mode 100644 apps/docs/app/recipes/signup-server-errors/page.tsx
 create mode 100644 apps/docs/app/recipes/standalone-fetch/page.tsx
 create mode 100644 apps/docs/app/submit-lifecycle/page.tsx
 create mode 100644 apps/docs/app/troubleshooting/page.tsx
 create mode 100644 apps/docs/app/why/page.tsx

diff --git a/MESSAGING.md b/MESSAGING.md
new file mode 100644
index 0000000..14d49b4
--- /dev/null
+++ b/MESSAGING.md
@@ -0,0 +1,102 @@
+# hookform-action Messaging Pack
+
+## Core Positioning
+- The missing layer between React Hook Form and your server.
+- Typed submit flows with Zod mapping, optimistic UI, persistence, and DevTools.
+- Keep RHF ergonomics. Remove repeated integration wiring.
+
+## 1) One-Liners (15)
+1. Typed submit flows for React Hook Form.
+2. The missing layer between RHF and your server.
+3. Write the schema. Write the action. Skip the wiring.
+4. React Hook Form meets typed server submits.
+5. Keep RHF. Add reliable server submit flows.
+6. One hook for validation, pending state, and submit errors.
+7. Zod errors mapped to RHF fields automatically.
+8. Optimistic UI with rollback, built in.
+9. Persistence for multi-step forms, without storage glue code.
+10. Server actions without repetitive form plumbing.
+11. End-to-end type safety from input to action result.
+12. Predictable RHF submit pipelines for production apps.
+13. Same API for Next.js and standalone React apps.
+14. Less per-form code between data entry and mutation.
+15. Form-server integration you configure, not rewrite.
+
+## 2) Short Descriptions (10)
+1. hookform-action bridges React Hook Form and server submits with typed data flow and automatic field error mapping.
+2. It removes repetitive submit plumbing: FormData parsing, transition wiring, and server error propagation.
+3. Define your Zod schema once and keep types consistent across validation, submission, and response handling.
+4. Enable optimistic updates with rollback through options, not custom state machines.
+5. Persist multi-step values with debounced sessionStorage restore behavior.
+6. Keep the RHF API you already use while adding server-aware pending and result state.
+7. Use the same mental model in Next.js Server Actions and standalone React apps.
+8. Add DevTools to inspect form state, submit history, and debug actions during development.
+9. Built for teams that need predictable server-backed forms without replacing RHF.
+10. A practical typed layer for RHF submit flows with Zod and server feedback.
+
+## 3) Medium Descriptions (5)
+1. hookform-action is the integration layer between React Hook Form and your server. It standardizes typed submission, Zod validation mapping, pending state, and field-level server errors in one pipeline. You keep RHF ergonomics and remove repeated boilerplate.
+2. RHF, Zod, and Server Actions are strong primitives, but the space between them is where most form bugs appear. hookform-action closes that gap with typed submit flow control, automatic error mapping, optimistic updates, and optional persistence.
+3. Use `withZod` as a single source of truth for validation and types. hookform-action carries those types through the submit lifecycle and keeps form state behavior consistent across client and server boundaries.
+4. In Next.js, it plugs into Server Actions directly. In standalone React apps, the same API works with a `submit` function, which keeps form architecture consistent across frameworks.
+5. The library is designed for production submit behavior: predictable pending state, rollback-safe optimistic UI, debounced persistence, and DevTools visibility. It reduces per-form complexity while keeping behavior explicit.
+
+## 4) GitHub Repo Description Options (5)
+1. Typed submit flows for React Hook Form: Zod mapping, optimistic UI, persistence, and DevTools.
+2. The missing layer between RHF and server submits, with typed actions and automatic field error mapping.
+3. Connect RHF to Next.js Server Actions or standalone submits with one consistent API.
+4. Server-backed React forms without glue code: typed flow, error mapping, optimistic rollback, persistence.
+5. Monorepo for hookform-action core, Next.js/standalone adapters, and DevTools.
+
+## 5) Headline Variations (5)
+1. React Hook Form Meets Typed Server Submits
+2. Write the Schema. Write the Action. Skip the Wiring.
+3. Typed Submit Flows for Real RHF Apps
+4. One Hook Between RHF and Server Mutations
+5. Keep React Hook Form. Remove Submit Plumbing.
+
+## 6) Release Announcement Variations (5)
+1. `hookform-action v4.0.3` is live: typed RHF submit flows with Zod mapping, optimistic UI, persistence, and DevTools.
+2. Released: `hookform-action v4.0.3`. Same RHF-first API, better server submit consistency.
+3. `hookform-action v4.0.3` ships typed form-server wiring so you can stop rewriting the same submit glue code.
+4. New release: `hookform-action v4.0.3` for predictable RHF submit pipelines across Next.js and standalone React apps.
+5. `hookform-action v4.0.3` is out. If you manually wire RHF + Zod + server submits, this package standardizes that flow.
+
+## 7) "What This Replaces" Messaging (5)
+1. Replaces manual `FormData` parsing and hand-written type casting.
+2. Replaces custom `fieldErrors -> setError` mapping code per form.
+3. Replaces per-form `useTransition` submit pending wiring.
+4. Replaces ad-hoc optimistic update and rollback logic.
+5. Replaces custom sessionStorage persistence code for wizard flows.
+
+## X / Twitter Post Templates (5)
+1. React Hook Form + server submits usually means repeated glue code. `hookform-action` gives typed submit flows, Zod error mapping, optimistic UI, persistence, and DevTools. `npm i hookform-action`
+2. We built `hookform-action` to remove repetitive RHF submit plumbing: FormData parsing, transition wiring, and field error mapping. Keep RHF, standardize the server flow.
+3. `hookform-action v4.0.3` is live. Typed RHF submit flows for Next.js Server Actions and standalone React apps. One API, less boilerplate, clearer behavior.
+4. If your RHF forms submit to a server, this is the integration layer: typed actions, Zod mapping, pending state, optimistic rollback, and persistence.
+5. `withZod` + `useActionForm`: schema once, typed flow through validation, submit, and response handling. That is the core idea behind `hookform-action`.
+
+## LinkedIn Post Template (1)
+Today we are shipping `hookform-action v4.0.3`.
+
+React Hook Form, Zod, and Server Actions are solid primitives. The repeated work is in the integration layer between them: submit wiring, error mapping, pending state, and recovery behavior.
+
+`hookform-action` standardizes that layer with typed submit flows, automatic Zod -> RHF field mapping, optimistic UI with rollback, multi-step persistence, and DevTools.
+
+It works with Next.js Server Actions and also with standalone React apps through the same API shape.
+
+If your team is rewriting form-server glue code in every feature, this release is for you.
+
+## Release Notes Snippets (5)
+1. This release strengthens the project positioning around typed submit flows for React Hook Form and server integrations.
+2. Messaging now emphasizes practical outcomes: less submit boilerplate, predictable pending state, and consistent field error mapping.
+3. Documentation copy is now aligned across README, docs home, and package descriptions for clearer onboarding.
+4. NPM metadata has been updated to surface Zod mapping, optimistic UI, persistence, and DevTools in a consistent way.
+5. A centralized messaging pack has been added to support launch posts, release notes, and changelog summaries.
+
+## Changelog Highlights (5)
+1. Refined core tagline to "typed submit flows for React Hook Form".
+2. Updated docs home messaging to match the current product scope and tone.
+3. Aligned package descriptions across `hookform-action`, `-standalone`, `-core`, and `-devtools`.
+4. Improved README wording to reinforce technical clarity over marketing phrasing.
+5. Added reusable copy blocks for GitHub, npm, X/Twitter, LinkedIn, release notes, and changelog highlights.
diff --git a/README.md b/README.md
index 7fa9292..8b67170 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,25 @@
 <p align="center">
   <h1 align="center">⚡ hookform-action</h1>
   <p align="center">
-    Seamless integration between <strong>React Hook Form</strong> and <strong>any React framework</strong><br />
-    with Zod validation, automatic type inference, optimistic UI, multi-step persistence, and DevTools.
-    <br />
-    <a href="https://hookform-action-docs.vercel.app/"><strong>📚 Explore the Docs »</strong></a>
-  </p>
+    The missing layer between <strong>React Hook Form</strong> and your server.<br />
+    Typed submit flows, automatic Zod error mapping, optimistic UI with rollback, persistence, and DevTools &mdash;<br />
+    for <strong>Next.js Server Actions</strong>, <strong>Vite</strong>, <strong>Remix</strong>, <strong>Astro</strong>, or any React app.
+  </p>
+  <p align="center">
+    <a href="https://hookform-action-docs.vercel.app/"><strong>📚 Documentation</strong></a>
+    &nbsp;&middot;&nbsp;
+    <a href="#quick-start--nextjs">Quick Start</a>
+    &nbsp;&middot;&nbsp;
+    <a href="#choose-your-path">Choose Your Path</a>
+    &nbsp;&middot;&nbsp;
+    <a href="#examples-that-show-real-value">Examples</a>
+    &nbsp;&middot;&nbsp;
+    <a href="#faq--troubleshooting">FAQ</a>
+    &nbsp;&middot;&nbsp;
+    <a href="#api-reference">API Reference</a>
+    &nbsp;&middot;&nbsp;
+    <a href="#packages">Packages</a>
+  </p>
 </p>
 
 <p align="center">
@@ -19,83 +33,211 @@
 
 ## The Problem
 
-Connecting React Hook Form with server-side actions requires tons of boilerplate: manual FormData conversion, error mapping, state management, and type juggling.
+React Hook Form handles form state beautifully, but the moment you connect it to a server — a Next.js Server Action, a REST endpoint, a Remix action — you end up writing the same boilerplate every single time:
 
-**hookform-action** solves this in one hook — for **Next.js Server Actions**, **Vite SPAs**, **Remix**, **Astro**, or any React app.
+- Manually serialize form values to `FormData` or JSON
+- Wire `useTransition` or `useFormState` to track pending state
+- Parse Zod errors from the server response and map them back to individual fields
+- Handle `prevState` for progressive enhancement
+- Roll back UI state on failure
 
-## Packages
+That is hundreds of lines of plumbing that has nothing to do with your actual business logic.
 
-| Package                                             | Description                          |
-| --------------------------------------------------- | ------------------------------------ |
-| [`hookform-action-core`](packages/core)             | Core library (framework-agnostic)    |
-| [`hookform-action`](packages/next)                  | Next.js adapter (⭐ main install)    |
-| [`hookform-action-standalone`](packages/standalone) | Adapter for Vite, Remix, Astro, SPAs |
-| [`hookform-action-devtools`](packages/devtools)     | Floating debug panel (FormDevTool)   |
+**hookform-action gives you one typed hook that handles all of it.**
 
-## What's New in v3
+---
 
-- 🌍 **Framework-Agnostic Core** — Core decoupled from Next.js. Use with any React framework
-- 🚀 **Standalone Adapter** — `hookform-action-standalone` for Vite, Remix, Astro, or any React SPA
-- 🔍 **DevTools Panel** — `hookform-action-devtools` for real-time form state inspection
-- 🧩 **Internal Plugin System** — Lifecycle hooks (`onBeforeSubmit`, `onSuccess`, `onError`, `onMount`)
-- 🔄 **Zero Breaking Changes** — Existing `hookform-action` imports work identically
+## Why hookform-action?
 
-## Features
+| Concern                | Without hookform-action                    | With hookform-action                |
+| ---------------------- | ------------------------------------------ | ----------------------------------- |
+| Type safety            | Manual casts from `FormData`               | Full inference from your Zod schema |
+| Error mapping          | Parse JSON → iterate fields → `setError()` | Automatic, zero config              |
+| Pending state          | `useTransition` + manual boolean           | `formState.isPending`               |
+| Optimistic UI          | Custom `useOptimistic` wiring              | `optimisticKey` + `optimisticData`  |
+| Client validation      | Duplicate schema setup                     | Auto-detected from `withZod`        |
+| Multi-step persistence | Roll your own sessionStorage               | `persistKey` + `persistDebounce`    |
+| Debugging              | `console.log` everywhere                   | `<FormDevTool />` panel             |
 
-- 🔒 **Full Type Inference** — Types inferred from your action automatically
-- ⚡ **Auto Error Mapping** — Zod `.flatten().fieldErrors` mapped to RHF fields out of the box
-- 🚀 **Optimistic UI** — Native `useOptimistic` integration with automatic rollback
-- 🔍 **Client-Side Validation** — Real-time Zod validation (`onChange`/`onBlur`/`onSubmit`)
-- 💾 **Wizard Persistence** — Multi-step form state saved to sessionStorage with debounce
-- 🧩 **Headless `<Form>`** — Optional wrapper providing FormContext to children
-- 📦 **Tiny Bundle** — ESM + CJS, tree-shakeable, peer deps only
-- 🧪 **81+ Tests** — Vitest + React Testing Library
+---
 
-## Installation
+## Before & After
 
-### Next.js (Server Actions)
+### Without hookform-action
 
-```bash
-npm install hookform-action react-hook-form zod
-```
+```tsx
+// ❌ Manual wiring — ~60 lines to do what one hook does
+"use client";
+import { useForm } from "react-hook-form";
+import { useTransition } from "react";
+
+export function LoginForm() {
+  const [isPending, startTransition] = useTransition();
+  const {
+    register,
+    handleSubmit,
+    setError,
+    formState: { errors },
+  } = useForm();
 
-### Vite / Remix / Astro (Standalone)
+  const onSubmit = (values) => {
+    startTransition(async () => {
+      const formData = new FormData();
+      Object.entries(values).forEach(([k, v]) => formData.append(k, String(v)));
 
-```bash
-npm install hookform-action-standalone react-hook-form zod
+      const result = await loginAction(null, formData);
+
+      if (!result.success && result.errors) {
+        Object.entries(result.errors).forEach(([field, messages]) => {
+          setError(field, { message: messages[0] });
+        });
+      }
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register("email")} />
+      {errors.email && <span>{errors.email.message}</span>}
+      <button disabled={isPending}>Sign in</button>
+    </form>
+  );
+}
 ```
 
-### DevTools (optional)
+### With hookform-action
 
-```bash
-npm install hookform-action-devtools
+```tsx
+// ✅ One hook, fully typed, zero boilerplate
+"use client";
+import { useActionForm } from "hookform-action";
+import { loginAction } from "./actions";
+
+export function LoginForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isPending },
+  } = useActionForm(loginAction, { validationMode: "onChange" });
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      <input {...register("email")} />
+      {errors.email && <span>{errors.email.message}</span>}
+      <button disabled={isPending}>Sign in</button>
+    </form>
+  );
+}
 ```
 
+---
+
+## Packages
+
+hookform-action is a monorepo. Install the adapter that matches your stack.
+
+| Package                                             | Install                            | Description                                                           |
+| --------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------- |
+| [`hookform-action`](packages/next)                  | `npm i hookform-action`            | **Next.js adapter** — Server Actions, FormData, `prevState`           |
+| [`hookform-action-standalone`](packages/standalone) | `npm i hookform-action-standalone` | **Standalone adapter** — fetch, axios, Remix, Vite, Astro             |
+| [`hookform-action-core`](packages/core)             | internal                           | Framework-agnostic core — `useActionFormCore`, `withZod`, persistence |
+| [`hookform-action-devtools`](packages/devtools)     | `npm i hookform-action-devtools`   | Floating debug panel — form state, submission history                 |
+
+> **Zod and react-hook-form are peer dependencies.** Install them alongside any adapter:
+>
+> ```bash
+> npm install hookform-action react-hook-form zod
+> ```
+
+---
+
+## Choose Your Path
+
+Pick the shortest adoption route for your stack:
+
+| You are using | Install | Start here |
+| --- | --- | --- |
+| Next.js App Router + Server Actions | `npm i hookform-action react-hook-form zod` | [Quick Start - Next.js](#quick-start--nextjs) |
+| Vite / Remix / Astro / SPA | `npm i hookform-action-standalone react-hook-form zod` | [Quick Start - Standalone](#quick-start--standalone-vite-remix-astro) |
+| Custom adapter / framework integration | `npm i hookform-action-core react-hook-form zod` | [How It Works](#how-it-works) |
+
+---
+
+## Examples that show real value
+
+These are the examples that convert fastest for new users:
+
+- Login / registration with server validation + field error mapping
+- Client-side validation with a shared schema (no duplication)
+- Optimistic UI with rollback on action failure
+- Multi-step wizard with draft persistence
+
+Live docs pages:
+
+- https://hookform-action-docs.vercel.app/examples
+- https://hookform-action-docs.vercel.app/recipes
+
+---
+
+## What you stop writing
+
+- ❌ Manual `FormData` → typed object conversion
+- ❌ `.flatten().fieldErrors` → `setError()` mapping
+- ❌ Duplicate Zod passes for client-side validation
+- ❌ `useTransition` / `startTransition` wiring
+- ❌ `useOptimistic` setup and rollback logic
+- ❌ `sessionStorage` wiring for multi-step wizards
+
+## What you get
+
+- ✅ **Full type inference** — types flow from your Zod schema through `withZod` into the hook with no manual generics
+- ✅ **Auto error mapping** — server-side Zod errors (`flatten().fieldErrors`) are automatically applied to RHF fields
+- ✅ **Client-side validation** — real-time validation using the same schema, with `onChange`, `onBlur`, or `onSubmit` modes
+- ✅ **Optimistic UI** — native `useOptimistic` (React 19) with automatic rollback and a React 18 fallback
+- ✅ **Wizard persistence** — multi-step form state survives page refreshes via sessionStorage with debounce
+- ✅ **Headless `<Form>`** — optional context provider that distributes form state to any child component
+- ✅ **DevTools** — floating panel with live state, submission history, and debug actions; zero CSS dependencies
+- ✅ **Plugin system** — lifecycle hooks (`onBeforeSubmit`, `onSuccess`, `onError`, `onMount`) for custom integrations
+- ✅ **Tiny footprint** — ESM + CJS, tree-shakeable, only peer deps; no runtime bloat
+- ✅ **81+ tests** — Vitest + React Testing Library
+
+---
+
 ## Quick Start — Next.js
 
-### 1. Create a Server Action
+### 1. Install
+
+```bash
+npm install hookform-action react-hook-form zod
+```
+
+### 2. Create a Server Action
 
 ```ts
-// app/actions.ts
+// app/login/actions.ts
 "use server";
 import { z } from "zod";
 import { withZod } from "hookform-action-core/with-zod";
 
 const schema = z.object({
-  email: z.string().email(),
-  password: z.string().min(8),
+  email: z.string().email("Invalid email"),
+  password: z.string().min(8, "At least 8 characters"),
 });
 
 export const loginAction = withZod(schema, async (data) => {
-  // data is typed as { email: string; password: string }
+  // `data` is fully typed as { email: string; password: string }
+  const user = await db.authenticate(data.email, data.password);
+  if (!user) return { success: false, errors: { email: ["Invalid credentials"] } };
   return { success: true };
 });
 ```
 
-### 2. Use the Hook
+> `withZod` validates on the server, maps Zod errors to the flat `{ errors: Record<string, string[]> }` shape, and attaches the schema to the action so the hook can auto-detect it for client-side validation.
+
+### 3. Use the Hook
 
 ```tsx
-// app/login-form.tsx
+// app/login/login-form.tsx
 "use client";
 import { useActionForm } from "hookform-action";
 import { loginAction } from "./actions";
@@ -104,45 +246,59 @@ export function LoginForm() {
   const {
     register,
     handleSubmit,
-    formState: { errors, isPending },
+    formState: { errors, isPending, isSubmitSuccessful },
   } = useActionForm(loginAction, {
     defaultValues: { email: "", password: "" },
-    validationMode: "onChange",
+    validationMode: "onChange", // schema auto-detected from withZod
+    onSuccess: () => redirect("/dashboard"),
   });
 
   return (
     <form onSubmit={handleSubmit()}>
-      <input {...register("email")} />
-      {errors.email && <span>{errors.email.message}</span>}
-
-      <input {...register("password")} type="password" />
-      {errors.password && <span>{errors.password.message}</span>}
-
-      <button disabled={isPending}>{isPending ? "Signing in..." : "Sign In"}</button>
+      <div>
+        <input {...register("email")} placeholder="Email" />
+        {errors.email && <p>{errors.email.message}</p>}
+      </div>
+
+      <div>
+        <input {...register("password")} type="password" placeholder="Password" />
+        {errors.password && <p>{errors.password.message}</p>}
+      </div>
+
+      <button type="submit" disabled={isPending}>
+        {isPending ? "Signing in…" : "Sign In"}
+      </button>
     </form>
   );
 }
 ```
 
-## Quick Start — Standalone (Vite, Remix, etc.)
+---
+
+## Quick Start — Standalone (Vite, Remix, Astro)
+
+```bash
+npm install hookform-action-standalone react-hook-form zod
+```
 
 ```tsx
+// components/contact-form.tsx
 import { useActionForm } from "hookform-action-standalone";
 import { z } from "zod";
 
 const schema = z.object({
   email: z.string().email(),
-  password: z.string().min(8),
+  message: z.string().min(10),
 });
 
-export function LoginForm() {
+export function ContactForm() {
   const {
     register,
     handleSubmit,
-    formState: { errors, isPending },
+    formState: { errors, isPending, isSubmitSuccessful },
   } = useActionForm({
     submit: async (data) => {
-      const res = await fetch("/api/login", {
+      const res = await fetch("/api/contact", {
         method: "POST",
         body: JSON.stringify(data),
         headers: { "Content-Type": "application/json" },
@@ -150,211 +306,446 @@ export function LoginForm() {
       return res.json();
     },
     schema,
-    validationMode: "onChange",
-    defaultValues: { email: "", password: "" },
+    validationMode: "onBlur",
+    defaultValues: { email: "", message: "" },
   });
 
+  if (isSubmitSuccessful) return <p>Message sent!</p>;
+
   return (
     <form onSubmit={handleSubmit()}>
-      <input {...register("email")} />
-      {errors.email && <span>{errors.email.message}</span>}
+      <input {...register("email")} placeholder="Email" />
+      {errors.email && <p>{errors.email.message}</p>}
 
-      <input {...register("password")} type="password" />
-      {errors.password && <span>{errors.password.message}</span>}
+      <textarea {...register("message")} placeholder="Your message" />
+      {errors.message && <p>{errors.message.message}</p>}
 
-      <button disabled={isPending}>{isPending ? "Signing in..." : "Sign In"}</button>
+      <button type="submit" disabled={isPending}>
+        {isPending ? "Sending…" : "Send"}
+      </button>
     </form>
   );
 }
 ```
 
-## DevTools
+The standalone adapter is **identical to the Next.js API** — the only difference is that you pass a `submit` function instead of a Server Action.
 
-Add a floating debug panel to inspect form state, submission history, and errors:
+---
 
-```tsx
-import { FormDevTool } from "hookform-action-devtools";
+## Mental Model
 
-function App() {
-  const form = useActionForm(/* ... */);
-  return (
-    <>
-      <MyForm form={form} />
-      {process.env.NODE_ENV === "development" && <FormDevTool control={form.control} />}
-    </>
-  );
-}
 ```
+Your Zod schema
+      │
+      ▼
+ withZod(schema, handler)          ← server-side: validates input, types handler
+      │
+      │  returns { success, errors } or handler's return value
+      ▼
+ useActionForm(action, options)    ← client-side: bridges RHF ↔ your action
+      │
+      ├── manages form state (RHF)
+      ├── runs client-side Zod validation (onChange / onBlur / onSubmit)
+      ├── serializes values → calls your action
+      ├── maps server errors → RHF fields (auto)
+      ├── drives isPending via useTransition
+      ├── updates optimistic state (React 19 useOptimistic)
+      └── persists to sessionStorage (wizard mode)
+```
+
+**The key insight:** your schema is the single source of truth. Write it once, attach it with `withZod`, and the hook picks it up automatically — no duplication, no manual error parsing, no type gymnastics.
+
+---
+
+## When to Use / When Not to Use
+
+### ✅ Good fit
+
+- Forms that submit to a server and need to display field-level errors
+- Next.js App Router with Server Actions
+- Vite / Remix / Astro apps submitting to a REST or RPC endpoint
+- Multi-step onboarding wizards where state must survive navigation
+- Any form that benefits from instant optimistic feedback
 
-Features:
+### ⚠️ Might be overkill
 
-- **State Tab** — Live form values, errors, submit status
-- **History Tab** — Every submission with payload, response, duration
-- **Actions Tab** — Debug buttons + summary stats
-- Inline styles (no CSS deps), tree-shakeable, dark theme
+- Simple single-field inline edits with no validation requirements
+- Forms that only run on the client with no server round-trip
+- Projects that already have a custom RHF + server error pipeline they are happy with
 
-## Client-Side Zod Validation
+### ❌ Not designed for
+
+- Non-React environments
+- Uncontrolled `<form action="...">` submissions without JavaScript (use the `formAction` prop for progressive enhancement instead)
+
+---
+
+## Common Use Cases
+
+<details>
+<summary><strong>Login / Registration</strong></summary>
 
 ```tsx
-const form = useActionForm(action, {
-  schema: myZodSchema,
-  validationMode: "onChange", // 'onChange' | 'onBlur' | 'onSubmit'
+const form = useActionForm(registerAction, {
+  defaultValues: { email: "", password: "", confirmPassword: "" },
+  validationMode: "onBlur",
+  onSuccess: () => router.push("/onboarding"),
 });
 ```
 
-With `withZod`, the schema is auto-detected — just set `validationMode`:
+</details>
+
+<details>
+<summary><strong>Optimistic List Item Update</strong></summary>
 
 ```tsx
-const form = useActionForm(withZodAction, {
-  validationMode: "onChange", // schema auto-detected!
+const { register, handleSubmit, optimistic } = useActionForm(updateTodoAction, {
+  defaultValues: { title: "" },
+  optimisticKey: `todo-${todo.id}`,
+  optimisticInitial: todo,
+  optimisticData: (current, values) => ({ ...current, title: values.title }),
 });
+
+// Render optimistic.data immediately — no waiting for the server
+return <span>{optimistic.data.title}</span>;
 ```
 
-## Optimistic UI
+</details>
+
+<details>
+<summary><strong>Multi-Step Wizard</strong></summary>
 
 ```tsx
-const { optimistic, register, handleSubmit } = useActionForm(updateAction, {
-  defaultValues: { title: "" },
-  optimisticKey: "todo-1",
-  optimisticInitial: { id: "1", title: "Buy groceries", completed: false },
-  optimisticData: (currentData, formValues) => ({
-    ...currentData,
-    title: formValues.title,
-  }),
+// Step 1 — values persist to sessionStorage automatically
+const step1 = useActionForm(noopAction, {
+  defaultValues: { name: "", company: "" },
+  persistKey: "onboarding",
 });
 
-// optimistic.data   → instant UI state
-// optimistic.isPending → true while action is in flight
-// optimistic.rollback() → manually revert
+// Step 2 — resumes from persisted state on reload
+const step2 = useActionForm(submitOnboardingAction, {
+  defaultValues: { plan: "", billing: "" },
+  persistKey: "onboarding",
+  onSuccess: () => step1.clearPersistedData(),
+});
 ```
 
-## Multi-Step Wizard with Persistence
+</details>
+
+<details>
+<summary><strong>Custom Error Handling</strong></summary>
 
 ```tsx
-const form = useActionForm(wizardAction, {
-  defaultValues: { name: "", email: "", plan: "" },
-  persistKey: "onboarding-wizard",
-  persistDebounce: 200,
+const form = useActionForm(myAction, {
+  // Override the default Zod error mapper for non-standard API shapes
+  errorMapper: (result) => result?.validationErrors ?? null,
+  onError: (err) => toast.error(err instanceof Error ? err.message : "Something went wrong"),
 });
 ```
 
-## Architecture
+</details>
 
+<details>
+<summary><strong>DevTools</strong></summary>
+
+```tsx
+import { FormDevTool } from "hookform-action-devtools";
+
+export function MyPage() {
+  const form = useActionForm(myAction, {
+    defaultValues: {
+      /* ... */
+    },
+  });
+
+  return (
+    <>
+      <MyForm form={form} />
+      {process.env.NODE_ENV === "development" && <FormDevTool control={form.control} position="bottom-right" />}
+    </>
+  );
+}
 ```
-┌────────────────────────────────────────────────┐
-│        hookform-action-core (core)             │
-│   useActionFormCore · withZod · Form · persist │
-├────────────────────┬───────────────────────────┤
-│   hookform-action  │  hookform-action          │
-│    (Next.js)       │    -standalone            │
-│  (Server Actions)  │  (fetch / REST / gRPC)    │
-└────────────────────┴───────────────────────────┘
-          ┌──────────────────────┐
-          │ hookform-action      │
-          │     -devtools        │
-          │  (FormDevTool panel) │
-          └──────────────────────┘
-```
+
+The DevTools panel shows:
+
+- **State tab** — live field values, errors, and submission status
+- **History tab** — every submission with its payload, response, and duration
+- **Actions tab** — manual debug triggers and aggregate stats
+
+</details>
+
+---
+
+## How It Works
+
+hookform-action is built in three layers.
+
+### Layer 1 — `withZod` (server)
+
+A thin wrapper that runs Zod validation before your handler. On failure it returns `{ success: false, errors: Record<string, string[]> }` — the exact shape the hook expects. On success it calls your handler with fully typed data and attaches the schema as `action.__schema` so the hook can reuse it on the client without duplication.
+
+### Layer 2 — `useActionFormCore` (framework-agnostic)
+
+The engine. It accepts a single `submit: (data: T) => Promise<TResult>` function and handles:
+
+- Initialising React Hook Form with persisted or default values
+- Running client-side schema validation before submission
+- Calling `submit`, setting `isPending` via `useTransition`
+- Parsing the result with `errorMapper` and applying errors to RHF fields
+- Updating the `useOptimistic` state (React 19) or the fallback `useState` (React 18)
+- Debounce-writing form values to sessionStorage when `persistKey` is set
+- Running plugin lifecycle callbacks
+
+### Layer 3 — Adapters (`hookform-action` / `hookform-action-standalone`)
+
+Thin wrappers around the core. The Next.js adapter handles `FormData` serialization and `prevState` tracking. The standalone adapter forwards the user's `submit` function directly. Both expose an identical public API.
+
+---
 
 ## API Reference
 
 ### `useActionForm(action, options?)` — Next.js
 
-| Option              | Type                        | Default      | Description                        |
-| ------------------- | --------------------------- | ------------ | ---------------------------------- |
-| `defaultValues`     | `DefaultValues<T>`          | —            | Initial form values                |
-| `mode`              | `Mode`                      | `'onSubmit'` | RHF validation mode                |
-| `persistKey`        | `string`                    | —            | Enables sessionStorage persistence |
-| `persistDebounce`   | `number`                    | `300`        | Debounce interval (ms)             |
-| `errorMapper`       | `(result) => errors`        | Zod format   | Custom error extractor             |
-| `onSuccess`         | `(result) => void`          | —            | Success callback                   |
-| `onError`           | `(result \| Error) => void` | —            | Error callback                     |
-| `schema`            | `ZodSchema`                 | —            | Client-side Zod schema             |
-| `validationMode`    | `ClientValidationMode`      | `'onSubmit'` | When to run client validation      |
-| `optimisticKey`     | `string`                    | —            | Enables optimistic UI              |
-| `optimisticData`    | `(current, formData) => T`  | —            | Reducer for optimistic state       |
-| `optimisticInitial` | `T`                         | —            | Initial data for optimistic state  |
+```ts
+import { useActionForm } from "hookform-action";
+```
+
+**Options**
+
+| Option              | Type                                   | Default      | Description                                       |
+| ------------------- | -------------------------------------- | ------------ | ------------------------------------------------- |
+| `defaultValues`     | `DefaultValues<T>`                     | —            | Initial field values                              |
+| `mode`              | `Mode`                                 | `'onSubmit'` | RHF internal validation mode                      |
+| `schema`            | `ZodSchema`                            | auto         | Client-side schema (auto-detected from `withZod`) |
+| `validationMode`    | `'onChange' \| 'onBlur' \| 'onSubmit'` | `'onSubmit'` | When to run client validation                     |
+| `persistKey`        | `string`                               | —            | sessionStorage key for wizard persistence         |
+| `persistDebounce`   | `number`                               | `300`        | Write debounce in ms                              |
+| `errorMapper`       | `(result) => FieldErrorRecord \| null` | Zod format   | Custom server error extractor                     |
+| `onSuccess`         | `(result) => void`                     | —            | Called after a successful submission              |
+| `onError`           | `(result \| Error) => void`            | —            | Called after a failed submission                  |
+| `optimisticKey`     | `string`                               | —            | Enables optimistic UI                             |
+| `optimisticInitial` | `T`                                    | —            | Initial optimistic state                          |
+| `optimisticData`    | `(current: T, values) => T`            | —            | Reducer for optimistic state                      |
+| `plugins`           | `Plugin[]`                             | `[]`         | Lifecycle plugin array                            |
 
 ### `useActionForm({ submit, ...options })` — Standalone
 
-Same options as Next.js, plus `submit: (data) => Promise<TResult>` (required).
+```ts
+import { useActionForm } from "hookform-action-standalone";
+```
+
+Identical options, with one addition:
+
+| Option   | Type                            | Required | Description                                |
+| -------- | ------------------------------- | -------- | ------------------------------------------ |
+| `submit` | `(data: T) => Promise<TResult>` | ✅       | The async function that handles submission |
 
 ### Return Value
 
 Everything from RHF's `useForm`, plus:
 
-| Property                       | Description                                         |
-| ------------------------------ | --------------------------------------------------- |
-| `handleSubmit(onValid?)`       | Enhanced submit handler                             |
-| `formState.isSubmitting`       | True while action is running                        |
-| `formState.isPending`          | True during transition                              |
-| `formState.isSubmitSuccessful` | True after success                                  |
-| `formState.submitErrors`       | Raw server error record                             |
-| `formState.actionResult`       | Full action result                                  |
-| `setSubmitError(field, msg)`   | Manually set a server error                         |
-| `persist()`                    | Manually persist to sessionStorage                  |
-| `clearPersistedData()`         | Clear persisted data                                |
-| `formAction`                   | Direct FormData action (Next.js only)               |
-| `optimistic`                   | Optimistic state: `data`, `isPending`, `rollback()` |
+| Property                       | Type                       | Description                                           |
+| ------------------------------ | -------------------------- | ----------------------------------------------------- |
+| `handleSubmit(onValid?)`       | `() => FormEventHandler`   | Enhanced submit handler                               |
+| `formState.isPending`          | `boolean`                  | `true` while transition/request is pending            |
+| `formState.isSubmitting`       | `boolean`                  | submit-in-progress flag (RHF + internal action state) |
+| `formState.isSubmitSuccessful` | `boolean`                  | `true` when the last completed submit succeeded       |
+| `formState.submitErrors`       | `FieldErrorRecord \| null` | structured field errors from validation/error mapping |
+| `formState.actionResult`       | `TResult \| null`          | full result from the last completed action response   |
+| `setSubmitError(field, msg)`   | `fn`                       | Manually set a field error                            |
+| `persist()`                    | `fn`                       | Manually flush state to sessionStorage                |
+| `clearPersistedData()`         | `fn`                       | Remove persisted state for this form                  |
+| `formAction`                   | `(FormData) => void`       | Direct `<form action={...}>` handler _(Next.js only)_ |
+| `optimistic.data`              | `TOptimistic`              | Current optimistic state                              |
+| `optimistic.isPending`         | `boolean`                  | `true` while optimistic update is unconfirmed         |
+| `optimistic.rollback()`        | `fn`                       | Revert to last confirmed state                        |
+
+### Submit Lifecycle (Cheat Sheet)
+
+Use this mental model for action-driven forms:
+
+1. `handleSubmit()` starts the transition and async submit.
+2. `isPending` turns `true` and should drive UI locking/loading.
+3. Submission ends in one of three outcomes:
+   - **success**: `isSubmitSuccessful = true`, `submitErrors = null`, `actionResult = result`
+   - **field errors**: `isSubmitSuccessful = false`, `submitErrors = {...}`, `actionResult = result`
+   - **thrown error**: `isSubmitSuccessful = false`, handle with `onError`
+
+**Which state should I use?**
+
+| Goal                            | State(s) to use                          |
+| ------------------------------- | ---------------------------------------- |
+| Disable submit button           | `formState.isPending`                    |
+| Show loading spinner/text       | `formState.isPending`                    |
+| Run success side-effects        | `!formState.isPending && formState.isSubmitSuccessful` |
+| Render field/server validation  | `formState.submitErrors` + `formState.errors` |
+| Read confirmed response payload | `formState.actionResult` guarded by success checks |
+
+**Correct pattern**
+
+```tsx
+const { handleSubmit, formState } = useActionForm(action, { defaultValues });
+const { isPending, isSubmitSuccessful, submitErrors, actionResult } = formState;
+
+<button disabled={isPending}>
+  {isPending ? "Saving..." : "Save"}
+</button>;
+
+useEffect(() => {
+  if (!isPending && isSubmitSuccessful) {
+    // toast / redirect / reset
+  }
+}, [isPending, isSubmitSuccessful]);
+```
+
+**Common mistakes**
+
+- Using `isSubmitting` for button/loader instead of `isPending`
+- Treating `actionResult` as "success only" data
+- Triggering post-submit logic from `isSubmitSuccessful` without checking `!isPending`
+- Expecting thrown exceptions inside `submitErrors` (use `onError` for that path)
+
+For a full timeline and examples, see [`apps/docs/app/submit-lifecycle/page.tsx`](apps/docs/app/submit-lifecycle/page.tsx).
+
+### `withZod(schema, handler)`
+
+```ts
+import { withZod } from "hookform-action-core/with-zod";
+```
+
+| Argument  | Type                                                 | Description                       |
+| --------- | ---------------------------------------------------- | --------------------------------- |
+| `schema`  | `ZodSchema`                                          | Zod schema to validate against    |
+| `handler` | `(data: z.infer<typeof schema>) => Promise<TResult>` | Called with typed, validated data |
+
+Returns a Server Action with `__schema` attached for client-side auto-detection.
+
+---
 
 ## Migration Guide
 
+### v3 → v4
+
+**No breaking changes.** All existing imports and options remain identical.
+
+What's new in v4:
+
+- Package versions consolidated under the v4 line
+- Documentation IA updated for faster adoption and support deflection
+- Expanded examples + recipes + troubleshooting guides
+- Canonical API naming standardized (`validationMode`, `optimisticData`, `submitErrors`, `actionResult`)
+
+Legacy aliases are still supported for backward compatibility:
+
+| Legacy name | Canonical name |
+| --- | --- |
+| `clientValidation` | `validationMode` |
+| `optimisticReducer` / `optimisticDefault` | `optimisticData` / `optimisticInitial` |
+| `formState.serverErrors` / `formState.lastResult` | `formState.submitErrors` / `formState.actionResult` |
+| `setServerError` | `setSubmitError` |
+| `clearPersisted` | `clearPersistedData` |
+
 ### v2 → v3
 
-**Zero breaking changes.** All v2 imports work identically.
+**No breaking changes.** All existing imports and options remain identical.
 
-New capabilities:
+What's new in v3:
 
-1. Use `hookform-action-standalone` for non-Next.js apps
-2. Add `hookform-action-devtools` for debugging
-3. Access `useActionFormCore` for building custom adapters
+- Use `hookform-action-standalone` for Vite, Remix, and Astro apps
+- Add `hookform-action-devtools` for a floating debug panel in development
+- Use `useActionFormCore` directly to build custom adapters for any framework
+- Add `plugins` to hook into the form submission lifecycle
 
 ### v1 → v2
 
-1. **Replace `isSubmitting` with `isPending`** in button states (recommended):
+**1. Prefer `isPending` over `isSubmitting` for button states**
+
+```diff
+- <button disabled={formState.isSubmitting}>Submit</button>
++ <button disabled={formState.isPending}>Submit</button>
+```
+
+`isSubmitting` remains available, but `isPending` reflects the `useTransition` state and is more accurate during concurrent React renders.
 
-   ```diff
-   - <button disabled={isSubmitting}>
-   + <button disabled={isPending}>
-   ```
+**2. Enable client-side validation** _(optional)_
+
+```diff
+  const form = useActionForm(myAction, {
+    defaultValues: { email: "" },
++   schema: mySchema,
++   validationMode: "onChange",
+  });
+```
 
-2. **Add `schema` for client-side validation** (optional):
-   ```diff
-     const form = useActionForm(myAction, {
-       defaultValues: { email: '' },
-   +   schema: mySchema,
-   +   validationMode: 'onChange',
-     })
-   ```
+If your action was created with `withZod`, the schema is auto-detected — you only need to set `validationMode`.
+
+---
 
 ## Requirements
 
-- React 18+ (React 19 recommended for optimistic UI)
-- React Hook Form 7.50+
-- Zod 3.22+ (optional)
-- Next.js 14+ (for `hookform-action`)
+| Dependency      | Minimum | Notes                                                 |
+| --------------- | ------- | ----------------------------------------------------- |
+| React           | 18.0    | React 19 recommended for native `useOptimistic`       |
+| React Hook Form | 7.50    | —                                                     |
+| Zod             | 3.22    | Peer dependency; optional if not using `withZod`      |
+| Next.js         | 14.0    | Required only for `hookform-action` (Next.js adapter) |
+
+---
+
+## Compatibility Matrix
+
+| Package | Current line | Purpose |
+| --- | --- | --- |
+| `hookform-action` | `4.x` | Next.js adapter (Server Actions) |
+| `hookform-action-standalone` | `4.x` | Non-Next React apps |
+| `hookform-action-core` | `4.x` | Framework-agnostic core |
+| `hookform-action-devtools` | `4.x` | Optional dev debug panel |
+
+---
+
+## FAQ / Troubleshooting
+
+For support-heavy questions and symptom-based debugging:
+
+- FAQ: https://hookform-action-docs.vercel.app/faq
+- Troubleshooting: https://hookform-action-docs.vercel.app/troubleshooting
+
+Most common adoption blockers covered there:
+
+- Action runs but field errors do not render
+- `isPending` vs `isSubmitting` confusion
+- `persistKey` restoring stale drafts
+- Optimistic state not appearing or not rolling back
+- File upload + FormData integration pitfalls
+
+---
 
 ## Development
 
 ```bash
-# Clone and install
+# Clone and install dependencies
 git clone https://github.com/gabpaesschulz/hookform-action.git
 cd hookform-action
 pnpm install
 
-# Dev (core + docs)
+# Start the dev server (core + docs)
 pnpm dev
 
-# Test
+# Run all tests
 pnpm test
 
 # Build all packages
 pnpm build
 
-# Create a changeset
+# Create a changeset before opening a PR
 pnpm changeset
 ```
 
+The repository is a [Turborepo](https://turbo.build/repo) monorepo with [pnpm workspaces](https://pnpm.io/workspaces). Each package under `packages/` is independently versioned and published.
+
+---
+
 ## License
 
 [MIT](LICENSE) © hookform-action contributors
diff --git a/apps/docs/ADVANCED_PATTERNS.md b/apps/docs/ADVANCED_PATTERNS.md
new file mode 100644
index 0000000..53383a6
--- /dev/null
+++ b/apps/docs/ADVANCED_PATTERNS.md
@@ -0,0 +1,1640 @@
+# Advanced Patterns
+
+This guide covers the hard parts — the patterns that go beyond the basic
+"register a field and call handleSubmit" flow.
+Each section is written for a developer who already understands the basics and
+wants to know **exactly how the library behaves** in tricky real-world scenarios.
+
+---
+
+## Table of Contents
+
+| #   | Topic                                                                   | When you need it                              |
+| --- | ----------------------------------------------------------------------- | --------------------------------------------- |
+| 1   | [Nested Objects](#1-nested-objects)                                     | Address, billing, settings sub-forms          |
+| 2   | [Dynamic Lists with useFieldArray](#2-dynamic-lists-with-usefieldarray) | Line items, tags, members, cart               |
+| 3   | [Custom Server Error Mapping](#3-custom-server-error-mapping)           | Non-standard API response shapes              |
+| 4   | [Business Rule Errors](#4-business-rule-errors)                         | Unique constraints, availability, cross-field |
+| 5   | [Reset and Rehydration](#5-reset-and-rehydration)                       | Back button, draft recovery, clear form       |
+| 6   | [Loading Initial Data](#6-loading-initial-data)                         | Edit forms, pre-populated data from DB        |
+| 7   | [Multi-Step Wizard](#7-multi-step-wizard)                               | Onboarding flows, checkout, multi-page forms  |
+| 8   | [Optimistic UI with Rollback](#8-optimistic-ui-with-rollback)           | Like/follow, todo lists, instant feedback     |
+| 9   | [Exceptions vs Validation Errors](#9-exceptions-vs-validation-errors)   | Predictable errors vs unexpected crashes      |
+| 10  | [File Uploads](#10-file-uploads)                                        | Single file, multiple files, progress         |
+
+---
+
+## 1. Nested Objects
+
+### Why this matters
+
+Real-world forms rarely map to flat field lists. An address has `street`,
+`city`, `zip`. A product has `dimensions.width`, `dimensions.height`. A user
+profile has `social.twitter`, `social.github`. The library needs to serialize
+these properly when sending to the server action, and the Zod schema needs to
+reflect the same shape for client-side validation to work.
+
+### Common questions
+
+- "How do I register a nested field — `register('address.city')`?"
+- "My Zod schema has `z.object({ address: z.object({...}) })` but the error
+  never appears on the field."
+- "The server receives `{ 'address.city': 'SP' }` instead of
+  `{ address: { city: 'SP' } }`."
+
+### Common mistakes
+
+- **Using `FormData` action with nested objects.** FormData keys are always
+  strings; `address.city` is a valid key name, not a path. The library
+  serializes dot-paths when building FormData, but the server must parse them
+  back — use the JSON action signature (single-argument) when you have nested
+  data.
+- **Flat Zod schema vs nested TypeScript types.** If your TS type is nested
+  but your Zod schema is flat (e.g. `z.string()` for `address`), client-side
+  validation will either skip nested fields or fire on the wrong path.
+- **`errorMapper` returning flat keys.** The default `errorMapper` expects
+  `{ errors: { 'address.city': ['...'] } }`. Zod's `.flatten()` does **not**
+  produce deep nested objects — it produces dot-joined keys. This is correct
+  and compatible with RHF's `setError('address.city', ...)`.
+
+### What to learn
+
+- RHF uses dot-notation paths for nested fields: `register('address.city')`.
+- `withZod` runs `schema.safeParse(data)` then calls `zodError.flatten()`,
+  which produces flat dot-joined keys. Those keys map exactly to RHF paths.
+- For FormData actions, the library loops `Object.entries` and sets
+  `formData.append('address.city', value)`. If you need real nesting on the
+  server, prefer the JSON action (single argument).
+- TypeScript inference works: `useActionForm<{ address: { city: string } }>`
+  makes `register('address.city')` type-safe.
+
+### Content outline
+
+1. Declaring a nested TypeScript shape
+2. Matching the Zod schema
+3. Registering nested fields with dot-notation
+4. How the library serializes nested data (JSON vs FormData)
+5. Where server errors land (flat dot-keys → RHF path)
+6. Troubleshooting: "error shows on root, not on child field"
+
+### Example
+
+```ts
+// schema.ts
+import { z } from "zod";
+
+export const checkoutSchema = z.object({
+  customer: z.object({
+    name: z.string().min(2, "Name is required"),
+    email: z.string().email("Invalid email"),
+  }),
+  shipping: z.object({
+    street: z.string().min(5),
+    city: z.string().min(2),
+    zip: z.string().regex(/^\d{5}(-\d{4})?$/, "Invalid ZIP"),
+  }),
+});
+
+export type CheckoutFields = z.infer<typeof checkoutSchema>;
+```
+
+```ts
+// actions.ts
+"use server";
+import { withZod } from "hookform-action-core/with-zod";
+import { checkoutSchema } from "./schema";
+
+export const checkoutAction = withZod(checkoutSchema, async (data) => {
+  // data.customer.email – fully typed, already validated
+  await processOrder(data);
+  return { success: true };
+});
+```
+
+```tsx
+// CheckoutForm.tsx
+"use client";
+import { useActionForm } from "hookform-action";
+import { checkoutAction } from "./actions";
+
+export function CheckoutForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors },
+  } = useActionForm(checkoutAction, {
+    defaultValues: {
+      customer: { name: "", email: "" },
+      shipping: { street: "", city: "", zip: "" },
+    },
+    // schema auto-detected from withZod – no need to pass it again
+    validationMode: "onBlur",
+  });
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      {/* Dot-notation path – TypeScript validates the key */}
+      <input {...register("customer.name")} placeholder="Full name" />
+      {errors.customer?.name && <span>{errors.customer.name.message}</span>}
+
+      <input {...register("shipping.zip")} placeholder="ZIP code" />
+      {errors.shipping?.zip && <span>{errors.shipping.zip.message}</span>}
+
+      <button type="submit">Place Order</button>
+    </form>
+  );
+}
+```
+
+> **Key insight:** `errors.customer?.name` not `errors['customer.name']`.
+> RHF stores nested errors as a real nested object. The dot-path is only used
+> in `register()`, `setError()`, and `trigger()`.
+
+---
+
+## 2. Dynamic Lists with `useFieldArray`
+
+### Why this matters
+
+`useFieldArray` is RHF's primitive for fields whose count is unknown at
+compile-time: invoice line items, team members, tag lists, ordered steps.
+The integration works because `useActionForm` returns the full RHF API —
+`useFieldArray` just needs the `control` object from it. The challenge is
+that the server action receives an array, Zod must validate it as an array,
+and errors must land on the correct `items[0].price` path.
+
+### Common questions
+
+- "Should I call `useFieldArray` separately or does the library have a wrapper?"
+- "How do I type the form values so the array is inferred correctly?"
+- "Zod gives me an error on `items` as a whole but I need it per-item."
+- "After a successful submit, the array keeps the old items — how do I reset?"
+
+### Common mistakes
+
+- **Not including `id` in the item shape.** RHF's `useFieldArray` adds its
+  own internal `id` property. If your Zod schema has `id` as required, Zod
+  will accept the RHF-injected UUID fine — but if your backend creates the `id`,
+  keep it optional in the schema (`.optional()` or omit it).
+- **Using `index` as React `key`.** Always use `field.id` (the one returned
+  by `useFieldArray`) as the key, not the array index. This prevents
+  re-render bugs when items are removed or reordered.
+- **Zod `z.array(z.object({...}))` errors not appearing per-field.** Zod
+  `.flatten()` produces keys like `'items[0].price'` which RHF resolves
+  correctly **only** if you access `errors.items?.[0]?.price`.
+- **Resetting the list after submit.** Call `reset()` or `replace([])` from
+  `useFieldArray` inside `onSuccess`.
+
+### What to learn
+
+- `useActionForm` is a superset of `useForm` — destructure `control` and pass
+  it straight to `useFieldArray`.
+- Type the field values with an explicit array: `type Fields = { items: Item[] }`.
+- Zod validates the array server-side and client-side with the same schema.
+- Access errors as `errors.items?.[index]?.fieldName?.message`.
+
+### Content outline
+
+1. Typing form values with an array field
+2. Matching the Zod schema (`z.array(z.object(...))`)
+3. Getting `control` from `useActionForm` and passing to `useFieldArray`
+4. Rendering dynamic rows with `fields.map`
+5. Add / remove / swap operations
+6. Accessing per-item errors
+7. Resetting or partially clearing the list on success
+
+### Example
+
+```ts
+// types-and-schema.ts
+import { z } from "zod";
+
+export const invoiceSchema = z.object({
+  client: z.string().min(1, "Client is required"),
+  items: z
+    .array(
+      z.object({
+        description: z.string().min(1, "Description is required"),
+        qty: z.coerce.number().int().positive("Must be > 0"),
+        unitPrice: z.coerce.number().positive("Must be > 0"),
+      }),
+    )
+    .min(1, "Add at least one item"),
+});
+
+export type InvoiceFields = z.infer<typeof invoiceSchema>;
+```
+
+```ts
+// actions.ts
+"use server";
+import { withZod } from "hookform-action-core/with-zod";
+import { invoiceSchema } from "./types-and-schema";
+
+export const createInvoiceAction = withZod(invoiceSchema, async (data) => {
+  const total = data.items.reduce((acc, i) => acc + i.qty * i.unitPrice, 0);
+  await db.invoices.create({ ...data, total });
+  return { success: true };
+});
+```
+
+```tsx
+// InvoiceForm.tsx
+"use client";
+import { useActionForm } from "hookform-action";
+import { useFieldArray } from "react-hook-form";
+import { createInvoiceAction } from "./actions";
+import type { InvoiceFields } from "./types-and-schema";
+
+export function InvoiceForm() {
+  const {
+    register,
+    control,
+    handleSubmit,
+    formState: { errors },
+    reset,
+  } = useActionForm<InvoiceFields>(createInvoiceAction, {
+    defaultValues: {
+      client: "",
+      items: [{ description: "", qty: 1, unitPrice: 0 }],
+    },
+    onSuccess: () => reset(),
+  });
+
+  // control comes straight from useActionForm – no bridge needed
+  const { fields, append, remove } = useFieldArray({ control, name: "items" });
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      <input {...register("client")} placeholder="Client name" />
+      {errors.client && <span>{errors.client.message}</span>}
+
+      {fields.map((field, index) => (
+        // Always use field.id, never index, as React key
+        <div key={field.id} style={{ display: "flex", gap: 8 }}>
+          <input {...register(`items.${index}.description`)} placeholder="Description" />
+          {errors.items?.[index]?.description && <span>{errors.items[index].description.message}</span>}
+
+          <input type="number" {...register(`items.${index}.qty`)} placeholder="Qty" />
+          {errors.items?.[index]?.qty && <span>{errors.items[index].qty.message}</span>}
+
+          <input type="number" step="0.01" {...register(`items.${index}.unitPrice`)} placeholder="Unit price" />
+          {errors.items?.[index]?.unitPrice && <span>{errors.items[index].unitPrice.message}</span>}
+
+          <button type="button" onClick={() => remove(index)}>
+            Remove
+          </button>
+        </div>
+      ))}
+
+      {/* Form-level array error */}
+      {errors.items?.root && <span>{errors.items.root.message}</span>}
+
+      <button type="button" onClick={() => append({ description: "", qty: 1, unitPrice: 0 })}>
+        Add Item
+      </button>
+
+      <button type="submit">Create Invoice</button>
+    </form>
+  );
+}
+```
+
+> **Tip:** Use `z.coerce.number()` for qty and price fields. HTML inputs
+> always return strings; coercion lets Zod convert them automatically instead
+> of producing a type mismatch error.
+
+---
+
+## 3. Custom Server Error Mapping
+
+### Why this matters
+
+The default `errorMapper` understands responses shaped as
+`{ errors: Record<string, string[]> }` — the format produced by
+`withZod`. But not every team controls the API contract. Legacy backends,
+third-party services, and APIs generated from OpenAPI specs return errors in
+their own formats: `{ error: string }`, `{ fieldErrors: [...] }`,
+`{ violations: [{ field, message }] }`, or HTTP 422 bodies with RFC 7807
+`application/problem+json`. Without a custom mapper, none of these surface as
+field-level errors.
+
+### Common questions
+
+- "My API returns `{ message: 'email already taken' }` — how do I show that
+  on the email field?"
+- "The action returns a `violations` array, not an object. How do I convert it?"
+- "I want global (form-level) errors, not field errors. Where do they go?"
+
+### Common mistakes
+
+- **Returning the whole result from `errorMapper`.** `errorMapper` must return
+  a `FieldErrorRecord` (`Record<string, string[] | undefined>`) or `null` — not
+  the raw result. Return `null` to signal "no errors here, treat as success."
+- **Forgetting to return `null` on success.** If the action returns
+  `{ message: 'OK' }` and your mapper tries to read `.violations`, it returns
+  `undefined` — which the library treats as falsy (no errors). This is correct,
+  but be explicit.
+- **Using a global `_form` key inconsistently.** The library does not reserve
+  any key name for form-level errors. By convention, use `_form` or `root`, but
+  you must render it manually: `errors._form?.message`.
+- **Mapping network errors inside `errorMapper`.** `errorMapper` only runs when
+  the action returns normally. Thrown errors go to `onError` — handle them
+  there.
+
+### What to learn
+
+- `errorMapper: (result: TResult) => FieldErrorRecord | null | undefined`
+- Return `null` → result treated as success.
+- Return a populated object → `setError` is called for each key.
+- Use `_form` key for form-level (non-field) messages.
+- Combine with `onError` for thrown exceptions.
+
+### Content outline
+
+1. The default mapper and its contract
+2. Writing a custom mapper for arbitrary shapes
+3. The `_form` convention for global errors
+4. Rendering form-level errors in the UI
+5. Combining `errorMapper` with `onError`
+6. Testing your mapper in isolation
+
+### Example
+
+```ts
+// Suppose your backend returns:
+// { ok: false, violations: [{ field: 'email', message: 'Already taken' }] }
+// or
+// { ok: false, error: 'Service temporarily unavailable' }
+
+type ApiResponse = {
+  ok: boolean;
+  violations?: Array<{ field: string; message: string }>;
+  error?: string;
+};
+```
+
+```tsx
+// form.tsx
+import { useActionForm } from "hookform-action";
+import type { ErrorMapper } from "hookform-action-core/core-types";
+import { updateProfileAction } from "./actions";
+import type { ApiResponse } from "./types";
+
+const apiErrorMapper: ErrorMapper<ApiResponse> = (result) => {
+  if (result.ok) return null; // no errors – success path
+
+  const errors: Record<string, string[]> = {};
+
+  // Map field-level violations
+  for (const v of result.violations ?? []) {
+    errors[v.field] = [v.message];
+  }
+
+  // Map a global error under the `_form` key
+  if (result.error) {
+    errors._form = [result.error];
+  }
+
+  return Object.keys(errors).length > 0 ? errors : null;
+};
+
+export function ProfileForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors },
+  } = useActionForm(updateProfileAction, {
+    errorMapper: apiErrorMapper,
+    onError: (result) => {
+      // Thrown exceptions land here – result is an Error instance
+      // when the action throws, or the raw TResult when it returns errors.
+      console.error("Submission failed", result);
+    },
+  });
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      {/* Form-level error */}
+      {errors._form && (
+        <div role="alert" className="error-banner">
+          {errors._form.message}
+        </div>
+      )}
+
+      <input {...register("email")} />
+      {errors.email && <span>{errors.email.message}</span>}
+
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+> **Testing tip:** `errorMapper` is a plain function — unit test it
+> independently of React with a simple `expect(apiErrorMapper({ ok: false,
+violations: [{ field: 'email', message: 'Taken' }] }))
+.toEqual({ email: ['Taken'] })`.
+
+---
+
+## 4. Business Rule Errors
+
+### Why this matters
+
+Zod validates _structure_ (type, length, format). But business rules require
+database or external lookups: "is this username taken?", "is this coupon still
+valid?", "does the user have enough balance?". These errors must come from the
+server action and be mapped precisely to the right field. The mechanism is the
+same as any server error — but the **timing, granularity, and mental model**
+are different enough to deserve their own section.
+
+### Common questions
+
+- "My action checks for duplicate email. Do I need a separate Zod check for
+  this?"
+- "The business rule spans two fields (`startDate` / `endDate`). Where do I
+  attach the error?"
+- "I want to show the error on submit, but keep the form open so the user can
+  fix it. Is that the default?"
+
+### Common mistakes
+
+- **Running business logic before Zod validation.** Always validate shape with
+  Zod first. Querying the database with unvalidated input is a security risk and
+  a performance waste.
+- **Returning only `message` without `errors`.** The default mapper ignores
+  `message`. Either add an `errors` key, or provide a custom `errorMapper`.
+- **Calling `router.push()` inside the action after a business rule failure.**
+  The action should return a structured error; the client decides navigation.
+- **Not making the error message actionable.** "Username taken" is good.
+  "Invalid input" is not. The user needs to know exactly what to change.
+
+### What to learn
+
+- Zod validates shape → your handler validates business rules → return errors
+  in the same `{ errors: Record<string, string[]> }` format.
+- Cross-field errors map to the "responsible" field, or to `_form` if the
+  error is truly form-level.
+- `setSubmitError` lets the client imperatively attach a server error to a
+  field without re-submitting.
+- The form stays open with errors after a failed submit — the user can correct
+  and resubmit.
+
+### Content outline
+
+1. The two-layer model: structural (Zod) vs business (custom)
+2. Returning business errors from the action handler
+3. Cross-field business rules (e.g. date range, password confirm)
+4. Using `setSubmitError` for interactive validation (e.g. async username check)
+5. Showing contextual messages vs error-field highlighting
+6. UX patterns: keep-open vs close-on-fail
+
+### Example
+
+```ts
+// actions.ts
+"use server";
+import { withZod } from "hookform-action-core/with-zod";
+import { z } from "zod";
+
+const registerSchema = z.object({
+  username: z.string().min(3).max(30),
+  email: z.string().email(),
+  couponCode: z.string().optional(),
+  startDate: z.string().datetime(),
+  endDate: z.string().datetime(),
+});
+
+export const registerAction = withZod(registerSchema, async (data) => {
+  // Layer 1 – Zod already passed (we only reach here if shape is valid)
+
+  // Layer 2 – Business rules
+  const errors: Record<string, string[]> = {};
+
+  const existingUser = await db.users.findByEmail(data.email);
+  if (existingUser) {
+    errors.email = ["This email is already registered"];
+  }
+
+  const usernameTaken = await db.users.findByUsername(data.username);
+  if (usernameTaken) {
+    errors.username = ["Username is not available"];
+  }
+
+  if (data.couponCode) {
+    const coupon = await db.coupons.findValid(data.couponCode);
+    if (!coupon) {
+      errors.couponCode = ["Coupon is invalid or expired"];
+    }
+  }
+
+  // Cross-field rule: endDate must be after startDate
+  if (new Date(data.endDate) <= new Date(data.startDate)) {
+    // Attach to endDate – it's the "responsible" field
+    errors.endDate = ["End date must be after start date"];
+  }
+
+  if (Object.keys(errors).length > 0) {
+    return { errors }; // same shape as withZod validation errors
+  }
+
+  await db.users.create(data);
+  return { success: true };
+});
+```
+
+```tsx
+// Async field-level check without re-submitting the whole form
+"use client";
+import { useActionForm } from "hookform-action";
+import { registerAction, checkUsernameAction } from "./actions";
+
+export function RegisterForm() {
+  const {
+    register,
+    handleSubmit,
+    setSubmitError,
+    formState: { errors },
+  } = useActionForm(registerAction);
+
+  // Check availability on blur, before submit
+  const handleUsernameBlur = async (e: React.FocusEvent<HTMLInputElement>) => {
+    const value = e.target.value;
+    if (value.length < 3) return;
+
+    const result = await checkUsernameAction(value);
+    if (!result.available) {
+      // Imperatively set a server error on the field
+      setSubmitError("username", "Username is not available");
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      <input {...register("username")} onBlur={handleUsernameBlur} />
+      {errors.username && <span>{errors.username.message}</span>}
+
+      <button type="submit">Register</button>
+    </form>
+  );
+}
+```
+
+---
+
+## 5. Reset and Rehydration
+
+### Why this matters
+
+"Reset" covers three distinct behaviors that users often confuse:
+
+1. **Clear the form** — reset to empty or default values after a successful
+   submit.
+2. **Restore a draft** — bring back what the user typed if they navigated away
+   (`persistKey`).
+3. **Reload server data** — populate the form with fresh data from the server
+   (edit flows).
+
+Getting these wrong causes the classic bugs: the form shows stale data after
+edit, the draft is never cleared after submit, or the form is empty when the
+user expected a draft.
+
+### Common questions
+
+- "After a successful submit, the form still shows the old data. What do I do?"
+- "I call `reset()` inside `onSuccess` but the persisted draft isn't cleared."
+- "I set `persistKey` — now when I edit an existing record, the stale draft
+  overrides the server data."
+- "How do I reset to server-fetched values, not to empty defaults?"
+
+### Common mistakes
+
+- **Calling `reset()` without clearing persisted data.** `reset()` resets RHF's
+  in-memory state, but `sessionStorage` is not touched. Call
+  `clearPersistedData()` (returned by the hook) alongside `reset()`.
+- **Using `persistKey` on edit forms.** Persistence is designed for _new
+  record_ flows where losing a draft is painful. Edit forms should always show
+  server data, not a stale draft. Either skip `persistKey` entirely on edit
+  forms, or scope the key with the record ID so each record has its own
+  independent draft.
+- **Calling `reset(serverData)` before the component mounts.** `reset` must be
+  called inside a `useEffect` when data arrives asynchronously — calling it
+  during render has no effect on the next paint.
+
+### What to learn
+
+- `reset()` — resets to `defaultValues` (or a new value if passed).
+- `clearPersistedData()` — removes the sessionStorage entry.
+- `onSuccess` callback receives the action result — ideal place to reset.
+- For edit forms: pass server data as `defaultValues` and avoid `persistKey`,
+  or scope the key to the record ID.
+
+### Content outline
+
+1. The three reset scenarios and when each applies
+2. Clearing form after successful create
+3. Resetting to new server data (edit flow)
+4. Clearing persisted drafts on success
+5. Scoping `persistKey` to a record ID for edit + persist
+6. Using `useEffect` to apply async default values
+
+### Example
+
+```tsx
+// Scenario A: Clear after create
+export function CreatePostForm() {
+  const { register, handleSubmit, reset, clearPersistedData, formState } = useActionForm(createPostAction, {
+    defaultValues: { title: "", body: "" },
+    persistKey: "create-post-draft",
+    onSuccess: () => {
+      reset(); // reset RHF state to defaultValues
+      clearPersistedData(); // wipe sessionStorage so draft doesn't return
+    },
+  });
+
+  // ...
+}
+```
+
+```tsx
+// Scenario B: Edit form – no persistKey, reset when server data arrives
+type PostFields = { title: string; body: string };
+
+export function EditPostForm({ post }: { post: Post }) {
+  const { register, handleSubmit, reset, formState } = useActionForm<PostFields>(updatePostAction, {
+    // Pass server data directly – no persistKey needed
+    defaultValues: { title: post.title, body: post.body },
+  });
+
+  // If `post` prop changes (e.g. route navigation), sync the form
+  useEffect(() => {
+    reset({ title: post.title, body: post.body });
+  }, [post.id, reset]);
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      <input {...register("title")} />
+      <textarea {...register("body")} />
+      <button type="submit" disabled={!formState.isDirty}>
+        Save Changes
+      </button>
+    </form>
+  );
+}
+```
+
+```tsx
+// Scenario C: Edit form where user might have a draft
+// Scope persistKey to record ID – each record keeps its own draft independently
+export function EditPostWithDraft({ post }: { post: Post }) {
+  const { register, handleSubmit, reset, clearPersistedData } = useActionForm<PostFields>(updatePostAction, {
+    defaultValues: { title: post.title, body: post.body },
+    // Key is scoped to this specific post
+    persistKey: `edit-post-${post.id}`,
+    onSuccess: () => {
+      clearPersistedData();
+      reset({ title: post.title, body: post.body });
+    },
+  });
+
+  // ...
+}
+```
+
+> **Gotcha:** The library merges persisted data on top of `defaultValues`
+> during initialization (`{ ...defaultValues, ...persisted }`). On edit forms
+> without ID-scoped keys, a draft from a _different_ record leaks into the
+> current form.
+
+---
+
+## 6. Loading Initial Data
+
+### Why this matters
+
+Edit forms need to show existing data. The challenge is that this data is
+often fetched asynchronously — either from a server component that passes it
+as props, from a `useEffect` fetch, or from a router loader. The hook's
+`defaultValues` are only read once, on mount. If data arrives after mount,
+you must call `reset()` to sync.
+
+### Common questions
+
+- "I'm using `async/await` in a Server Component to fetch the post. How do I
+  pass it to the form?"
+- "My data fetch is in a `useEffect`. When I set `defaultValues` after fetch
+  it doesn't update the form."
+- "I want to show a loading skeleton while data loads, then populate the form."
+- "How do `isLoading` and `defaultValues` interact?"
+
+### Common mistakes
+
+- **Setting `defaultValues` inside the hook as a promise.** RHF's
+  `defaultValues` accepts a promise (async default values), but the library
+  wraps `useForm` and the merging logic with `persistKey` runs synchronously.
+  Pass resolved values, not promises.
+- **Not calling `reset()` when async data arrives.** `useEffect(() => {
+if (data) reset(data) }, [data])` is the correct pattern.
+- **Passing `undefined` fields.** If a field is present in the schema but
+  absent from `defaultValues`, RHF treats it as an uncontrolled component. Set
+  explicit empty values.
+- **Forgetting `disabled` state during loading.** While data is loading, the
+  submit button should be disabled to prevent premature submission with empty
+  values.
+
+### What to learn
+
+- Preferred pattern in Next.js App Router: fetch in Server Component, pass as
+  props — no `useEffect` needed.
+- SPA / client-fetch pattern: empty `defaultValues` on mount, `reset(data)`
+  when fetch resolves.
+- RHF's `formState.isLoading` is `true` while async `defaultValues` promise
+  is pending — can be used to show a skeleton.
+
+### Content outline
+
+1. The App Router way: Server Component → Client Component props
+2. Client-side fetch with `useEffect` + `reset`
+3. Handling loading states (skeleton, disabled submit)
+4. What happens to `persistKey` when initial data arrives late
+5. Partial population: only some fields have server defaults
+
+### Example
+
+```tsx
+// App Router (recommended): fetch in Server Component
+// page.tsx (Server Component)
+import { EditPostForm } from "./EditPostForm";
+import { db } from "@/lib/db";
+
+export default async function EditPostPage({ params }: { params: { id: string } }) {
+  const post = await db.posts.findById(params.id);
+  if (!post) notFound();
+
+  // Data is available synchronously from the client component's perspective
+  return <EditPostForm post={post} />;
+}
+```
+
+```tsx
+// EditPostForm.tsx (Client Component)
+"use client";
+import { useActionForm } from "hookform-action";
+import { updatePostAction } from "./actions";
+
+export function EditPostForm({ post }: { post: Post }) {
+  const {
+    register,
+    handleSubmit,
+    formState: { isDirty, isSubmitting },
+  } = useActionForm(updatePostAction, {
+    // Data is already available on mount – no useEffect needed
+    defaultValues: {
+      title: post.title,
+      slug: post.slug,
+      body: post.body,
+      published: post.published,
+    },
+  });
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      <input {...register("title")} />
+      <input {...register("slug")} />
+      <textarea {...register("body")} />
+      <button type="submit" disabled={!isDirty || isSubmitting}>
+        {isSubmitting ? "Saving..." : "Save"}
+      </button>
+    </form>
+  );
+}
+```
+
+```tsx
+// SPA pattern: client-side fetch
+"use client";
+import { useEffect } from "react";
+import { useActionForm } from "hookform-action-standalone";
+
+export function EditPostFormSPA({ postId }: { postId: string }) {
+  const {
+    register,
+    handleSubmit,
+    reset,
+    formState: { isSubmitting },
+  } = useActionForm({
+    submit: async (data) => updatePost(postId, data),
+    defaultValues: { title: "", body: "" }, // start empty
+  });
+
+  useEffect(() => {
+    fetchPost(postId).then((post) => {
+      // Sync form with fetched data
+      reset({ title: post.title, body: post.body });
+    });
+  }, [postId, reset]);
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      <input {...register("title")} />
+      <button type="submit" disabled={isSubmitting}>
+        Save
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+## 7. Multi-Step Wizard
+
+### Why this matters
+
+Multi-step flows (onboarding, checkout, application) have several hard
+problems at once:
+
+- **Partial validation**: step 1 should only validate step 1 fields.
+- **Draft preservation**: a page refresh or accidental navigation should not
+  lose progress.
+- **Final submit**: the action runs once, with all data from all steps.
+- **Back navigation**: going back should show the previously entered values.
+- **Server errors that belong to an earlier step**: the user is on step 3 but
+  the error is on `email` (step 1) — they must be brought back.
+
+### Common questions
+
+- "How do I validate only the current step's fields before advancing?"
+- "Should I have one `useActionForm` for the entire wizard, or one per step?"
+- "How do I go back and keep the data I entered in step 2?"
+- "The server returned an error on a field in step 1, but I'm showing step 3.
+  What do I do?"
+
+### Common mistakes
+
+- **One form per step.** Data is split across multiple React state atoms,
+  making the final submit complex. Use **one** `useActionForm` for the entire
+  wizard — this is what `persistKey` is designed for.
+- **Advancing without validating.** Calling `setStep(step + 1)` directly
+  allows garbage data into later steps. Always call `trigger(fields)` first.
+- **Not clearing the draft on success.** `persistKey` saves every keystroke.
+  After a successful final submit, call `clearPersistedData()` to prevent the
+  completed wizard from reappearing.
+- **Forgetting that `trigger` validates against the _full_ schema.** If step 1
+  validates `firstName` but the full Zod schema also requires `plan`, Zod will
+  fail. Use `.pick()` or `.partial()` for per-step trigger checks, or rely
+  purely on `trigger` (which validates only the specified fields against the
+  schema, reporting only those errors).
+
+### What to learn
+
+- `trigger(['field1', 'field2'])` — validates a subset of fields and reports
+  only their errors. Returns `true` if all pass.
+- `persistKey` — saves the whole form state across renders and page navigations.
+- One `useActionForm` per wizard, `step` controlled by local `useState`.
+- On success, call `reset()` and `clearPersistedData()`.
+- If a server error lands on an earlier step's field, track which step owns
+  which field and `setStep` to that step.
+
+### Content outline
+
+1. Architecture: one form for the whole wizard
+2. Declaring all fields in `defaultValues`
+3. Per-step validation with `trigger`
+4. Draft persistence with `persistKey`
+5. Progress indicator tied to step state
+6. Handling server errors that belong to earlier steps
+7. Success state and cleanup
+
+### Example
+
+```ts
+// schema.ts
+import { z } from "zod";
+
+export const onboardingSchema = z.object({
+  // Step 1
+  firstName: z.string().min(2),
+  lastName: z.string().min(2),
+  email: z.string().email(),
+  // Step 2
+  company: z.string().min(1),
+  role: z.string().min(1),
+  // Step 3
+  plan: z.enum(["free", "pro", "enterprise"]),
+  agreeToTerms: z.literal(true, { errorMap: () => ({ message: "Required" }) }),
+});
+
+export type OnboardingFields = z.infer<typeof onboardingSchema>;
+
+// Map each field to the step that owns it – used for error routing
+export const FIELD_STEP: Record<keyof OnboardingFields, number> = {
+  firstName: 0,
+  lastName: 0,
+  email: 0,
+  company: 1,
+  role: 1,
+  plan: 2,
+  agreeToTerms: 2,
+};
+```
+
+```tsx
+// WizardForm.tsx
+"use client";
+import { useState } from "react";
+import { useActionForm } from "hookform-action";
+import { onboardingAction } from "./actions";
+import { type OnboardingFields, FIELD_STEP } from "./schema";
+
+const STEPS_FIELDS: (keyof OnboardingFields)[][] = [
+  ["firstName", "lastName", "email"],
+  ["company", "role"],
+  ["plan", "agreeToTerms"],
+];
+
+export function WizardForm() {
+  const [step, setStep] = useState(0);
+
+  const {
+    register,
+    handleSubmit,
+    trigger,
+    setStep: _,
+    formState: { errors, isSubmitting, isSubmitSuccessful },
+    reset,
+    clearPersistedData,
+  } = useActionForm<OnboardingFields>(onboardingAction, {
+    defaultValues: {
+      firstName: "",
+      lastName: "",
+      email: "",
+      company: "",
+      role: "",
+      plan: "free",
+      agreeToTerms: false as unknown as true,
+    },
+    persistKey: "onboarding-wizard",
+    persistDebounce: 200,
+    onSuccess: () => {
+      reset();
+      clearPersistedData();
+    },
+    onError: (result) => {
+      // If server returns errors on earlier-step fields, navigate back
+      if (result && typeof result === "object" && "errors" in result) {
+        const errorFields = Object.keys((result as { errors: Record<string, unknown> }).errors);
+        const earliestStep = Math.min(...errorFields.map((f) => FIELD_STEP[f as keyof OnboardingFields] ?? step));
+        if (earliestStep < step) setStep(earliestStep);
+      }
+    },
+  });
+
+  if (isSubmitSuccessful) {
+    return <div>🎉 Welcome aboard!</div>;
+  }
+
+  const advance = async () => {
+    const valid = await trigger(STEPS_FIELDS[step]);
+    if (valid) setStep((s) => s + 1);
+  };
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      {/* Step 1 */}
+      {step === 0 && (
+        <>
+          <input {...register("firstName")} placeholder="First name" />
+          {errors.firstName && <span>{errors.firstName.message}</span>}
+
+          <input {...register("email")} type="email" placeholder="Email" />
+          {errors.email && <span>{errors.email.message}</span>}
+        </>
+      )}
+
+      {/* Step 2 */}
+      {step === 1 && (
+        <>
+          <input {...register("company")} placeholder="Company" />
+          {errors.company && <span>{errors.company.message}</span>}
+        </>
+      )}
+
+      {/* Step 3 */}
+      {step === 2 && (
+        <>
+          <select {...register("plan")}>
+            <option value="free">Free</option>
+            <option value="pro">Pro</option>
+            <option value="enterprise">Enterprise</option>
+          </select>
+          {errors.plan && <span>{errors.plan.message}</span>}
+
+          <input type="checkbox" {...register("agreeToTerms")} />
+          {errors.agreeToTerms && <span>{errors.agreeToTerms.message}</span>}
+        </>
+      )}
+
+      <div>
+        {step > 0 && (
+          <button type="button" onClick={() => setStep((s) => s - 1)}>
+            Back
+          </button>
+        )}
+        {step < 2 ? (
+          <button type="button" onClick={advance}>
+            Next
+          </button>
+        ) : (
+          <button type="submit" disabled={isSubmitting}>
+            {isSubmitting ? "Submitting..." : "Finish"}
+          </button>
+        )}
+      </div>
+    </form>
+  );
+}
+```
+
+> **Performance note:** `persistKey` debounces writes to `sessionStorage` by
+> 200 ms (configurable via `persistDebounce`). For long wizards, lower it to
+> 100 ms — 200 ms means a fast typer could lose 1-2 keystrokes on a crash.
+
+---
+
+## 8. Optimistic UI with Rollback
+
+### Why this matters
+
+Optimistic UI makes the UI respond instantly to user actions — before the
+server confirms success. A todo item appears in the list the moment the user
+clicks "Add", not after 1-2 seconds of waiting. This dramatically improves
+perceived performance. The hard part is the rollback: when the server returns
+an error or throws, the optimistic item must disappear and the original state
+must be restored — automatically, without the developer writing manual undo
+logic.
+
+### Common questions
+
+- "What's the difference between `optimisticData` and `optimisticInitial`?"
+- "My optimistic item stays in the list even after the server fails."
+- "Can I use optimistic UI without React 19?"
+- "How do I show which items are 'pending' vs confirmed?"
+
+### Common mistakes
+
+- **Not providing `optimisticInitial`.** The optimistic state starts from
+  `optimisticInitial`. If it's `undefined`, `optimistic.data` is `undefined`
+  on first render, causing a flash or crash.
+- **Computing optimistic state that's too complex to reverse.** The reducer
+  should be a pure function that only adds/changes what the user action should
+  add/change. Don't call side-effect APIs inside `optimisticData`.
+- **Confusing `optimistic.data` with `actionResult`.** `optimistic.data` is
+  the _speculative_ state — used only in the UI while `isPending` is true.
+  `actionResult` is the _confirmed_ server response. Combine them correctly:
+  if `isPending`, show `optimistic.data`; otherwise show `actionResult`.
+- **On React 18, expecting true concurrent optimistic updates.** The library
+  falls back to a `useState` shim on React 18 — `optimistic.data` updates
+  synchronously but the UI doesn't get the concurrent-mode benefits of React
+  19's `useOptimistic`. It still works correctly, just without the frame-level
+  batching.
+
+### What to learn
+
+- `optimisticKey` — enables the feature (any unique string).
+- `optimisticInitial` — the starting state (your server-fetched data).
+- `optimisticData` — pure reducer: `(current, formValues) => newState`.
+- `optimistic.data` — the speculative state for the UI.
+- `optimistic.isPending` — true while the action is in flight.
+- `optimistic.rollback()` — manually revert to the last confirmed state.
+- Automatic rollback: happens on thrown exception or when `errorMapper` returns
+  errors.
+
+### Content outline
+
+1. How `useOptimistic` works under the hood (React 19 vs 18 fallback)
+2. Configuring the three options: `optimisticKey`, `optimisticInitial`,
+   `optimisticData`
+3. Reading the optimistic state in the UI
+4. Styling pending items (animated, italic, "saving..." badge)
+5. Automatic vs manual rollback
+6. What happens when the action throws
+
+### Example
+
+```ts
+// actions.ts
+"use server";
+export type Task = { id: string; title: string; done: boolean };
+
+let tasks: Task[] = [
+  { id: "1", title: "Design the schema", done: true },
+  { id: "2", title: "Write the action", done: false },
+];
+
+export async function addTaskAction(raw: unknown) {
+  await new Promise((r) => setTimeout(r, 1500)); // simulate latency
+
+  const { title } = raw as { title: string };
+  if (!title?.trim()) return { errors: { title: ["Title is required"] }, tasks };
+
+  // Simulate a random failure to demonstrate rollback
+  if (title.toLowerCase() === "fail") {
+    throw new Error("Server error – optimistic update will be rolled back");
+  }
+
+  const newTask: Task = { id: crypto.randomUUID(), title: title.trim(), done: false };
+  tasks = [...tasks, newTask];
+  return { tasks };
+}
+```
+
+```tsx
+// TaskList.tsx
+"use client";
+import { useActionForm } from "hookform-action";
+import { type Task, addTaskAction } from "./actions";
+
+type FormFields = { title: string };
+type ActionResult = { tasks: Task[]; errors?: { title?: string[] } };
+
+const initialTasks: Task[] = [
+  { id: "1", title: "Design the schema", done: true },
+  { id: "2", title: "Write the action", done: false },
+];
+
+export function TaskList() {
+  const {
+    register,
+    handleSubmit,
+    reset,
+    formState: { errors, isPending, actionResult },
+    optimistic,
+  } = useActionForm<FormFields, ActionResult, Task[]>(addTaskAction, {
+    defaultValues: { title: "" },
+    optimisticKey: "tasks",
+    optimisticInitial: initialTasks,
+    optimisticData: (current, values) => [...current, { id: `temp-${Date.now()}`, title: values.title, done: false }],
+  });
+
+  // Merge strategy:
+  //   - While pending: show optimistic list (contains temp item)
+  //   - After confirmation: show server-confirmed list
+  const confirmedTasks = actionResult?.tasks ?? initialTasks;
+  const displayTasks = optimistic?.isPending ? optimistic.data ?? confirmedTasks : confirmedTasks;
+
+  return (
+    <div>
+      <ul>
+        {displayTasks.map((task) => {
+          const isPendingItem = task.id.startsWith("temp-");
+          return (
+            <li
+              key={task.id}
+              style={{
+                opacity: isPendingItem ? 0.6 : 1,
+                fontStyle: isPendingItem ? "italic" : "normal",
+              }}
+            >
+              {task.done ? "✅" : "⬜"} {task.title}
+              {isPendingItem && <small> (saving...)</small>}
+            </li>
+          );
+        })}
+      </ul>
+
+      <form onSubmit={handleSubmit(() => reset({ title: "" }))}>
+        <input {...register("title")} placeholder="New task title" />
+        {errors.title && <span>{errors.title.message}</span>}
+        <button type="submit" disabled={isPending}>
+          {isPending ? "Adding..." : "Add Task"}
+        </button>
+      </form>
+
+      {/* Manual rollback button – useful for undo features */}
+      {optimistic?.isPending && (
+        <button type="button" onClick={optimistic.rollback}>
+          Cancel (Undo)
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+> **Architecture note:** `optimisticData` is called **before** the action
+> runs. `confirmedOptimisticRef` is only updated when the action returns
+> without errors. A thrown exception or returned field errors will trigger
+> automatic rollback to `confirmedOptimisticRef.current`.
+
+---
+
+## 9. Exceptions vs Validation Errors
+
+### Why this matters
+
+There are two fundamentally different failure modes in a server action:
+
+| Mode                 | Cause                      | How it reaches the client        |
+| -------------------- | -------------------------- | -------------------------------- |
+| **Validation error** | `{ errors: {...} }` return | `errorMapper` → RHF `setError`   |
+| **Exception**        | Action `throw`s            | `onError` callback → raw `Error` |
+
+Conflating these two leads to silent failures, unhandled error states, and
+confusing UX. Validation errors should keep the form open and highlighted.
+Exceptions should surface a toast, banner, or redirect.
+
+### Common questions
+
+- "My action throws when the DB is down. Why doesn't the error appear on the
+  form?"
+- "Should I throw or return `{ errors }` when validation fails?"
+- "I'm catching the exception in `onError` but I also want to show a message.
+  How?"
+- "What happens to the optimistic state when the action throws?"
+
+### Common mistakes
+
+- **Throwing for expected validation failures.** Validation failures are
+  expected — return a structured error object. Throw only for unexpected
+  conditions (network down, DB unavailable, bug in code).
+- **Using `errorMapper` to handle thrown errors.** `errorMapper` only runs
+  when the action _returns_ a value. If it throws, `onError` is called with an
+  `Error` instance — `errorMapper` is never invoked.
+- **Not providing `onError` at all.** Without `onError`, thrown exceptions are
+  silently swallowed (after rollback and form state reset). The user sees
+  nothing — the form just becomes unblocked with no feedback.
+- **Calling `setError` inside a `catch` block outside the hook.** Use
+  `setSubmitError` (returned by the hook) to imperatively set errors from
+  outside the mapper.
+
+### What to learn
+
+- **Return `{ errors }` for validation failures** (duplicates, rule violations,
+  malformed data caught server-side).
+- **Throw for infrastructure failures** (DB down, auth service unreachable,
+  unexpected exceptions).
+- `onError(result | Error)` — `result` can be either the raw TResult (when the
+  action returns field errors and the mapper fires) or an `Error` instance
+  (when the action throws).
+- Check `result instanceof Error` in `onError` to distinguish the two cases.
+- Optimistic state is automatically rolled back in both cases.
+
+### Content outline
+
+1. The semantic difference: expected vs unexpected failure
+2. Server action authoring guide: when to throw vs return
+3. How the library routes each failure mode
+4. Implementing `onError` for toast / banner / redirect
+5. Type narrowing inside `onError`: `result instanceof Error`
+6. Global error boundary vs in-form error handling
+
+### Example
+
+```ts
+// actions.ts – demonstrating both patterns
+"use server";
+import { withZod } from "hookform-action-core/with-zod";
+import { paymentSchema } from "./schema";
+
+export const processPaymentAction = withZod(paymentSchema, async (data) => {
+  // ✅ Expected failure: return structured errors
+  const card = await paymentGateway.validate(data.cardNumber);
+  if (!card.valid) {
+    return { errors: { cardNumber: [card.message] } };
+  }
+
+  const fundsCheck = await paymentGateway.checkFunds(data.cardNumber, data.amount);
+  if (!fundsCheck.sufficient) {
+    return { errors: { amount: ["Insufficient funds"] } };
+  }
+
+  // ✅ Infrastructure failure: let it throw naturally
+  // The payment gateway throws on network error or service outage.
+  // withZod does not catch this – it propagates to onError.
+  const charge = await paymentGateway.charge(data);
+
+  return { success: true, transactionId: charge.id };
+});
+```
+
+```tsx
+// PaymentForm.tsx
+"use client";
+import { toast } from "sonner";
+import { useActionForm } from "hookform-action";
+import { processPaymentAction } from "./actions";
+
+type PaymentResult = {
+  success?: boolean;
+  transactionId?: string;
+  errors?: Record<string, string[]>;
+};
+
+export function PaymentForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+    setSubmitError,
+  } = useActionForm(processPaymentAction, {
+    onSuccess: (result) => {
+      toast.success(`Payment confirmed! ID: ${result.transactionId}`);
+    },
+    onError: (result) => {
+      if (result instanceof Error) {
+        // Thrown exception – infrastructure failure
+        toast.error("Payment service is unavailable. Please try again later.");
+        // Optionally set a form-level error for inline display too
+        setSubmitError("_form" as never, result.message);
+      }
+      // If result is not an Error instance, it's a validation failure
+      // already handled by errorMapper → RHF setError above.
+      // No need to do anything here.
+    },
+  });
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      {/* Form-level error banner */}
+      {errors._form && (
+        <div role="alert" className="error-banner">
+          {errors._form.message}
+        </div>
+      )}
+
+      <input {...register("cardNumber")} placeholder="Card number" />
+      {errors.cardNumber && <span>{errors.cardNumber.message}</span>}
+
+      <input type="number" {...register("amount")} placeholder="Amount" />
+      {errors.amount && <span>{errors.amount.message}</span>}
+
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? "Processing..." : "Pay Now"}
+      </button>
+    </form>
+  );
+}
+```
+
+> **Mental model:** think of it as HTTP status codes. A `422 Unprocessable
+Entity` is a validation error — return it. A `503 Service Unavailable` is
+> an infrastructure failure — throw it.
+
+---
+
+## 10. File Uploads
+
+### Why this matters
+
+File inputs are the most common reason to reach for `FormData` instead of JSON
+actions. Files cannot be JSON-serialized. They must travel as `multipart/form-data`.
+The library detects whether the action accepts `(prevState, formData)` or
+`(data)` and serializes accordingly — but the developer must register the file
+input correctly, handle the File object on the server, and deal with the
+complexities of size limits, progress, and multiple files.
+
+### Common questions
+
+- "Do I use `register('avatar')` or a custom `onChange`?"
+- "Should my action accept `FormData` or can I use a JSON action with files?"
+- "How do I access the file on the server inside `withZod`?"
+- "How do I show upload progress?"
+- "Can I upload multiple files at once?"
+
+### Common mistakes
+
+- **Using a JSON action (`(data: unknown) => Promise<R>`) for file uploads.**
+  JSON cannot carry `File` objects. The library auto-converts them to `File`
+  inside a `FormData` when calling a FormData-signature action, but it cannot
+  serialize `File` to JSON. Use a FormData action for file uploads.
+- **Forgetting `encType="multipart/form-data"` on the form element.** Not
+  required when using `handleSubmit()` (JavaScript handles the request), but
+  required if using `formAction` with progressive enhancement.
+- **Using `z.instanceof(File)` in a server-side `withZod` action.**
+  `File` is not available on the server in Node.js < 20. Use `z.any()` or
+  `z.custom<File>()` in the Zod schema for the file field, and do the runtime
+  check manually.
+- **No upload progress with server actions.** Server Actions in Next.js use the
+  Fetch API under the hood — `onUploadProgress` is not available. For progress,
+  use a pre-signed URL approach (S3, Cloudflare R2) or a dedicated upload
+  service.
+
+### What to learn
+
+- Use a FormData action (two-argument signature) for file uploads.
+- `register('avatar')` works — RHF stores `FileList` for file inputs.
+- The library serializes `File` and `FileList` into `FormData.append` calls.
+- Validate file type and size server-side (or with a custom `validate` in RHF).
+- For multiple files, use `accept` attribute and `multiple` on the input.
+- For progress, consider pre-signed URLs instead of Server Actions.
+
+### Content outline
+
+1. Why files require FormData (not JSON)
+2. How the library serializes File / FileList to FormData
+3. Registering a file input with `register`
+4. Server-side: reading the file from FormData
+5. Client-side file validation (type, size) before submit
+6. Multiple file uploads
+7. Upload progress: limitations and alternatives (pre-signed URLs)
+8. Displaying previews with `URL.createObjectURL`
+
+### Example
+
+```ts
+// actions.ts (FormData action signature)
+"use server";
+import { z } from "zod";
+import { put } from "@vercel/blob"; // or any storage SDK
+
+// Note: z.custom<File> is used for server-side – File may not be available
+// in all Node.js versions. Validate type/size manually.
+const uploadSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+  // For the file field: use z.any() and validate manually
+  avatar: z.any(),
+});
+
+export async function uploadAvatarAction(prevState: unknown, formData: FormData) {
+  const name = formData.get("name");
+  const avatar = formData.get("avatar");
+
+  // Manual Zod validation on the non-file fields
+  const parsed = uploadSchema.safeParse({ name, avatar });
+  if (!parsed.success) {
+    return { errors: parsed.error.flatten().fieldErrors };
+  }
+
+  if (!(avatar instanceof File) || avatar.size === 0) {
+    return { errors: { avatar: ["Please select a file"] } };
+  }
+
+  // File size limit: 5 MB
+  const MAX_SIZE = 5 * 1024 * 1024;
+  if (avatar.size > MAX_SIZE) {
+    return { errors: { avatar: ["File must be smaller than 5 MB"] } };
+  }
+
+  // Allowed types
+  const ALLOWED_TYPES = ["image/jpeg", "image/png", "image/webp"];
+  if (!ALLOWED_TYPES.includes(avatar.type)) {
+    return { errors: { avatar: ["Only JPEG, PNG, and WebP are allowed"] } };
+  }
+
+  const blob = await put(`avatars/${name}-${Date.now()}`, avatar, {
+    access: "public",
+  });
+
+  return { success: true, url: blob.url };
+}
+```
+
+```tsx
+// AvatarUploadForm.tsx
+"use client";
+import { useState } from "react";
+import { useActionForm } from "hookform-action";
+import { uploadAvatarAction } from "./actions";
+
+type UploadFields = { name: string; avatar: FileList };
+type UploadResult = { success?: boolean; url?: string; errors?: Record<string, string[]> };
+
+export function AvatarUploadForm() {
+  const [preview, setPreview] = useState<string | null>(null);
+
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting, isSubmitSuccessful },
+    watch,
+  } = useActionForm<UploadFields, UploadResult>(uploadAvatarAction, {
+    defaultValues: { name: "" },
+  });
+
+  // Live preview using URL.createObjectURL
+  const avatarFiles = watch("avatar");
+  const handleAvatarChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (file) {
+      setPreview(URL.createObjectURL(file));
+    }
+  };
+
+  if (isSubmitSuccessful) {
+    return <p>✅ Avatar uploaded!</p>;
+  }
+
+  return (
+    <form onSubmit={handleSubmit()} encType="multipart/form-data">
+      <input {...register("name")} placeholder="Your name" />
+      {errors.name && <span>{errors.name.message}</span>}
+
+      <input
+        type="file"
+        accept="image/jpeg,image/png,image/webp"
+        {...register("avatar", {
+          // Client-side validation before hitting the server
+          validate: {
+            maxSize: (files: FileList) =>
+              !files[0] || files[0].size <= 5 * 1024 * 1024 ? true : "File must be smaller than 5 MB",
+            acceptedTypes: (files: FileList) =>
+              !files[0] || ["image/jpeg", "image/png", "image/webp"].includes(files[0].type)
+                ? true
+                : "Only JPEG, PNG, and WebP are allowed",
+          },
+          onChange: handleAvatarChange,
+        })}
+      />
+      {errors.avatar && <span>{errors.avatar.message as string}</span>}
+
+      {preview && (
+        <img src={preview} alt="Preview" style={{ width: 80, height: 80, borderRadius: "50%", objectFit: "cover" }} />
+      )}
+
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? "Uploading..." : "Upload Avatar"}
+      </button>
+    </form>
+  );
+}
+```
+
+```tsx
+// Multiple file uploads
+<input
+  type="file"
+  multiple
+  accept="image/*"
+  {...register("photos", {
+    validate: {
+      maxFiles: (files: FileList) => (files.length <= 5 ? true : "Maximum 5 photos allowed"),
+    },
+  })}
+/>
+```
+
+> **Upload progress:** Server Actions in Next.js don't expose upload progress
+> events. If you need a progress bar, upload directly to S3/R2 using a
+> pre-signed URL (fetch the URL from a server action, then `PUT` the file
+> directly from the browser using the Fetch API with a `ReadableStream`), and
+> only save the resulting URL via a second server action.
+
+---
+
+## Quick Reference
+
+### Error flow summary
+
+```
+User submits
+    │
+    ├─► Client Zod validation (if schema + validationMode != 'onSubmit')
+    │       └── fails → setError on field, no network call
+    │
+    ├─► handleSubmit (RHF validation gate)
+    │       └── fails → setError on field, no network call
+    │
+    ├─► executeAction
+    │       ├── Client Zod (onSubmit mode)
+    │       │       └── fails → setError, no network call
+    │       │
+    │       ├── Optimistic update applied
+    │       │
+    │       ├── Action called
+    │       │       ├── Returns → errorMapper(result)
+    │       │       │       ├── null/undefined → onSuccess
+    │       │       │       └── { field: [...] } → setError per field
+    │       │       │               └── onError(result)  [result is TResult]
+    │       │       │               └── optimistic ROLLBACK
+    │       │       └── Throws → onError(error)  [error is Error]
+    │       │               └── optimistic ROLLBACK
+```
+
+### When to use which option
+
+| Scenario                                      | Option                                                   |
+| --------------------------------------------- | -------------------------------------------------------- |
+| Show errors from a non-standard API           | `errorMapper`                                            |
+| Imperatively attach a server error to a field | `setSubmitError`                                         |
+| Save progress across page navigations         | `persistKey`                                             |
+| Clear saved progress after success            | `clearPersistedData()`                                   |
+| Validate a subset of fields (wizard)          | `trigger(['field1', 'field2'])`                          |
+| Instant UI feedback before server confirms    | `optimisticKey` + `optimisticData` + `optimisticInitial` |
+| React to infrastructure failures (throw)      | `onError`                                                |
+| React to successful submission                | `onSuccess`                                              |
+| Pre-populate an edit form                     | `defaultValues` + `reset(serverData)` in `useEffect`     |
+| Upload files                                  | Two-argument FormData action                             |
+
+### Type imports cheatsheet
+
+```ts
+import type {
+  ErrorMapper, // (result: TResult) => FieldErrorRecord | null
+  FieldErrorRecord, // Record<string, string[] | undefined>
+  ActionResult, // { success?: boolean; errors?: FieldErrorRecord; data?: T }
+  OptimisticState, // { data: T; isPending: boolean; rollback: () => void }
+  OptimisticReducer, // (current: T, formValues: F) => T
+} from "hookform-action-core/core-types";
+```
diff --git a/apps/docs/app/api-reference/page.tsx b/apps/docs/app/api-reference/page.tsx
index 2099306..eb488e1 100644
--- a/apps/docs/app/api-reference/page.tsx
+++ b/apps/docs/app/api-reference/page.tsx
@@ -9,6 +9,19 @@ export default function ApiReferencePage() {
 
       <h1 className="text-3xl font-bold mb-8">API Reference</h1>
 
+      <div className="mb-10 rounded-xl border border-brand-500/20 bg-brand-500/5 p-4">
+        <p className="text-sm text-gray-300 mb-2">
+          Canonical naming in v4: <code>validationMode</code>, <code>optimisticData</code>,
+          <code>submitErrors</code>, <code>actionResult</code>.
+        </p>
+        <p className="text-xs text-gray-500">
+          Legacy aliases are still supported for backward compatibility (
+          <code>clientValidation</code>, <code>optimisticReducer</code>,{" "}
+          <code>serverErrors</code>, <code>lastResult</code>, <code>setServerError</code>,{" "}
+          <code>clearPersisted</code>).
+        </p>
+      </div>
+
       {/* useActionForm – Next.js */}
       <section className="mb-16">
         <h2 className="text-2xl font-bold mb-4 text-brand-400">useActionForm (Next.js)</h2>
@@ -128,7 +141,7 @@ export default function ApiReferencePage() {
           </code>
         </p>
         <p className="text-gray-400 mb-6">
-          <span className="text-emerald-400 text-xs font-medium mr-1">v3</span>
+          <span className="text-emerald-400 text-xs font-medium mr-1">v4</span>
           Same API, but takes an options object with <code>submit</code> instead of a Server Action.
         </p>
 
@@ -179,7 +192,7 @@ export default function ApiReferencePage() {
           </code>
         </p>
         <p className="text-gray-400 mb-6">
-          <span className="text-cyan-400 text-xs font-medium mr-1">v3</span>
+          <span className="text-cyan-400 text-xs font-medium mr-1">v4</span>
           Framework-agnostic core hook. Adapters (Next.js, standalone) wrap this. Use directly only
           for building custom adapters.
         </p>
@@ -198,6 +211,16 @@ export default function ApiReferencePage() {
         <p className="text-gray-400 text-sm mb-4">
           Returns everything from React Hook Form&apos;s <code>useForm</code>, plus:
         </p>
+        <p className="text-xs text-gray-500 mb-4">
+          Need a full timeline and state-by-state guide? See{' '}
+          <a
+            href="/submit-lifecycle"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
+            Submit Lifecycle
+          </a>
+          .
+        </p>
         <div className="overflow-x-auto">
           <table className="w-full text-sm text-left">
             <thead className="text-gray-400 border-b border-gray-800">
@@ -216,27 +239,39 @@ export default function ApiReferencePage() {
               <tr className="border-b border-gray-800/50">
                 <td className="py-3 pr-4 font-mono text-brand-300">formState.isSubmitting</td>
                 <td className="py-3 pr-4 font-mono text-xs">boolean</td>
-                <td className="py-3 text-gray-400">True while action is running.</td>
+                <td className="py-3 text-gray-400">
+                  Submit-in-progress flag (RHF + internal action state). Prefer{' '}
+                  <code>isPending</code> for UX locking/loading.
+                </td>
               </tr>
               <tr className="border-b border-gray-800/50">
                 <td className="py-3 pr-4 font-mono text-brand-300">formState.isPending</td>
                 <td className="py-3 pr-4 font-mono text-xs">boolean</td>
-                <td className="py-3 text-gray-400">True during transition.</td>
+                <td className="py-3 text-gray-400">
+                  True while transition/request is pending. Primary state for disabled buttons and
+                  spinners.
+                </td>
               </tr>
               <tr className="border-b border-gray-800/50">
                 <td className="py-3 pr-4 font-mono text-brand-300">formState.isSubmitSuccessful</td>
                 <td className="py-3 pr-4 font-mono text-xs">boolean</td>
-                <td className="py-3 text-gray-400">True after success.</td>
+                <td className="py-3 text-gray-400">
+                  True when the last completed submit succeeded (no field errors).
+                </td>
               </tr>
               <tr className="border-b border-gray-800/50">
                 <td className="py-3 pr-4 font-mono text-brand-300">formState.submitErrors</td>
                 <td className="py-3 pr-4 font-mono text-xs">FieldErrorRecord | null</td>
-                <td className="py-3 text-gray-400">Raw server error record.</td>
+                <td className="py-3 text-gray-400">
+                  Structured field errors from validation/client mapping.
+                </td>
               </tr>
               <tr className="border-b border-gray-800/50">
                 <td className="py-3 pr-4 font-mono text-brand-300">formState.actionResult</td>
                 <td className="py-3 pr-4 font-mono text-xs">TResult | null</td>
-                <td className="py-3 text-gray-400">Full result from last action.</td>
+                <td className="py-3 text-gray-400">
+                  Full result from the last completed action response (use with success guards).
+                </td>
               </tr>
               <tr className="border-b border-gray-800/50">
                 <td className="py-3 pr-4 font-mono text-brand-300">setSubmitError</td>
@@ -376,7 +411,7 @@ const customMapper = (result) => {
       <section className="mb-16">
         <h2 className="text-2xl font-bold mb-4 text-cyan-400">Plugin System (Internal)</h2>
         <p className="text-gray-400 mb-6">
-          <span className="text-cyan-400 text-xs font-medium mr-1">v3</span>
+          <span className="text-cyan-400 text-xs font-medium mr-1">v4</span>
           Internal plugin architecture for extending useActionFormCore. Not yet part of the public
           API.
         </p>
@@ -442,22 +477,22 @@ const customMapper = (result) => {
             <tbody className="text-gray-300">
               <tr className="border-b border-gray-800/50">
                 <td className="py-3 pr-4 font-mono text-brand-300">hookform-action-core</td>
-                <td className="py-3 pr-4 font-mono text-xs">3.0.0</td>
+                <td className="py-3 pr-4 font-mono text-xs">4.0.3</td>
                 <td className="py-3 text-gray-400">Core + Next.js adapter (backward-compatible)</td>
               </tr>
               <tr className="border-b border-gray-800/50">
                 <td className="py-3 pr-4 font-mono text-emerald-300">hookform-action</td>
-                <td className="py-3 pr-4 font-mono text-xs">3.0.0</td>
+                <td className="py-3 pr-4 font-mono text-xs">4.0.3</td>
                 <td className="py-3 text-gray-400">Standalone Next.js adapter package</td>
               </tr>
               <tr className="border-b border-gray-800/50">
                 <td className="py-3 pr-4 font-mono text-emerald-300">hookform-action-standalone</td>
-                <td className="py-3 pr-4 font-mono text-xs">3.0.0</td>
+                <td className="py-3 pr-4 font-mono text-xs">4.0.3</td>
                 <td className="py-3 text-gray-400">Adapter for Vite, Remix, Astro, SPAs</td>
               </tr>
               <tr className="border-b border-gray-800/50">
                 <td className="py-3 pr-4 font-mono text-purple-300">hookform-action-devtools</td>
-                <td className="py-3 pr-4 font-mono text-xs">3.0.0</td>
+                <td className="py-3 pr-4 font-mono text-xs">4.0.3</td>
                 <td className="py-3 text-gray-400">Floating debug panel (FormDevTool)</td>
               </tr>
             </tbody>
diff --git a/apps/docs/app/devtools/page.tsx b/apps/docs/app/devtools/page.tsx
index 0edc74e..2758e53 100644
--- a/apps/docs/app/devtools/page.tsx
+++ b/apps/docs/app/devtools/page.tsx
@@ -8,7 +8,7 @@ export default function DevToolsPage() {
       </div>
 
       <div className="inline-flex items-center gap-2 bg-purple-500/10 text-purple-400 border border-purple-500/20 rounded-full px-4 py-1.5 text-sm font-medium mb-6">
-        <span>v3</span>
+        <span>v4</span>
         <span className="text-gray-600">·</span>
         <span>hookform-action-devtools</span>
       </div>
diff --git a/apps/docs/app/examples/_components/example-shell.tsx b/apps/docs/app/examples/_components/example-shell.tsx
new file mode 100644
index 0000000..f1655d4
--- /dev/null
+++ b/apps/docs/app/examples/_components/example-shell.tsx
@@ -0,0 +1,50 @@
+import type { ReactNode } from "react";
+
+interface ExampleShellProps {
+  title: string;
+  subtitle: string;
+  impact: string;
+  differential: string;
+  message: string;
+  children: ReactNode;
+}
+
+export function ExampleShell({
+  title,
+  subtitle,
+  impact,
+  differential,
+  message,
+  children,
+}: ExampleShellProps) {
+  return (
+    <div className="max-w-4xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/examples" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to examples hub
+        </a>
+      </div>
+
+      <h1 className="text-3xl font-bold mb-2">{title}</h1>
+      <p className="text-gray-400 mb-6">{subtitle}</p>
+
+      <div className="grid sm:grid-cols-3 gap-3 mb-10 text-sm">
+        <div className="border border-gray-800 rounded-lg p-3 bg-gray-900/30">
+          <p className="text-gray-500 uppercase tracking-wide text-xs mb-1">Impact</p>
+          <p className="text-brand-300 font-medium">{impact}</p>
+        </div>
+        <div className="border border-gray-800 rounded-lg p-3 bg-gray-900/30">
+          <p className="text-gray-500 uppercase tracking-wide text-xs mb-1">Differential</p>
+          <p className="text-gray-200">{differential}</p>
+        </div>
+        <div className="border border-gray-800 rounded-lg p-3 bg-gray-900/30">
+          <p className="text-gray-500 uppercase tracking-wide text-xs mb-1">Message</p>
+          <p className="text-emerald-300">{message}</p>
+        </div>
+      </div>
+
+      {children}
+    </div>
+  );
+}
+
diff --git a/apps/docs/app/examples/catalog.ts b/apps/docs/app/examples/catalog.ts
new file mode 100644
index 0000000..5054d4c
--- /dev/null
+++ b/apps/docs/app/examples/catalog.ts
@@ -0,0 +1,125 @@
+export type ExampleFormat = "live" | "recipe";
+export type ExampleImpact = "Muito alto" | "Alto" | "Medio";
+
+export interface StrategicExample {
+  order: number;
+  slug: string;
+  title: string;
+  adapter: "Next.js" | "Standalone" | "Cross" | "Devtools";
+  impact: ExampleImpact;
+  format: ExampleFormat;
+  differential: string;
+  message: string;
+}
+
+export const strategicExamples: StrategicExample[] = [
+  {
+    order: 1,
+    slug: "next-quickstart-login",
+    title: "Next Quickstart Login",
+    adapter: "Next.js",
+    impact: "Muito alto",
+    format: "live",
+    differential: "RHF + Server Action + erro mapeado sem boilerplate",
+    message: "Conecte RHF a Server Actions em minutos.",
+  },
+  {
+    order: 2,
+    slug: "standalone-quickstart-login",
+    title: "Standalone Quickstart Login",
+    adapter: "Standalone",
+    impact: "Muito alto",
+    format: "recipe",
+    differential: "Mesma API do Next adapter, sem dependencia de framework",
+    message: "Troque para submit() e rode em Vite, Remix ou Astro.",
+  },
+  {
+    order: 3,
+    slug: "migration-rhf-manual-to-hookform-action",
+    title: "Migration Manual Wiring -> hookform-action",
+    adapter: "Cross",
+    impact: "Muito alto",
+    format: "recipe",
+    differential: "Antes/depois da DX em codigo real",
+    message: "Menos estados manuais, menos glue code, menos bugs.",
+  },
+  {
+    order: 4,
+    slug: "next-schema-once-signup",
+    title: "Next Schema Once Signup",
+    adapter: "Next.js",
+    impact: "Alto",
+    format: "live",
+    differential: "withZod + inferencia de tipos + validacao client/server",
+    message: "Schema vive uma vez e tipa todo o fluxo.",
+  },
+  {
+    order: 5,
+    slug: "standalone-rest-error-mapper",
+    title: "Standalone REST Error Mapper",
+    adapter: "Standalone",
+    impact: "Alto",
+    format: "recipe",
+    differential: "Mapeia contratos de erro legados sem refatorar backend",
+    message: "Adapte APIs reais sem retrabalho massivo.",
+  },
+  {
+    order: 6,
+    slug: "next-optimistic-profile-update",
+    title: "Next Optimistic Profile Update",
+    adapter: "Next.js",
+    impact: "Alto",
+    format: "recipe",
+    differential: "Optimistic UI com rollback nativo em poucas linhas",
+    message: "Entrega UX instantanea com seguranca de estado.",
+  },
+  {
+    order: 7,
+    slug: "next-wizard-onboarding-persist",
+    title: "Next Wizard Onboarding Persist",
+    adapter: "Next.js",
+    impact: "Alto",
+    format: "live",
+    differential: "Persistencia de wizard com persistKey e limpeza automatica",
+    message: "Usuario nao perde progresso ao navegar ou atualizar.",
+  },
+  {
+    order: 8,
+    slug: "devtools-debug-submission-history",
+    title: "Devtools Debug Submission History",
+    adapter: "Devtools",
+    impact: "Medio",
+    format: "recipe",
+    differential: "Inspecao de estado e historico de submissions em runtime",
+    message: "Debug de form deixa de ser tentativa e erro.",
+  },
+  {
+    order: 9,
+    slug: "cross-adapter-parity-next-vs-standalone",
+    title: "Cross Adapter Parity Next vs Standalone",
+    adapter: "Cross",
+    impact: "Medio",
+    format: "recipe",
+    differential: "Portabilidade comprovada com diff minimo",
+    message: "Evite lock-in de framework sem abrir mao de DX.",
+  },
+  {
+    order: 10,
+    slug: "next-optimistic-list-rollback",
+    title: "Next Optimistic List Rollback",
+    adapter: "Next.js",
+    impact: "Medio",
+    format: "live",
+    differential: "Caso avancado de optimistic para lista com falha simulada",
+    message: "Mostra robustez em cenarios de producao.",
+  },
+];
+
+export const topAdoptionSlugs = new Set([
+  "next-quickstart-login",
+  "standalone-quickstart-login",
+  "migration-rhf-manual-to-hookform-action",
+  "next-schema-once-signup",
+  "next-wizard-onboarding-persist",
+]);
+
diff --git a/apps/docs/app/examples/cross-adapter-parity-next-vs-standalone/page.tsx b/apps/docs/app/examples/cross-adapter-parity-next-vs-standalone/page.tsx
new file mode 100644
index 0000000..43f8a69
--- /dev/null
+++ b/apps/docs/app/examples/cross-adapter-parity-next-vs-standalone/page.tsx
@@ -0,0 +1,40 @@
+import { ExampleShell } from "../_components/example-shell";
+
+export default function CrossAdapterParityPage() {
+  return (
+    <ExampleShell
+      title="Cross Adapter Parity: Next vs Standalone"
+      subtitle="Side-by-side comparison to prove portability and reduce migration risk."
+      impact="Medio"
+      differential="Same API surface, different submit transport."
+      message="Mude de adapter com diff pequeno."
+    >
+      <div className="grid lg:grid-cols-2 gap-5">
+        <div>
+          <h2 className="text-lg font-semibold mb-3">Next.js Adapter</h2>
+          <div className="code-block text-gray-300">
+            <pre>{`import { useActionForm } from "hookform-action";
+
+const form = useActionForm(loginAction, {
+  defaultValues: { email: "", password: "" },
+  validationMode: "onChange",
+});`}</pre>
+          </div>
+        </div>
+
+        <div>
+          <h2 className="text-lg font-semibold mb-3">Standalone Adapter</h2>
+          <div className="code-block text-gray-300">
+            <pre>{`import { useActionForm } from "hookform-action-standalone";
+
+const form = useActionForm({
+  submit: async (values) => post("/login", values),
+  defaultValues: { email: "", password: "" },
+  validationMode: "onChange",
+});`}</pre>
+          </div>
+        </div>
+      </div>
+    </ExampleShell>
+  );
+}
diff --git a/apps/docs/app/examples/devtools-debug-submission-history/page.tsx b/apps/docs/app/examples/devtools-debug-submission-history/page.tsx
new file mode 100644
index 0000000..84464c1
--- /dev/null
+++ b/apps/docs/app/examples/devtools-debug-submission-history/page.tsx
@@ -0,0 +1,41 @@
+import { ExampleShell } from "../_components/example-shell";
+
+export default function DevtoolsDebugSubmissionHistoryPage() {
+  return (
+    <ExampleShell
+      title="Devtools Debug Submission History"
+      subtitle="Instrument forms in development with a floating panel for state + history."
+      impact="Medio"
+      differential="Faster diagnosis of validation and async submission regressions."
+      message="Debug guiado por dados, nao por tentativa e erro."
+    >
+      <div className="code-block text-gray-300 mb-8">
+        <pre>{`import { useActionForm } from "hookform-action";
+import { FormDevTool } from "hookform-action-devtools";
+
+function App() {
+  const form = useActionForm(loginAction, {
+    defaultValues: { email: "", password: "" },
+  });
+
+  return (
+    <>
+      <form onSubmit={form.handleSubmit()}>
+        <input {...form.register("email")} />
+        <input type="password" {...form.register("password")} />
+      </form>
+      {process.env.NODE_ENV === "development" && (
+        <FormDevTool control={form.control} defaultOpen />
+      )}
+    </>
+  );
+}`}</pre>
+      </div>
+
+      <p className="text-sm text-gray-500">
+        Strategic point: teams adopt faster when debugging behavior is visible and repeatable.
+      </p>
+    </ExampleShell>
+  );
+}
+
diff --git a/apps/docs/app/examples/login/login-form.tsx b/apps/docs/app/examples/login/login-form.tsx
index 0d854dd..f13d4f3 100644
--- a/apps/docs/app/examples/login/login-form.tsx
+++ b/apps/docs/app/examples/login/login-form.tsx
@@ -7,7 +7,7 @@ export function LoginForm() {
   const {
     register,
     handleSubmit,
-    formState: { errors, isSubmitting, isSubmitSuccessful },
+    formState: { errors, isPending, isSubmitSuccessful },
   } = useActionForm(loginAction, {
     defaultValues: { email: '', password: '' },
   })
@@ -55,10 +55,10 @@ export function LoginForm() {
 
       <button
         type="submit"
-        disabled={isSubmitting}
+        disabled={isPending}
         className="w-full py-2.5 bg-brand-600 hover:bg-brand-500 disabled:bg-gray-700 disabled:cursor-not-allowed text-white rounded-lg font-medium transition-colors"
       >
-        {isSubmitting ? (
+        {isPending ? (
           <span className="inline-flex items-center gap-2">
             <svg className="animate-spin h-4 w-4" viewBox="0 0 24 24" aria-hidden="true">
               <circle
diff --git a/apps/docs/app/examples/login/page.tsx b/apps/docs/app/examples/login/page.tsx
index 332526c..86320d4 100644
--- a/apps/docs/app/examples/login/page.tsx
+++ b/apps/docs/app/examples/login/page.tsx
@@ -60,7 +60,7 @@ export function LoginForm() {
   const {
     register,
     handleSubmit,
-    formState: { errors, isSubmitting, isSubmitSuccessful },
+    formState: { errors, isPending, isSubmitSuccessful },
   } = useActionForm(loginAction, {
     defaultValues: { email: '', password: '' },
   })
@@ -75,8 +75,8 @@ export function LoginForm() {
       <input {...register('password')} type="password" />
       {errors.password && <span>{errors.password.message}</span>}
 
-      <button disabled={isSubmitting}>
-        {isSubmitting ? 'Signing in...' : 'Sign In'}
+      <button disabled={isPending}>
+        {isPending ? 'Signing in...' : 'Sign In'}
       </button>
     </form>
   )
diff --git a/apps/docs/app/examples/migration-rhf-manual-to-hookform-action/page.tsx b/apps/docs/app/examples/migration-rhf-manual-to-hookform-action/page.tsx
new file mode 100644
index 0000000..b4f7abb
--- /dev/null
+++ b/apps/docs/app/examples/migration-rhf-manual-to-hookform-action/page.tsx
@@ -0,0 +1,54 @@
+import { ExampleShell } from "../_components/example-shell";
+
+export default function MigrationManualToHookformActionPage() {
+  return (
+    <ExampleShell
+      title="Migration: Manual Wiring -> hookform-action"
+      subtitle="Before/after comparison that makes DX gains obvious for maintainers."
+      impact="Muito alto"
+      differential="Concrete reduction in boilerplate and failure points."
+      message="Less glue code is the easiest adoption argument."
+    >
+      <div className="grid lg:grid-cols-2 gap-5">
+        <div>
+          <h2 className="text-lg font-semibold mb-3 text-red-300">Before (manual wiring)</h2>
+          <div className="code-block text-gray-300">
+            <pre>{`const form = useForm<LoginValues>();
+const [isPending, startTransition] = useTransition();
+
+const onSubmit = form.handleSubmit(async (values) => {
+  const parsed = schema.safeParse(values);
+  if (!parsed.success) {
+    mapZodToSetError(parsed.error.flatten().fieldErrors, form.setError);
+    return;
+  }
+
+  startTransition(async () => {
+    const result = await loginAction(parsed.data);
+    mapApiErrorsToSetError(result, form.setError);
+  });
+});`}</pre>
+          </div>
+        </div>
+
+        <div>
+          <h2 className="text-lg font-semibold mb-3 text-emerald-300">After (hookform-action)</h2>
+          <div className="code-block text-gray-300">
+            <pre>{`const form = useActionForm(loginAction, {
+  defaultValues: { email: "", password: "" },
+  validationMode: "onChange",
+});
+
+return (
+  <form onSubmit={form.handleSubmit()}>
+    <input {...form.register("email")} />
+    <input type="password" {...form.register("password")} />
+    <button disabled={form.formState.isPending}>Sign In</button>
+  </form>
+);`}</pre>
+          </div>
+        </div>
+      </div>
+    </ExampleShell>
+  );
+}
diff --git a/apps/docs/app/examples/next-optimistic-list-rollback/page.tsx b/apps/docs/app/examples/next-optimistic-list-rollback/page.tsx
new file mode 100644
index 0000000..a35ee31
--- /dev/null
+++ b/apps/docs/app/examples/next-optimistic-list-rollback/page.tsx
@@ -0,0 +1,25 @@
+import { ExampleShell } from "../_components/example-shell";
+import { OptimisticTodoForm } from "../optimistic/optimistic-todo-form";
+
+export const dynamic = "force-dynamic";
+
+export default function NextOptimisticListRollbackPage() {
+  return (
+    <ExampleShell
+      title="Next Optimistic List Rollback"
+      subtitle="Advanced optimistic flow that predicts list updates and rolls back on failure."
+      impact="Medio"
+      differential="Shows robustness under latency and server errors."
+      message="Optimistic UI seguro para mutacoes de lista."
+    >
+      <div className="bg-gray-900/50 border border-gray-800 rounded-xl p-8 mb-10">
+        <OptimisticTodoForm />
+      </div>
+
+      <p className="text-sm text-gray-500">
+        Tip: submit a todo containing <code className="text-gray-300">fail</code> to trigger rollback.
+      </p>
+    </ExampleShell>
+  );
+}
+
diff --git a/apps/docs/app/examples/next-optimistic-profile-update/page.tsx b/apps/docs/app/examples/next-optimistic-profile-update/page.tsx
new file mode 100644
index 0000000..2577302
--- /dev/null
+++ b/apps/docs/app/examples/next-optimistic-profile-update/page.tsx
@@ -0,0 +1,46 @@
+import { ExampleShell } from "../_components/example-shell";
+
+export default function NextOptimisticProfileUpdatePage() {
+  return (
+    <ExampleShell
+      title="Next Optimistic Profile Update"
+      subtitle="Single-entity optimistic mutation with automatic rollback on server failure."
+      impact="Alto"
+      differential="No manual useOptimistic orchestration or rollback bookkeeping."
+      message="UX instantanea com rollback seguro em poucas linhas."
+    >
+      <div className="code-block text-gray-300 mb-8">
+        <pre>{`type Profile = { id: string; name: string; title: string };
+
+const form = useActionForm(updateProfileAction, {
+  defaultValues: { name: profile.name, title: profile.title },
+  optimisticInitial: profile,
+  optimisticData: (current: Profile, values) => ({
+    ...current,
+    ...values,
+  }),
+});
+
+const view = form.optimistic?.data ?? profile;
+
+return (
+  <form onSubmit={form.handleSubmit()}>
+    <h2>{view.name}</h2>
+    <p>{view.title}</p>
+    <input {...form.register("name")} />
+    <input {...form.register("title")} />
+    <button disabled={form.formState.isPending}>Save</button>
+  </form>
+);`}</pre>
+      </div>
+
+      <p className="text-sm text-gray-500">
+        Want a live list scenario? Open{" "}
+        <a className="text-brand-300 hover:text-brand-200" href="/examples/next-optimistic-list-rollback">
+          Next Optimistic List Rollback
+        </a>
+        .
+      </p>
+    </ExampleShell>
+  );
+}
diff --git a/apps/docs/app/examples/next-quickstart-login/page.tsx b/apps/docs/app/examples/next-quickstart-login/page.tsx
new file mode 100644
index 0000000..c070b31
--- /dev/null
+++ b/apps/docs/app/examples/next-quickstart-login/page.tsx
@@ -0,0 +1,39 @@
+import { LoginForm } from "../login/login-form";
+import { ExampleShell } from "../_components/example-shell";
+
+export const dynamic = "force-dynamic";
+
+export default function NextQuickstartLoginPage() {
+  return (
+    <ExampleShell
+      title="Next Quickstart Login"
+      subtitle="RHF + Server Action + automatic error mapping in a single flow."
+      impact="Muito alto"
+      differential="First-value path for Next.js users."
+      message="Conecte RHF ao servidor sem boilerplate manual."
+    >
+      <div className="bg-gray-900/50 border border-gray-800 rounded-xl p-8 mb-10">
+        <LoginForm />
+      </div>
+
+      <h2 className="text-xl font-semibold mb-3">Why this sells the library</h2>
+      <p className="text-gray-400 mb-6">
+        This is the shortest path from install to success. It proves pending state, server validation,
+        and field-level error mapping in one place.
+      </p>
+
+      <div className="code-block text-gray-300">
+        <pre>{`const form = useActionForm(loginAction, {
+  defaultValues: { email: "", password: "" },
+});
+
+<form onSubmit={form.handleSubmit()}>
+  <input {...form.register("email")} />
+  <input {...form.register("password")} type="password" />
+  <button disabled={form.formState.isSubmitting}>Sign In</button>
+</form>`}</pre>
+      </div>
+    </ExampleShell>
+  );
+}
+
diff --git a/apps/docs/app/examples/next-schema-once-signup/page.tsx b/apps/docs/app/examples/next-schema-once-signup/page.tsx
new file mode 100644
index 0000000..f3f82f3
--- /dev/null
+++ b/apps/docs/app/examples/next-schema-once-signup/page.tsx
@@ -0,0 +1,32 @@
+import { ExampleShell } from "../_components/example-shell";
+import { ValidationForm } from "../validation/validation-form";
+
+export const dynamic = "force-dynamic";
+
+export default function NextSchemaOnceSignupPage() {
+  return (
+    <ExampleShell
+      title="Next Schema Once Signup"
+      subtitle="Use withZod once and let the hook infer validation + types across client and server."
+      impact="Alto"
+      differential="Single schema lifecycle with no duplicated contract."
+      message="Schema unica, validação em ambos os lados."
+    >
+      <div className="bg-gray-900/50 border border-gray-800 rounded-xl p-8 mb-10">
+        <ValidationForm />
+      </div>
+
+      <div className="code-block text-gray-300">
+        <pre>{`export const signupAction = withZod(signupSchema, async (data) => {
+  // data is inferred from schema
+  return await createUser(data);
+});
+
+const form = useActionForm(signupAction, {
+  defaultValues: { username: "", email: "", password: "" },
+  validationMode: "onChange",
+});`}</pre>
+      </div>
+    </ExampleShell>
+  );
+}
diff --git a/apps/docs/app/examples/next-wizard-onboarding-persist/page.tsx b/apps/docs/app/examples/next-wizard-onboarding-persist/page.tsx
new file mode 100644
index 0000000..fc0f529
--- /dev/null
+++ b/apps/docs/app/examples/next-wizard-onboarding-persist/page.tsx
@@ -0,0 +1,37 @@
+import { ExampleShell } from "../_components/example-shell";
+import { WizardForm } from "../wizard/wizard-form";
+
+export const dynamic = "force-dynamic";
+
+export default function NextWizardOnboardingPersistPage() {
+  return (
+    <ExampleShell
+      title="Next Wizard Onboarding Persist"
+      subtitle="Multi-step onboarding with persisted progress and step-level validation."
+      impact="Alto"
+      differential="Built-in persistence and restore behavior for wizard UX."
+      message="Usuario retoma o fluxo sem perder dados."
+    >
+      <div className="bg-gray-900/50 border border-gray-800 rounded-xl p-8 mb-10">
+        <WizardForm />
+      </div>
+
+      <div className="code-block text-gray-300">
+        <pre>{`const form = useActionForm(wizardAction, {
+  defaultValues: {
+    firstName: "",
+    lastName: "",
+    email: "",
+    company: "",
+    role: "",
+    plan: "",
+    agreeToTerms: "",
+  },
+  persistKey: "wizard-onboarding",
+  persistDebounce: 200,
+});`}</pre>
+      </div>
+    </ExampleShell>
+  );
+}
+
diff --git a/apps/docs/app/examples/optimistic/optimistic-todo-form.tsx b/apps/docs/app/examples/optimistic/optimistic-todo-form.tsx
index a1273c2..7d149d8 100644
--- a/apps/docs/app/examples/optimistic/optimistic-todo-form.tsx
+++ b/apps/docs/app/examples/optimistic/optimistic-todo-form.tsx
@@ -1,20 +1,20 @@
-'use client'
+"use client";
 
-import { useActionForm } from 'hookform-action'
-import { type Todo, addTodoAction } from './actions'
+import { useActionForm } from "hookform-action";
+import { type Todo, addTodoAction } from "./actions";
 
 const initialTodos: Todo[] = [
-  { id: '1', text: 'Read hookform-action docs', done: true },
-  { id: '2', text: 'Upgrade to React 19', done: false },
-  { id: '3', text: 'Add optimistic UI to my app', done: false },
-]
+  { id: "1", text: "Read hookform-action docs", done: true },
+  { id: "2", text: "Upgrade to React 19", done: false },
+  { id: "3", text: "Add optimistic UI to my app", done: false },
+];
 
 type AddTodoResult = {
-  todos: Todo[]
+  todos: Todo[];
   errors?: {
-    text?: string[]
-  }
-}
+    text?: string[];
+  };
+};
 
 export function OptimisticTodoForm() {
   const {
@@ -24,17 +24,16 @@ export function OptimisticTodoForm() {
     formState: { errors, isPending, actionResult },
     optimistic,
   } = useActionForm<{ text: string }, AddTodoResult, Todo[]>(addTodoAction, {
-    defaultValues: { text: '' },
-    optimisticKey: 'todos',
+    defaultValues: { text: "" },
     optimisticInitial: initialTodos,
     optimisticData: (current: Todo[], values) => [
       ...current,
       { id: `temp-${Date.now()}`, text: values.text, done: false },
     ],
-  })
+  });
 
-  const confirmedTodos = actionResult?.todos ?? initialTodos
-  const todos = optimistic?.isPending ? (optimistic.data ?? confirmedTodos) : confirmedTodos
+  const confirmedTodos = actionResult?.todos ?? initialTodos;
+  const todos = optimistic?.isPending ? optimistic.data ?? confirmedTodos : confirmedTodos;
 
   return (
     <div className="space-y-6">
@@ -43,24 +42,20 @@ export function OptimisticTodoForm() {
           <div
             key={todo.id}
             className={`flex items-center gap-3 px-4 py-3 rounded-lg border transition-all ${
-              todo.id.startsWith('temp-')
-                ? 'border-brand-500/50 bg-brand-500/10 animate-pulse'
-                : 'border-gray-700 bg-gray-900/50'
+              todo.id.startsWith("temp-")
+                ? "border-brand-500/50 bg-brand-500/10 animate-pulse"
+                : "border-gray-700 bg-gray-900/50"
             }`}
           >
-            <span className={`text-lg ${todo.done ? 'opacity-50' : ''}`}>
-              {todo.done ? '✅' : '⬜'}
-            </span>
+            <span className={`text-lg ${todo.done ? "opacity-50" : ""}`}>{todo.done ? "✅" : "⬜"}</span>
             <span
-              className={`flex-1 ${todo.done ? 'line-through text-gray-500' : 'text-gray-200'} ${
-                todo.id.startsWith('temp-') ? 'text-brand-300 italic' : ''
+              className={`flex-1 ${todo.done ? "line-through text-gray-500" : "text-gray-200"} ${
+                todo.id.startsWith("temp-") ? "text-brand-300 italic" : ""
               }`}
             >
               {todo.text}
             </span>
-            {todo.id.startsWith('temp-') && (
-              <span className="text-xs text-brand-400 font-medium">saving...</span>
-            )}
+            {todo.id.startsWith("temp-") && <span className="text-xs text-brand-400 font-medium">saving...</span>}
           </div>
         ))}
       </div>
@@ -68,20 +63,8 @@ export function OptimisticTodoForm() {
       {optimistic?.isPending && (
         <div className="text-xs text-brand-400 flex items-center gap-2">
           <svg className="animate-spin h-3 w-3" viewBox="0 0 24 24" aria-hidden="true">
-            <circle
-              className="opacity-25"
-              cx="12"
-              cy="12"
-              r="10"
-              stroke="currentColor"
-              strokeWidth="4"
-              fill="none"
-            />
-            <path
-              className="opacity-75"
-              fill="currentColor"
-              d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
-            />
+            <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" fill="none" />
+            <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
           </svg>
           Syncing with server...
         </div>
@@ -89,7 +72,7 @@ export function OptimisticTodoForm() {
 
       <form
         onSubmit={handleSubmit(() => {
-          reset({ text: '' })
+          reset({ text: "" });
         })}
         className="flex gap-3"
       >
@@ -97,7 +80,7 @@ export function OptimisticTodoForm() {
           <input
             placeholder="Add a new todo..."
             className="w-full px-4 py-2.5 bg-gray-900 border border-gray-700 rounded-lg text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-brand-500 focus:border-transparent transition-colors"
-            {...register('text')}
+            {...register("text")}
           />
           {errors.text && <p className="mt-1 text-sm text-red-400">{errors.text.message}</p>}
         </div>
@@ -106,9 +89,9 @@ export function OptimisticTodoForm() {
           disabled={isPending}
           className="px-6 py-2.5 bg-brand-600 hover:bg-brand-500 disabled:bg-gray-700 disabled:cursor-not-allowed text-white rounded-lg font-medium transition-colors whitespace-nowrap"
         >
-          {isPending ? 'Adding...' : 'Add Todo'}
+          {isPending ? "Adding..." : "Add Todo"}
         </button>
       </form>
     </div>
-  )
+  );
 }
diff --git a/apps/docs/app/examples/optimistic/page.tsx b/apps/docs/app/examples/optimistic/page.tsx
index 89b1d05..4a5753a 100644
--- a/apps/docs/app/examples/optimistic/page.tsx
+++ b/apps/docs/app/examples/optimistic/page.tsx
@@ -14,7 +14,7 @@ export default function OptimisticExamplePage() {
       <div className="flex items-center gap-3 mb-2">
         <h1 className="text-3xl font-bold">Optimistic UI Example</h1>
         <span className="text-xs font-medium bg-cyan-500/20 text-cyan-400 px-2 py-0.5 rounded-full">
-          v2
+          v4
         </span>
       </div>
       <p className="text-gray-400 mb-8">
@@ -77,7 +77,7 @@ export function OptimisticTodoForm() {
   } = useActionForm(addTodoAction, {
     defaultValues: { text: '' },
 
-    // ✨ v2 Optimistic UI
+    // ✨ v4 Optimistic UI
     optimisticKey: 'todos',
     optimisticInitial: initialTodos,
     optimisticData: (current: Todo[], values) => [
diff --git a/apps/docs/app/examples/page.tsx b/apps/docs/app/examples/page.tsx
new file mode 100644
index 0000000..1fba285
--- /dev/null
+++ b/apps/docs/app/examples/page.tsx
@@ -0,0 +1,113 @@
+import { strategicExamples, topAdoptionSlugs } from './catalog'
+
+function ImpactBadge({ impact }: { impact: string }) {
+  const color =
+    impact === 'Muito alto'
+      ? 'text-emerald-300 border-emerald-500/30 bg-emerald-500/10'
+      : impact === 'Alto'
+        ? 'text-cyan-300 border-cyan-500/30 bg-cyan-500/10'
+        : 'text-gray-300 border-gray-700 bg-gray-800/70'
+  return <span className={`text-xs border rounded-full px-2 py-0.5 ${color}`}>{impact}</span>
+}
+
+export default function ExamplesPage() {
+  const topAdoption = strategicExamples.filter((item) => topAdoptionSlugs.has(item.slug))
+  const fullCatalog = [...strategicExamples].sort((a, b) => a.order - b.order)
+
+  return (
+    <div className="max-w-5xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to docs
+        </a>
+      </div>
+
+      <header className="mb-10">
+        <div className="inline-flex items-center gap-2 bg-brand-500/10 text-brand-400 border border-brand-500/20 rounded-full px-4 py-1.5 text-sm font-medium mb-4">
+          <span>Examples Hub</span>
+        </div>
+        <h1 className="text-3xl font-bold mb-3">Examples that drive adoption</h1>
+        <p className="text-gray-400 max-w-3xl">
+          Start with the top adoption examples first. Then use the full catalog for deeper
+          migration, adapter parity, optimistic flows, and debugging strategies.
+        </p>
+      </header>
+
+      <section className="mb-12">
+        <h2 className="text-xl font-semibold mb-4 text-emerald-300">Top adoption path</h2>
+        <div className="grid sm:grid-cols-2 gap-4">
+          {topAdoption.map((item) => (
+            <a
+              key={item.slug}
+              href={`/examples/${item.slug}`}
+              className="group block bg-gray-900/50 border border-gray-800 hover:border-emerald-500/40 rounded-xl p-5 transition-colors"
+            >
+              <div className="flex items-center justify-between gap-3 mb-2">
+                <h3 className="font-semibold text-white group-hover:text-emerald-300 transition-colors">
+                  {item.title}
+                </h3>
+                <ImpactBadge impact={item.impact} />
+              </div>
+              <p className="text-sm text-gray-400 mb-2">{item.differential}</p>
+              <p className="text-sm text-gray-300">{item.message}</p>
+            </a>
+          ))}
+        </div>
+      </section>
+
+      <section className="mb-10">
+        <h2 className="text-xl font-semibold mb-4">Full example catalog</h2>
+        <div className="overflow-x-auto border border-gray-800 rounded-xl">
+          <table className="w-full text-sm text-left">
+            <thead className="text-gray-400 border-b border-gray-800 bg-gray-900/40">
+              <tr>
+                <th className="py-3 px-4 w-14">#</th>
+                <th className="py-3 px-4 min-w-[240px]">Example</th>
+                <th className="py-3 px-4 min-w-[120px]">Adapter</th>
+                <th className="py-3 px-4 min-w-[110px]">Format</th>
+                <th className="py-3 px-4 min-w-[360px]">Differential</th>
+              </tr>
+            </thead>
+            <tbody className="text-gray-300">
+              {fullCatalog.map((item) => (
+                <tr key={item.slug} className="border-b border-gray-800/60">
+                  <td className="py-3 px-4 text-gray-500">{item.order}</td>
+                  <td className="py-3 px-4">
+                    <a
+                      href={`/examples/${item.slug}`}
+                      className="text-brand-300 hover:text-brand-200 transition-colors"
+                    >
+                      {item.title}
+                    </a>
+                  </td>
+                  <td className="py-3 px-4 text-gray-400">{item.adapter}</td>
+                  <td className="py-3 px-4 text-gray-400">{item.format}</td>
+                  <td className="py-3 px-4 text-gray-400">{item.differential}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </section>
+
+      <section className="border border-gray-800 rounded-xl p-6 bg-gray-900/30">
+        <h2 className="text-lg font-semibold mb-2">Need deeper implementation guidance?</h2>
+        <p className="text-sm text-gray-400 mb-4">
+          Recipes cover concrete production patterns. FAQ and Troubleshooting cover support-heavy
+          operational issues.
+        </p>
+        <div className="flex items-center gap-4 text-sm">
+          <a href="/recipes" className="text-brand-400 hover:text-brand-300 transition-colors">
+            Recipes →
+          </a>
+          <a href="/faq" className="text-gray-300 hover:text-white transition-colors">
+            FAQ →
+          </a>
+          <a href="/troubleshooting" className="text-gray-300 hover:text-white transition-colors">
+            Troubleshooting →
+          </a>
+        </div>
+      </section>
+    </div>
+  )
+}
diff --git a/apps/docs/app/examples/standalone-quickstart-login/page.tsx b/apps/docs/app/examples/standalone-quickstart-login/page.tsx
new file mode 100644
index 0000000..b3dbd62
--- /dev/null
+++ b/apps/docs/app/examples/standalone-quickstart-login/page.tsx
@@ -0,0 +1,56 @@
+import { ExampleShell } from "../_components/example-shell";
+
+export default function StandaloneQuickstartLoginPage() {
+  return (
+    <ExampleShell
+      title="Standalone Quickstart Login"
+      subtitle="Same mental model as Next adapter, but with an explicit submit function."
+      impact="Muito alto"
+      differential="Fast proof that hookform-action is not Next-only."
+      message="Troque para submit() e mantenha a mesma DX."
+    >
+      <h2 className="text-xl font-semibold mb-3">Recipe</h2>
+      <p className="text-gray-400 mb-6">
+        This example is intentionally copy-paste ready for Vite, Remix, Astro, or any React SPA.
+      </p>
+
+      <div className="code-block text-gray-300 mb-8">
+        <pre>{`import { useActionForm } from "hookform-action-standalone";
+import { z } from "zod";
+
+const schema = z.object({
+  email: z.string().email("Invalid email"),
+  password: z.string().min(8, "Min 8 chars"),
+});
+
+export function LoginForm() {
+  const form = useActionForm({
+    submit: async (values) => {
+      const res = await fetch("/api/login", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(values),
+      });
+      return res.json();
+    },
+    schema,
+    validationMode: "onChange",
+    defaultValues: { email: "", password: "" },
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit()}>
+      <input {...form.register("email")} />
+      <input type="password" {...form.register("password")} />
+      <button disabled={form.formState.isPending}>Sign In</button>
+    </form>
+  );
+}`}</pre>
+      </div>
+
+      <p className="text-sm text-gray-500">
+        Strategic point: this removes framework lock-in objections during evaluation.
+      </p>
+    </ExampleShell>
+  );
+}
diff --git a/apps/docs/app/examples/standalone-rest-error-mapper/page.tsx b/apps/docs/app/examples/standalone-rest-error-mapper/page.tsx
new file mode 100644
index 0000000..fb008fd
--- /dev/null
+++ b/apps/docs/app/examples/standalone-rest-error-mapper/page.tsx
@@ -0,0 +1,40 @@
+import { ExampleShell } from "../_components/example-shell";
+
+export default function StandaloneRestErrorMapperPage() {
+  return (
+    <ExampleShell
+      title="Standalone REST Error Mapper"
+      subtitle="Map arbitrary backend error envelopes to RHF field errors with one option."
+      impact="Alto"
+      differential="Integrates with legacy API contracts without backend refactors."
+      message="Adapte erro legado para RHF sem reescrever a API."
+    >
+      <div className="code-block text-gray-300 mb-8">
+        <pre>{`type ApiError = {
+  ok: false;
+  errors: Array<{ field: string; message: string }>;
+};
+
+const form = useActionForm({
+  submit: async (values) => {
+    const res = await fetch("/api/users", {
+      method: "POST",
+      body: JSON.stringify(values),
+    });
+    return res.json() as Promise<ApiError | { ok: true }>;
+  },
+  defaultValues: { name: "", email: "" },
+  errorMapper: (result) => {
+    if (!result || result.ok !== false) return {};
+    return Object.fromEntries(result.errors.map((item) => [item.field, [item.message]]));
+  },
+});`}</pre>
+      </div>
+
+      <p className="text-sm text-gray-500">
+        Strategic point: this removes one of the most common adoption blockers in enterprise apps.
+      </p>
+    </ExampleShell>
+  );
+}
+
diff --git a/apps/docs/app/examples/validation/page.tsx b/apps/docs/app/examples/validation/page.tsx
index 8393957..56df9a6 100644
--- a/apps/docs/app/examples/validation/page.tsx
+++ b/apps/docs/app/examples/validation/page.tsx
@@ -14,7 +14,7 @@ export default function ValidationExamplePage() {
       <div className="flex items-center gap-3 mb-2">
         <h1 className="text-3xl font-bold">Client-Side Validation Example</h1>
         <span className="text-xs font-medium bg-cyan-500/20 text-cyan-400 px-2 py-0.5 rounded-full">
-          v2
+          v4
         </span>
       </div>
       <p className="text-gray-400 mb-8">
diff --git a/apps/docs/app/examples/validation/validation-form.tsx b/apps/docs/app/examples/validation/validation-form.tsx
index c7ed005..8eb5e84 100644
--- a/apps/docs/app/examples/validation/validation-form.tsx
+++ b/apps/docs/app/examples/validation/validation-form.tsx
@@ -1,8 +1,8 @@
-'use client'
+"use client";
 
-import { useActionForm } from 'hookform-action'
-import { signupAction } from './actions'
-import { signupSchema } from './schema'
+import { useActionForm } from "hookform-action";
+import { signupAction } from "./actions";
+import { signupSchema } from "./schema";
 
 export function ValidationForm() {
   const {
@@ -10,11 +10,11 @@ export function ValidationForm() {
     handleSubmit,
     formState: { errors, isPending, isSubmitSuccessful },
   } = useActionForm(signupAction, {
-    defaultValues: { username: '', email: '', password: '' },
+    defaultValues: { username: "", email: "", password: "" },
     // Pass the schema for client-side validation on every change
     schema: signupSchema,
-    validationMode: 'onChange',
-  })
+    validationMode: "onChange",
+  });
 
   if (isSubmitSuccessful) {
     return (
@@ -24,7 +24,7 @@ export function ValidationForm() {
           Client-side validation passed, then the server action ran successfully.
         </p>
       </div>
-    )
+    );
   }
 
   return (
@@ -38,19 +38,13 @@ export function ValidationForm() {
           type="text"
           placeholder="my_username"
           className={`w-full px-4 py-2.5 bg-gray-900 border rounded-lg text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:border-transparent transition-colors ${
-            errors.username
-              ? 'border-red-500 focus:ring-red-500'
-              : 'border-gray-700 focus:ring-brand-500'
+            errors.username ? "border-red-500 focus:ring-red-500" : "border-gray-700 focus:ring-brand-500"
           }`}
-          {...register('username')}
+          {...register("username")}
         />
-        {errors.username && (
-          <p className="mt-1.5 text-sm text-red-400">{errors.username.message}</p>
-        )}
+        {errors.username && <p className="mt-1.5 text-sm text-red-400">{errors.username.message}</p>}
         {!errors.username && (
-          <p className="mt-1.5 text-xs text-gray-500">
-            3–20 characters, letters, numbers, underscores
-          </p>
+          <p className="mt-1.5 text-xs text-gray-500">3–20 characters, letters, numbers, underscores</p>
         )}
       </div>
 
@@ -63,11 +57,9 @@ export function ValidationForm() {
           type="email"
           placeholder="you@example.com"
           className={`w-full px-4 py-2.5 bg-gray-900 border rounded-lg text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:border-transparent transition-colors ${
-            errors.email
-              ? 'border-red-500 focus:ring-red-500'
-              : 'border-gray-700 focus:ring-brand-500'
+            errors.email ? "border-red-500 focus:ring-red-500" : "border-gray-700 focus:ring-brand-500"
           }`}
-          {...register('email')}
+          {...register("email")}
         />
         {errors.email && <p className="mt-1.5 text-sm text-red-400">{errors.email.message}</p>}
       </div>
@@ -81,18 +73,12 @@ export function ValidationForm() {
           type="password"
           placeholder="••••••••"
           className={`w-full px-4 py-2.5 bg-gray-900 border rounded-lg text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:border-transparent transition-colors ${
-            errors.password
-              ? 'border-red-500 focus:ring-red-500'
-              : 'border-gray-700 focus:ring-brand-500'
+            errors.password ? "border-red-500 focus:ring-red-500" : "border-gray-700 focus:ring-brand-500"
           }`}
-          {...register('password')}
+          {...register("password")}
         />
-        {errors.password && (
-          <p className="mt-1.5 text-sm text-red-400">{errors.password.message}</p>
-        )}
-        {!errors.password && (
-          <p className="mt-1.5 text-xs text-gray-500">8+ characters, one uppercase, one number</p>
-        )}
+        {errors.password && <p className="mt-1.5 text-sm text-red-400">{errors.password.message}</p>}
+        {!errors.password && <p className="mt-1.5 text-xs text-gray-500">8+ characters, one uppercase, one number</p>}
       </div>
 
       <button
@@ -103,33 +89,21 @@ export function ValidationForm() {
         {isPending ? (
           <span className="inline-flex items-center gap-2">
             <svg className="animate-spin h-4 w-4" viewBox="0 0 24 24" aria-hidden="true">
-              <circle
-                className="opacity-25"
-                cx="12"
-                cy="12"
-                r="10"
-                stroke="currentColor"
-                strokeWidth="4"
-                fill="none"
-              />
-              <path
-                className="opacity-75"
-                fill="currentColor"
-                d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
-              />
+              <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" fill="none" />
+              <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
             </svg>
             Creating account...
           </span>
         ) : (
-          'Create Account'
+          "Create Account"
         )}
       </button>
 
       <p className="text-xs text-gray-500 text-center">
-        Try <code className="text-gray-400">admin</code> as username or{' '}
-        <code className="text-gray-400">taken@example.com</code> as email to see server-side errors
-        (after client validation passes).
+        Try <code className="text-gray-400">admin</code> as username or{" "}
+        <code className="text-gray-400">taken@example.com</code> as email to see server-side errors (after client
+        validation passes).
       </p>
     </form>
-  )
+  );
 }
diff --git a/apps/docs/app/examples/wizard/page.tsx b/apps/docs/app/examples/wizard/page.tsx
index ff108ca..36038b4 100644
--- a/apps/docs/app/examples/wizard/page.tsx
+++ b/apps/docs/app/examples/wizard/page.tsx
@@ -52,7 +52,7 @@ export default function WizardExamplePage() {
           <pre>{`const {
   register,
   handleSubmit,
-  formState: { errors, isSubmitting },
+  formState: { errors, isPending },
   trigger,
 } = useActionForm(wizardAction, {
   defaultValues: {
diff --git a/apps/docs/app/examples/wizard/wizard-form.tsx b/apps/docs/app/examples/wizard/wizard-form.tsx
index a26a499..6aa11a3 100644
--- a/apps/docs/app/examples/wizard/wizard-form.tsx
+++ b/apps/docs/app/examples/wizard/wizard-form.tsx
@@ -12,7 +12,7 @@ export function WizardForm() {
   const {
     register,
     handleSubmit,
-    formState: { errors, isSubmitting, isSubmitSuccessful },
+    formState: { errors, isPending, isSubmitSuccessful },
     trigger,
     watch,
   } = useActionForm(wizardAction, {
@@ -215,10 +215,10 @@ export function WizardForm() {
           ) : (
             <button
               type="submit"
-              disabled={isSubmitting}
+              disabled={isPending}
               className="px-5 py-2.5 bg-green-600 hover:bg-green-500 disabled:bg-gray-700 disabled:cursor-not-allowed text-white rounded-lg font-medium transition-colors"
             >
-              {isSubmitting ? (
+              {isPending ? (
                 <span className="inline-flex items-center gap-2">
                   <svg className="animate-spin h-4 w-4" viewBox="0 0 24 24" aria-hidden="true">
                     <circle
diff --git a/apps/docs/app/faq/page.tsx b/apps/docs/app/faq/page.tsx
new file mode 100644
index 0000000..70d6628
--- /dev/null
+++ b/apps/docs/app/faq/page.tsx
@@ -0,0 +1,146 @@
+type FaqItem = {
+  question: string
+  answer: string
+  category:
+    | 'Setup'
+    | 'Validation'
+    | 'Errors'
+    | 'State'
+    | 'Persistence'
+    | 'Optimistic'
+    | 'Standalone'
+}
+
+const faqItems: FaqItem[] = [
+  {
+    question: 'Which package should I install: hookform-action, standalone, or core?',
+    answer:
+      'Use hookform-action for Next.js Server Actions. Use hookform-action-standalone for Vite/Remix/Astro/SPA apps. Use core only for custom adapters.',
+    category: 'Setup',
+  },
+  {
+    question: 'Is withZod required?',
+    answer:
+      'No. It is optional but recommended. It gives typed server validation, a standard error shape, and schema auto-detection in useActionForm.',
+    category: 'Validation',
+  },
+  {
+    question: 'If I already use withZod, do I still need schema in useActionForm?',
+    answer:
+      'Usually no. The schema is auto-detected. Pass schema only when you want to override behavior explicitly.',
+    category: 'Validation',
+  },
+  {
+    question: 'What is the default error contract?',
+    answer:
+      'Return errors as { errors: Record<string, string[]> } so field mapping works out of the box.',
+    category: 'Errors',
+  },
+  {
+    question: 'What is the difference between mode and validationMode?',
+    answer:
+      'mode is the native React Hook Form validation strategy. validationMode controls when hookform-action runs client-side schema validation.',
+    category: 'Validation',
+  },
+  {
+    question: 'Should submit buttons use isPending or isSubmitting?',
+    answer:
+      'Prefer isPending for UI state during the full server round-trip. isSubmitting can be narrower depending on the flow.',
+    category: 'State',
+  },
+  {
+    question: 'What is the difference between formState.errors and formState.submitErrors?',
+    answer:
+      'errors is RHF-ready data for rendering. submitErrors is the raw error record returned by your action.',
+    category: 'Errors',
+  },
+  {
+    question: 'Why are old values restored when the form mounts?',
+    answer:
+      'If persistKey is set, persisted data takes precedence over defaultValues. Use scoped keys and clear persisted drafts when needed.',
+    category: 'Persistence',
+  },
+  {
+    question: 'When is persisted state cleared automatically?',
+    answer:
+      'Persisted data is cleared on successful submission. Failed submissions keep the draft for recovery.',
+    category: 'Persistence',
+  },
+  {
+    question: 'Why is optimistic undefined?',
+    answer:
+      'You need optimisticKey and optimisticData. optimisticInitial is recommended for predictable first render behavior.',
+    category: 'Optimistic',
+  },
+  {
+    question: 'Does optimistic rollback happen automatically?',
+    answer:
+      'Yes. Rollback runs on mapped action errors and thrown exceptions. Manual rollback() is also available.',
+    category: 'Optimistic',
+  },
+  {
+    question: 'Does standalone provide formAction too?',
+    answer:
+      'No. In standalone mode, you pass submit and call handleSubmit(). formAction is Next.js adapter specific.',
+    category: 'Standalone',
+  },
+]
+
+export default function FaqPage() {
+  return (
+    <div className="max-w-5xl mx-auto px-6 py-16">
+      <div className="mb-8 flex items-center justify-between gap-4 flex-wrap">
+        <a href="/" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to docs
+        </a>
+        <div className="flex items-center gap-4 text-sm">
+          <a
+            href="/troubleshooting"
+            className="text-cyan-400 hover:text-cyan-300 transition-colors"
+          >
+            Troubleshooting →
+          </a>
+          <a href="/recipes" className="text-brand-400 hover:text-brand-300 transition-colors">
+            Recipes →
+          </a>
+        </div>
+      </div>
+
+      <header className="mb-10">
+        <h1 className="text-3xl font-bold mb-3">FAQ</h1>
+        <p className="text-gray-400 max-w-3xl">
+          Short answers for the most frequent adoption questions. If your issue is symptom-based, go
+          straight to Troubleshooting.
+        </p>
+      </header>
+
+      <section className="space-y-3 mb-10">
+        {faqItems.map((item) => (
+          <div key={item.question} className="border border-gray-800 rounded-xl p-5 bg-gray-900/30">
+            <div className="flex items-center justify-between gap-3 mb-2">
+              <h2 className="text-base font-semibold text-white">{item.question}</h2>
+              <span className="text-xs text-gray-400 border border-gray-700 rounded-full px-2 py-0.5">
+                {item.category}
+              </span>
+            </div>
+            <p className="text-sm text-gray-400">{item.answer}</p>
+          </div>
+        ))}
+      </section>
+
+      <section className="border border-gray-800 rounded-xl p-6 bg-gradient-to-br from-brand-500/10 to-cyan-500/10">
+        <h2 className="text-lg font-semibold mb-2">Still blocked?</h2>
+        <p className="text-sm text-gray-300 mb-4">
+          Use the troubleshooting checklist to debug by symptom: submit not firing, field errors not
+          showing, stale persisted values, optimistic rollback issues, and upload edge cases.
+        </p>
+        <a
+          href="/troubleshooting"
+          className="text-cyan-300 hover:text-cyan-200 transition-colors text-sm"
+        >
+          Open Troubleshooting →
+        </a>
+      </section>
+    </div>
+  )
+}
diff --git a/apps/docs/app/layout.tsx b/apps/docs/app/layout.tsx
index 8e7ec86..76d0537 100644
--- a/apps/docs/app/layout.tsx
+++ b/apps/docs/app/layout.tsx
@@ -2,48 +2,74 @@ import type { Metadata } from 'next'
 import './globals.css'
 
 export const metadata: Metadata = {
-  title: 'hookform-action – Docs',
+  title: 'hookform-action - Docs',
   description:
-    'Seamless integration between React Hook Form and Next.js Server Actions with Zod validation and multi-step persistence.',
+    'React Hook Form + server submit flows with type-safe actions, Zod mapping, optimistic UI, persistence, and adapters for Next.js or standalone React apps.',
 }
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <html lang="en" className="dark">
       <body className="min-h-screen">
-        <nav className="border-b border-gray-800 bg-gray-950/80 backdrop-blur-sm sticky top-0 z-50">
-          <div className="max-w-6xl mx-auto px-6 h-16 flex items-center justify-between">
-            <a href="/" className="flex items-center gap-2 font-bold text-lg">
-              <span className="text-brand-400">⚡</span>
-              <span>hookform-action</span>
-            </a>
-            <div className="flex items-center gap-6 text-sm text-gray-400">
-              <a href="/examples/login" className="hover:text-white transition-colors">
-                Login
+        <nav className="sticky top-0 z-50 border-b border-gray-800 bg-gray-950/85 backdrop-blur-sm">
+          <div className="mx-auto max-w-6xl px-4 py-3 sm:px-6">
+            <div className="mb-2 flex items-center justify-between">
+              <a href="/" className="flex items-center gap-2 text-lg font-bold">
+                <span className="text-brand-400">⚡</span>
+                <span>hookform-action</span>
               </a>
-              <a href="/examples/wizard" className="hover:text-white transition-colors">
-                Wizard
+              <span className="rounded-full border border-brand-500/20 bg-brand-500/10 px-2.5 py-1 text-xs font-medium text-brand-300">
+                v4
+              </span>
+            </div>
+
+            <div className="flex items-center gap-5 overflow-x-auto whitespace-nowrap pb-1 text-sm text-gray-400">
+              <a
+                href="/examples/next-quickstart-login"
+                className="transition-colors hover:text-white"
+              >
+                Quick Start
+              </a>
+              <a href="/examples" className="transition-colors hover:text-white">
+                Examples
+              </a>
+              <a href="/recipes" className="transition-colors hover:text-white">
+                Recipes
+              </a>
+              <a href="/faq" className="transition-colors hover:text-white">
+                FAQ
               </a>
-              <a href="/examples/optimistic" className="hover:text-white transition-colors">
-                <span className="text-cyan-400">⚡</span> Optimistic
+              <a href="/troubleshooting" className="transition-colors hover:text-white">
+                Troubleshooting
               </a>
-              <a href="/examples/validation" className="hover:text-white transition-colors">
-                <span className="text-cyan-400">⚡</span> Validation
+              <a href="/standalone" className="transition-colors hover:text-white">
+                Standalone
               </a>
-              <a href="/standalone" className="hover:text-white transition-colors">
-                <span className="text-emerald-400">🚀</span> Standalone
+              <a
+                href="/examples/devtools-debug-submission-history"
+                className="transition-colors hover:text-white"
+              >
+                DevTools
               </a>
-              <a href="/devtools" className="hover:text-white transition-colors">
-                <span className="text-purple-400">🔍</span> DevTools
+              <a href="/api-reference" className="transition-colors hover:text-white">
+                API
               </a>
-              <a href="/api-reference" className="hover:text-white transition-colors">
-                API Reference
+              <a href="/why" className="transition-colors hover:text-white">
+                Why
+              </a>
+              <a
+                href="https://github.com/gabpaesschulz/hookform-action/blob/main/packages/next/CHANGELOG.md"
+                target="_blank"
+                rel="noreferrer noopener"
+                className="transition-colors hover:text-white"
+              >
+                Changelog
               </a>
               <a
                 href="https://github.com/gabpaesschulz/hookform-action"
                 target="_blank"
                 rel="noreferrer noopener"
-                className="hover:text-white transition-colors"
+                className="transition-colors hover:text-white"
               >
                 GitHub
               </a>
diff --git a/apps/docs/app/page.tsx b/apps/docs/app/page.tsx
index 45d8653..e85da96 100644
--- a/apps/docs/app/page.tsx
+++ b/apps/docs/app/page.tsx
@@ -1,296 +1,580 @@
+const comparisonRows = [
+  {
+    concern: 'Type safety from schema to submit handler',
+    manual: 'Manual casting and duplicated generic types',
+    withHookformAction: 'Inference from withZod schema to useActionForm',
+  },
+  {
+    concern: 'Server validation errors to RHF fields',
+    manual: 'Parse fieldErrors and loop setError() per field',
+    withHookformAction: 'Automatic mapping through default error mapper',
+  },
+  {
+    concern: 'Pending submit state',
+    manual: 'Wire useTransition separately from RHF formState',
+    withHookformAction: 'formState.isPending available in the hook result',
+  },
+  {
+    concern: 'Optimistic UI with rollback',
+    manual: 'Build custom useOptimistic wiring per form',
+    withHookformAction: 'Enable optimisticData and optimisticKey options',
+  },
+  {
+    concern: 'Multi-step persistence',
+    manual: 'Custom sessionStorage effects and debounce logic',
+    withHookformAction: 'Built-in persistKey and persistDebounce options',
+  },
+  {
+    concern: 'Cross-framework submit flow',
+    manual: 'Rewrite integration for each stack',
+    withHookformAction: 'Same API in Next.js and standalone adapters',
+  },
+] as const
+
+const featureClusters = [
+  {
+    title: 'Integration Layer',
+    label: 'RHF + server submit flow',
+    points: [
+      'Single hook for React Hook Form and server submit handlers',
+      'Schema-driven types from withZod into client usage',
+      'Automatic data and error shape handling for common server responses',
+    ],
+  },
+  {
+    title: 'State And UX',
+    label: 'Fast forms without custom plumbing',
+    points: [
+      'Pending state aligned with concurrent React submit flow',
+      'Optimistic updates with rollback support',
+      'Session persistence for multi-step and long forms',
+    ],
+  },
+  {
+    title: 'Extensibility',
+    label: 'Fits existing architecture',
+    points: [
+      'Next.js adapter and standalone adapter with matching API',
+      'Lifecycle callbacks for success and error integrations',
+      'DevTools package for live form and submission inspection',
+    ],
+  },
+  {
+    title: 'Production Readiness',
+    label: 'Built for real projects',
+    points: [
+      'ESM + CJS outputs and tree-shakeable package structure',
+      'MIT licensed monorepo with separate package changelogs',
+      'Automated test coverage in core and standalone adapters',
+    ],
+  },
+] as const
+
+const examples = [
+  {
+    title: 'Login With Server Errors',
+    stack: 'Next.js Server Actions',
+    level: 'Beginner',
+    description: 'Typed login form with field-level server validation and pending button state.',
+    href: '/examples/login',
+    cta: 'Open login example',
+  },
+  {
+    title: 'Optimistic Todo Submit',
+    stack: 'Next.js + optimistic UI',
+    level: 'Common',
+    description: 'Immediate UI updates during submit, with rollback behavior when server fails.',
+    href: '/examples/optimistic',
+    cta: 'Open optimistic example',
+  },
+  {
+    title: 'Multi-Step Wizard',
+    stack: 'Next.js + persistence',
+    level: 'Advanced',
+    description: 'Persist form progress across reloads and steps with a shared persist key.',
+    href: '/examples/wizard',
+    cta: 'Open wizard example',
+  },
+  {
+    title: 'Standalone Submit Flow',
+    stack: 'Vite / Remix / Astro',
+    level: 'Common',
+    description: 'Same API using submit functions with fetch, axios, or RPC endpoints.',
+    href: '/recipes/standalone-fetch',
+    cta: 'Open standalone recipe',
+  },
+] as const
+
+const trustSignals = [
+  { title: 'Versioned Packages', detail: 'v4.0.x adapters and core published independently.' },
+  { title: 'MIT License', detail: 'Open source license with permissive commercial usage.' },
+  { title: 'Automated Tests', detail: 'Core and standalone packages include Vitest test suites.' },
+  { title: 'CI In GitHub Actions', detail: 'Repository checks run in public workflow pipelines.' },
+  { title: 'Changelogs', detail: 'Each package has explicit release notes and history.' },
+  { title: 'SemVer Workflow', detail: 'Changesets + release process managed in monorepo scripts.' },
+] as const
+
+const faqItems = [
+  {
+    question: 'Is this too much abstraction over React Hook Form?',
+    answer:
+      'No. You still use RHF primitives directly. The library removes repeated glue code between RHF, server submit handlers, and schema validation.',
+  },
+  {
+    question: 'Should I use it for small forms?',
+    answer:
+      'If your form never hits a server, native RHF is often enough. The value appears when multiple forms share server submit and validation flows.',
+  },
+  {
+    question: 'Can I use it outside Next.js?',
+    answer:
+      'Yes. Use hookform-action-standalone for Vite, Remix, Astro, or any React app with async submit functions.',
+  },
+  {
+    question: 'Do I need Zod?',
+    answer:
+      'Zod is optional, but recommended. withZod unlocks end-to-end type inference and automatic error mapping without duplicated schema setup.',
+  },
+] as const
+
 export default function HomePage() {
   return (
-    <div className="max-w-4xl mx-auto px-6 py-24">
-      {/* Hero */}
-      <section className="text-center mb-20">
-        <div className="inline-flex items-center gap-2 bg-brand-500/10 text-brand-400 border border-brand-500/20 rounded-full px-4 py-1.5 text-sm font-medium mb-6">
-          <span>v3.0.0</span>
-          <span className="text-gray-600">·</span>
-          <span>Framework-Agnostic</span>
-        </div>
-        <h1 className="text-5xl sm:text-6xl font-extrabold tracking-tight mb-6">
-          React Hook Form{' '}
-          <span className="text-transparent bg-clip-text bg-gradient-to-r from-brand-400 to-cyan-400">
-            for every React stack
-          </span>
-        </h1>
-        <p className="text-xl text-gray-400 max-w-2xl mx-auto mb-10">
-          From Next.js Server Actions to Vite SPAs — automatic Zod error mapping, optimistic UI,
-          client-side validation, multi-step persistence, and a beautiful DevTools panel.
-        </p>
-        <div className="flex justify-center gap-4">
-          <a
-            href="/examples/login"
-            className="inline-flex items-center px-6 py-3 bg-brand-600 hover:bg-brand-500 text-white rounded-lg font-medium transition-colors"
-          >
-            See Examples
-          </a>
-          <a
-            href="/standalone"
-            className="inline-flex items-center px-6 py-3 border border-emerald-700 hover:border-emerald-500 text-emerald-300 rounded-lg font-medium transition-colors"
-          >
-            Standalone Guide
-          </a>
-          <a
-            href="/api-reference"
-            className="inline-flex items-center px-6 py-3 border border-gray-700 hover:border-gray-500 text-gray-300 rounded-lg font-medium transition-colors"
-          >
-            API Reference
-          </a>
+    <div className="max-w-6xl mx-auto px-6 py-16 sm:py-20">
+      <section className="relative mb-14 overflow-hidden rounded-3xl border border-gray-800 bg-gray-900/60 px-6 py-12 sm:px-10 sm:py-16">
+        <div className="pointer-events-none absolute -top-28 -left-16 h-72 w-72 rounded-full bg-brand-600/20 blur-3xl" />
+        <div className="pointer-events-none absolute -bottom-24 right-0 h-64 w-64 rounded-full bg-cyan-500/20 blur-3xl" />
+        <div className="relative">
+          <div className="inline-flex items-center gap-2 rounded-full border border-brand-400/30 bg-brand-500/10 px-4 py-1.5 text-sm font-medium text-brand-300">
+            <span>v4.0.x</span>
+            <span className="text-gray-600">|</span>
+            <span>Docs Home</span>
+          </div>
+          <h1 className="mt-6 text-4xl font-extrabold tracking-tight text-white sm:text-6xl">
+            React Hook Form + server submit flows, without boilerplate.
+          </h1>
+          <p className="mt-5 max-w-3xl text-base leading-relaxed text-gray-300 sm:text-lg">
+            Connect React Hook Form to Server Actions or submit functions with end-to-end types, Zod
+            mapping, optimistic UI, and persistence for multi-step flows.
+          </p>
+          <p className="mt-3 text-sm text-gray-500">
+            Pick your adapter. Keep one API. Ship production forms faster.
+          </p>
+          <div className="mt-8 flex flex-wrap items-center gap-3">
+            <a
+              href="/examples/login"
+              className="inline-flex items-center rounded-lg bg-brand-600 px-5 py-2.5 text-sm font-semibold text-white transition-colors hover:bg-brand-500"
+            >
+              Build your first form in 2 minutes
+            </a>
+            <a
+              href="/standalone"
+              className="inline-flex items-center rounded-lg border border-emerald-600/60 px-5 py-2.5 text-sm font-semibold text-emerald-300 transition-colors hover:border-emerald-400"
+            >
+              Open Standalone Quick Start
+            </a>
+            <a
+              href="/api-reference"
+              className="inline-flex items-center rounded-lg border border-gray-700 px-5 py-2.5 text-sm font-semibold text-gray-200 transition-colors hover:border-gray-500"
+            >
+              Read full API
+            </a>
+          </div>
+          <div className="mt-8 flex flex-wrap items-center gap-2 text-xs text-gray-400">
+            <span className="rounded-full border border-gray-700 px-2.5 py-1">
+              Next.js Server Actions
+            </span>
+            <span className="rounded-full border border-gray-700 px-2.5 py-1">Vite</span>
+            <span className="rounded-full border border-gray-700 px-2.5 py-1">Remix</span>
+            <span className="rounded-full border border-gray-700 px-2.5 py-1">Astro</span>
+          </div>
         </div>
       </section>
 
-      {/* Install */}
-      <section className="mb-20">
-        <h2 className="text-2xl font-bold mb-4 text-center">Quick Start</h2>
-        <div className="grid sm:grid-cols-2 gap-4">
+      <section className="mb-20 rounded-2xl border border-gray-800 bg-gray-900/40 p-6 sm:p-8">
+        <div className="mb-6 flex flex-wrap items-end justify-between gap-4">
           <div>
-            <p className="text-sm text-gray-400 mb-2 text-center">Next.js (Server Actions)</p>
-            <div className="code-block text-center">
-              <code className="text-green-400">
+            <h2 className="text-2xl font-bold text-white sm:text-3xl">Quick Start In 3 Steps</h2>
+            <p className="mt-2 text-sm text-gray-400">
+              From install to first submit in around two minutes.
+            </p>
+          </div>
+          <div className="text-xs text-gray-500">
+            New here? Start with{' '}
+            <a href="/examples/login" className="text-brand-400 hover:text-brand-300">
+              login example
+            </a>
+            .
+          </div>
+        </div>
+        <div className="grid gap-4 lg:grid-cols-3">
+          <div className="rounded-xl border border-gray-800 bg-gray-950/50 p-4">
+            <p className="text-xs font-semibold uppercase tracking-widest text-brand-300">Step 1</p>
+            <h3 className="mt-2 text-base font-semibold text-white">
+              Install the adapter for your stack
+            </h3>
+            <div className="mt-3 space-y-2 text-xs">
+              <div className="rounded-lg border border-gray-800 bg-gray-900 px-3 py-2 text-green-300">
                 npm install hookform-action react-hook-form zod
-              </code>
+              </div>
+              <div className="rounded-lg border border-gray-800 bg-gray-900 px-3 py-2 text-green-300">
+                npm install hookform-action-standalone react-hook-form zod
+              </div>
             </div>
           </div>
-          <div>
-            <p className="text-sm text-gray-400 mb-2 text-center">
-              Vite / Remix / Astro (Standalone)
-            </p>
-            <div className="code-block text-center">
-              <code className="text-green-400">
-                npm install hookform-action-standalone react-hook-form zod
-              </code>
+          <div className="rounded-xl border border-gray-800 bg-gray-950/50 p-4">
+            <p className="text-xs font-semibold uppercase tracking-widest text-brand-300">Step 2</p>
+            <h3 className="mt-2 text-base font-semibold text-white">
+              Wrap server logic with withZod
+            </h3>
+            <div className="code-block mt-3 text-xs leading-relaxed text-gray-300">
+              <pre>{`export const action = withZod(schema, async (data) => {
+  return { success: true };
+});`}</pre>
+            </div>
+          </div>
+          <div className="rounded-xl border border-gray-800 bg-gray-950/50 p-4">
+            <p className="text-xs font-semibold uppercase tracking-widest text-brand-300">Step 3</p>
+            <h3 className="mt-2 text-base font-semibold text-white">
+              Call useActionForm and submit
+            </h3>
+            <div className="code-block mt-3 text-xs leading-relaxed text-gray-300">
+              <pre>{`const form = useActionForm(action, {
+  validationMode: 'onChange',
+});
+<form onSubmit={form.handleSubmit()} />`}</pre>
             </div>
           </div>
         </div>
       </section>
 
-      {/* v3 Highlights */}
-      <section className="mb-20">
-        <h2 className="text-2xl font-bold mb-6 text-center">What&apos;s New in v3</h2>
-        <div className="grid sm:grid-cols-2 gap-6">
-          <div className="bg-gradient-to-br from-emerald-500/10 to-cyan-500/10 border border-emerald-500/20 rounded-xl p-6">
-            <div className="text-3xl mb-3">🌍</div>
-            <h3 className="text-lg font-semibold mb-2">Framework-Agnostic Core</h3>
-            <p className="text-gray-400 text-sm">
-              The core logic no longer depends on Next.js. Use{' '}
-              <code>hookform-action-standalone</code> with Vite, Remix, Astro, or any React app.
+      <section className="mb-20" id="comparison">
+        <h2 className="text-2xl font-bold text-white sm:text-3xl">
+          Manual Wiring vs hookform-action
+        </h2>
+        <p className="mt-2 max-w-3xl text-sm text-gray-400">
+          Same primitives, less glue code. You keep RHF and Zod control, but remove repeated
+          submit-flow plumbing.
+        </p>
+        <div className="mt-6 overflow-x-auto rounded-2xl border border-gray-800 bg-gray-900/40">
+          <table className="w-full min-w-[760px] text-left text-sm">
+            <thead>
+              <tr className="border-b border-gray-800 text-gray-400">
+                <th className="px-4 py-3 font-semibold">Concern</th>
+                <th className="px-4 py-3 font-semibold text-red-300">Manual</th>
+                <th className="px-4 py-3 font-semibold text-brand-300">hookform-action</th>
+              </tr>
+            </thead>
+            <tbody className="divide-y divide-gray-800/70 text-gray-300">
+              {comparisonRows.map((row) => (
+                <tr key={row.concern}>
+                  <td className="px-4 py-3.5 font-medium">{row.concern}</td>
+                  <td className="px-4 py-3.5 text-gray-400">{row.manual}</td>
+                  <td className="px-4 py-3.5">{row.withHookformAction}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+
+        <div className="mt-6 grid gap-4 lg:grid-cols-2">
+          <div className="rounded-xl border border-red-700/40 bg-red-950/10 p-5">
+            <p className="text-xs font-semibold uppercase tracking-widest text-red-300">
+              Before (manual)
             </p>
+            <div className="code-block mt-3 text-xs leading-relaxed text-gray-300">
+              <pre>{`const result = await action(values);
+if (result.errors) {
+  for (const [field, messages] of Object.entries(result.errors)) {
+    setError(field as keyof Fields, { message: messages[0] });
+  }
+}`}</pre>
+            </div>
           </div>
-          <div className="bg-gradient-to-br from-purple-500/10 to-pink-500/10 border border-purple-500/20 rounded-xl p-6">
-            <div className="text-3xl mb-3">🔍</div>
-            <h3 className="text-lg font-semibold mb-2">DevTools Panel</h3>
-            <p className="text-gray-400 text-sm">
-              <code>hookform-action-devtools</code> — a floating debug panel showing form state,
-              submission history, and debug actions. Inspired by TanStack Query DevTools.
+          <div className="rounded-xl border border-brand-700/40 bg-brand-950/10 p-5">
+            <p className="text-xs font-semibold uppercase tracking-widest text-brand-300">
+              After (hookform-action)
             </p>
+            <div className="code-block mt-3 text-xs leading-relaxed text-gray-300">
+              <pre>{`const { handleSubmit, formState: { errors, isPending } } =
+  useActionForm(action, { validationMode: 'onChange' });
+
+<form onSubmit={handleSubmit()} />;`}</pre>
+            </div>
           </div>
-          <div className="bg-gradient-to-br from-brand-500/10 to-cyan-500/10 border border-brand-500/20 rounded-xl p-6">
-            <div className="text-3xl mb-3">🧩</div>
-            <h3 className="text-lg font-semibold mb-2">Plugin System (Internal)</h3>
-            <p className="text-gray-400 text-sm">
-              An internal plugin architecture with lifecycle hooks (<code>onBeforeSubmit</code>,
-              <code>onSuccess</code>, <code>onError</code>, <code>onMount</code>) powering future
-              extensibility.
-            </p>
+        </div>
+
+        <div className="mt-4 grid gap-3 sm:grid-cols-3">
+          <div className="rounded-xl border border-gray-800 bg-gray-900/40 p-4 text-center">
+            <p className="text-2xl font-bold text-brand-300">-1 layer</p>
+            <p className="mt-1 text-xs text-gray-500">single integration API for submit flows</p>
           </div>
-          <div className="bg-gradient-to-br from-brand-500/10 to-cyan-500/10 border border-brand-500/20 rounded-xl p-6">
-            <div className="text-3xl mb-3">🔄</div>
-            <h3 className="text-lg font-semibold mb-2">Zero Breaking Changes</h3>
-            <p className="text-gray-400 text-sm">
-              Existing <code>hookform-action</code> v2 imports work exactly the same. The Next.js
-              adapter is 100% backward-compatible.
-            </p>
+          <div className="rounded-xl border border-gray-800 bg-gray-900/40 p-4 text-center">
+            <p className="text-2xl font-bold text-brand-300">+1 schema</p>
+            <p className="mt-1 text-xs text-gray-500">server and client stay aligned</p>
+          </div>
+          <div className="rounded-xl border border-gray-800 bg-gray-900/40 p-4 text-center">
+            <p className="text-2xl font-bold text-brand-300">-N bugs</p>
+            <p className="mt-1 text-xs text-gray-500">less custom wiring to maintain per form</p>
           </div>
         </div>
       </section>
 
-      {/* Architecture diagram */}
-      <section className="mb-20">
-        <h2 className="text-2xl font-bold mb-6 text-center">Architecture</h2>
-        <div className="code-block text-gray-300 text-center leading-loose">
-          <pre>{`┌─────────────────────────────────────────────┐
-│        hookform-action-core (core)           │
-│   useActionFormCore · withZod · Form · persist │
-├────────────────────┬────────────────────────┤
-│  hookform-action   │  hookform-action       │
-│    (Next.js)       │    -standalone         │
-│  (Server Actions)  │  (fetch / REST / gRPC)  │
-└────────────────────┴────────────────────────┘
-          ┌──────────────────────┐
-          │ hookform-action    │
-          │     -devtools      │
-          │  (FormDevTool panel) │
-          └──────────────────────┘`}</pre>
+      <section className="mb-20" id="features">
+        <h2 className="text-2xl font-bold text-white sm:text-3xl">Feature Clusters</h2>
+        <p className="mt-2 max-w-3xl text-sm text-gray-400">
+          Built on top of RHF. No lock-in, only less repetition.
+        </p>
+        <div className="mt-6 grid gap-4 md:grid-cols-2">
+          {featureClusters.map((cluster) => (
+            <article
+              key={cluster.title}
+              className="rounded-2xl border border-gray-800 bg-gray-900/40 p-6"
+            >
+              <p className="text-xs font-semibold uppercase tracking-widest text-brand-300">
+                {cluster.label}
+              </p>
+              <h3 className="mt-2 text-lg font-semibold text-white">{cluster.title}</h3>
+              <ul className="mt-4 space-y-2 text-sm text-gray-300">
+                {cluster.points.map((point) => (
+                  <li key={point} className="flex items-start gap-2">
+                    <span className="mt-1 text-brand-300">•</span>
+                    <span>{point}</span>
+                  </li>
+                ))}
+              </ul>
+            </article>
+          ))}
         </div>
       </section>
 
-      {/* Features */}
-      <section className="grid sm:grid-cols-2 lg:grid-cols-3 gap-6 mb-20">
-        {[
-          {
-            icon: '🔒',
-            title: 'Type-Safe',
-            desc: 'Full TypeScript inference from your action — zero manual typing.',
-          },
-          {
-            icon: '⚡',
-            title: 'Auto Error Mapping',
-            desc: 'Zod validation errors mapped to RHF fields automatically.',
-          },
-          {
-            icon: '💾',
-            title: 'Wizard Persistence',
-            desc: 'Multi-step forms with sessionStorage persistence, debounced and SSR-safe.',
-          },
-          {
-            icon: '🚀',
-            title: 'Optimistic UI',
-            desc: 'Native useOptimistic integration. Instant UI updates with automatic rollback.',
-          },
-          {
-            icon: '📦',
-            title: 'Tiny Bundle',
-            desc: 'ESM + CJS via tsup. Tree-shakeable. React, RHF, and Zod are peer deps.',
-          },
-          {
-            icon: '🧪',
-            title: 'Fully Tested',
-            desc: '81+ tests covering core, adapters, plugins, persistence, and optimistic UI.',
-          },
-        ].map((f) => (
-          <div
-            key={f.title}
-            className="bg-gray-900/50 border border-gray-800 rounded-xl p-6 hover:border-gray-700 transition-colors"
-          >
-            <div className="text-3xl mb-3">{f.icon}</div>
-            <h3 className="text-lg font-semibold mb-2">{f.title}</h3>
-            <p className="text-gray-400 text-sm">{f.desc}</p>
+      <section className="mb-20" id="examples">
+        <div className="mb-6 flex flex-wrap items-end justify-between gap-4">
+          <div>
+            <h2 className="text-2xl font-bold text-white sm:text-3xl">Examples You Can Copy</h2>
+            <p className="mt-2 max-w-2xl text-sm text-gray-400">
+              Use these as your onboarding path: beginner to advanced submit flows.
+            </p>
           </div>
-        ))}
+          <a href="/recipes" className="text-sm font-semibold text-brand-400 hover:text-brand-300">
+            Browse all recipes
+          </a>
+        </div>
+        <div className="grid gap-4 sm:grid-cols-2">
+          {examples.map((example) => (
+            <article
+              key={example.title}
+              className="rounded-2xl border border-gray-800 bg-gray-900/40 p-5"
+            >
+              <div className="flex flex-wrap items-center gap-2 text-xs">
+                <span className="rounded-full border border-gray-700 px-2.5 py-1 text-gray-300">
+                  {example.stack}
+                </span>
+                <span className="rounded-full border border-brand-600/40 px-2.5 py-1 text-brand-300">
+                  {example.level}
+                </span>
+              </div>
+              <h3 className="mt-3 text-lg font-semibold text-white">{example.title}</h3>
+              <p className="mt-2 text-sm text-gray-400">{example.description}</p>
+              <a
+                href={example.href}
+                className="mt-4 inline-flex items-center text-sm font-semibold text-emerald-300 hover:text-emerald-200"
+              >
+                {example.cta} →
+              </a>
+            </article>
+          ))}
+        </div>
       </section>
 
-      {/* Usage – Next.js */}
-      <section className="mb-20">
-        <h2 className="text-2xl font-bold mb-2 text-center">Usage — Next.js</h2>
-        <p className="text-gray-400 text-sm text-center mb-6">
-          Works exactly like v2. No changes required.
-        </p>
-        <div className="code-block text-gray-300 leading-relaxed">
-          <pre>{`// actions.ts — Server Action
-'use server'
-import { z } from 'zod'
-import { withZod } from 'hookform-action-core/with-zod'
-
-const schema = z.object({
-  email: z.string().email(),
-  password: z.string().min(8),
-})
-
-export const loginAction = withZod(schema, async (data) => {
-  return { success: true }
-})
-
-// LoginForm.tsx — Client Component
-'use client'
-import { useActionForm } from 'hookform-action'
-import { loginAction } from './actions'
-
-export function LoginForm() {
-  const { register, handleSubmit, formState: { errors, isPending } } =
-    useActionForm(loginAction, {
-      defaultValues: { email: '', password: '' },
-      validationMode: 'onChange',
-    })
+      <section className="mb-20 grid gap-4 lg:grid-cols-2" id="model">
+        <article className="rounded-2xl border border-gray-800 bg-gray-900/40 p-6">
+          <h2 className="text-2xl font-bold text-white">Mental Model</h2>
+          <p className="mt-2 text-sm text-gray-400">One schema, one action, one form hook.</p>
+          <ol className="mt-5 space-y-3 text-sm text-gray-300">
+            <li>
+              1. Define schema and server handler with <code>withZod</code>.
+            </li>
+            <li>
+              2. Pass action (or submit function) into <code>useActionForm</code>.
+            </li>
+            <li>
+              3. Render standard RHF fields and call <code>handleSubmit()</code>.
+            </li>
+            <li>
+              4. Let the hook manage pending, error mapping, optimistic state, and persistence.
+            </li>
+          </ol>
+        </article>
+        <article className="rounded-2xl border border-gray-800 bg-gray-900/40 p-6">
+          <h3 className="text-lg font-semibold text-white">Architecture</h3>
+          <div className="code-block mt-4 text-xs leading-relaxed text-gray-300">
+            <pre>{`withZod(schema, handler)
+          |
+          v
+   useActionFormCore
+      /        \\
+     v          v
+hookform-action   hookform-action-standalone
+      \\          /
+       v        v
+   hookform-action-devtools`}</pre>
+          </div>
+        </article>
+      </section>
 
-  return (
-    <form onSubmit={handleSubmit()}>
-      <input {...register('email')} placeholder="Email" />
-      {errors.email && <span>{errors.email.message}</span>}
-      <input {...register('password')} type="password" />
-      {errors.password && <span>{errors.password.message}</span>}
-      <button disabled={isPending}>
-        {isPending ? 'Signing in...' : 'Sign In'}
-      </button>
-    </form>
-  )
-}`}</pre>
-        </div>
+      <section className="mb-20 grid gap-4 lg:grid-cols-2" id="compatibility">
+        <article className="rounded-2xl border border-gray-800 bg-gray-900/40 p-6">
+          <h2 className="text-2xl font-bold text-white">Compatibility</h2>
+          <div className="mt-4 overflow-x-auto">
+            <table className="w-full min-w-[380px] text-left text-sm">
+              <thead>
+                <tr className="border-b border-gray-800 text-gray-400">
+                  <th className="py-2 pr-4">Dependency</th>
+                  <th className="py-2 pr-4">Minimum</th>
+                  <th className="py-2">Notes</th>
+                </tr>
+              </thead>
+              <tbody className="divide-y divide-gray-800/70 text-gray-300">
+                <tr>
+                  <td className="py-2 pr-4">React</td>
+                  <td className="py-2 pr-4">18.0+</td>
+                  <td className="py-2">React 19 recommended for native useOptimistic behavior.</td>
+                </tr>
+                <tr>
+                  <td className="py-2 pr-4">React Hook Form</td>
+                  <td className="py-2 pr-4">7.50+</td>
+                  <td className="py-2">Required peer dependency.</td>
+                </tr>
+                <tr>
+                  <td className="py-2 pr-4">Zod</td>
+                  <td className="py-2 pr-4">3.22+</td>
+                  <td className="py-2">
+                    Optional, recommended for withZod and typed validation flow.
+                  </td>
+                </tr>
+                <tr>
+                  <td className="py-2 pr-4">Next.js</td>
+                  <td className="py-2 pr-4">14.0+</td>
+                  <td className="py-2">Only required for the Next.js adapter package.</td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+        </article>
+        <article className="rounded-2xl border border-gray-800 bg-gray-900/40 p-6">
+          <h3 className="text-lg font-semibold text-white">Upgrade Notes</h3>
+          <p className="mt-3 text-sm text-gray-300">
+            Current package line is <code>4.0.x</code>. Before upgrading, check package changelogs
+            to confirm API notes and migration details for your adapter.
+          </p>
+          <div className="mt-5 space-y-2 text-sm">
+            <a
+              href="https://github.com/gabpaesschulz/hookform-action/blob/main/packages/next/CHANGELOG.md"
+              target="_blank"
+              rel="noreferrer noopener"
+              className="block text-brand-400 hover:text-brand-300"
+            >
+              Open Next.js adapter changelog →
+            </a>
+            <a
+              href="https://github.com/gabpaesschulz/hookform-action/blob/main/packages/standalone/CHANGELOG.md"
+              target="_blank"
+              rel="noreferrer noopener"
+              className="block text-brand-400 hover:text-brand-300"
+            >
+              Open standalone adapter changelog →
+            </a>
+            <a href="/api-reference" className="block text-brand-400 hover:text-brand-300">
+              Open API reference →
+            </a>
+          </div>
+        </article>
       </section>
 
-      {/* Usage – Standalone */}
-      <section className="mb-20">
-        <h2 className="text-2xl font-bold mb-2 text-center">Usage — Vite / Standalone</h2>
-        <p className="text-gray-400 text-sm text-center mb-6">
-          Same API, pass <code>submit</code> instead of a Server Action.
+      <section className="mb-20" id="trust">
+        <h2 className="text-2xl font-bold text-white sm:text-3xl">Maturity And Trust Signals</h2>
+        <p className="mt-2 max-w-3xl text-sm text-gray-400">
+          Production-focused signals to reduce adoption risk.
         </p>
-        <div className="code-block text-gray-300 leading-relaxed">
-          <pre>{`import { useActionForm } from 'hookform-action-standalone'
-import { z } from 'zod'
-
-const schema = z.object({
-  email: z.string().email(),
-  password: z.string().min(8),
-})
-
-export function LoginForm() {
-  const { register, handleSubmit, formState: { errors, isPending } } =
-    useActionForm({
-      submit: async (data) => {
-        const res = await fetch('/api/login', {
-          method: 'POST',
-          body: JSON.stringify(data),
-          headers: { 'Content-Type': 'application/json' },
-        })
-        return res.json()
-      },
-      schema,
-      validationMode: 'onChange',
-      defaultValues: { email: '', password: '' },
-    })
+        <div className="mt-6 grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+          {trustSignals.map((item) => (
+            <article
+              key={item.title}
+              className="rounded-xl border border-gray-800 bg-gray-900/40 p-5"
+            >
+              <h3 className="text-sm font-semibold text-white">{item.title}</h3>
+              <p className="mt-2 text-sm text-gray-400">{item.detail}</p>
+            </article>
+          ))}
+        </div>
+        <div className="mt-6 flex flex-wrap items-center gap-3 text-sm">
+          <a
+            href="https://github.com/gabpaesschulz/hookform-action/actions"
+            target="_blank"
+            rel="noreferrer noopener"
+            className="inline-flex items-center rounded-lg border border-gray-700 px-4 py-2 text-gray-300 transition-colors hover:border-gray-500"
+          >
+            View CI pipeline
+          </a>
+          <a
+            href="https://github.com/gabpaesschulz/hookform-action"
+            target="_blank"
+            rel="noreferrer noopener"
+            className="inline-flex items-center rounded-lg border border-gray-700 px-4 py-2 text-gray-300 transition-colors hover:border-gray-500"
+          >
+            View repository
+          </a>
+        </div>
+      </section>
 
-  return (
-    <form onSubmit={handleSubmit()}>
-      <input {...register('email')} placeholder="Email" />
-      {errors.email && <span>{errors.email.message}</span>}
-      <input {...register('password')} type="password" />
-      {errors.password && <span>{errors.password.message}</span>}
-      <button disabled={isPending}>
-        {isPending ? 'Signing in...' : 'Sign In'}
-      </button>
-    </form>
-  )
-}`}</pre>
+      <section className="mb-20" id="faq">
+        <h2 className="text-2xl font-bold text-white sm:text-3xl">FAQ</h2>
+        <div className="mt-6 space-y-3">
+          {faqItems.map((item) => (
+            <details
+              key={item.question}
+              className="rounded-xl border border-gray-800 bg-gray-900/40 p-5"
+            >
+              <summary className="cursor-pointer text-sm font-semibold text-white">
+                {item.question}
+              </summary>
+              <p className="mt-3 text-sm leading-relaxed text-gray-400">{item.answer}</p>
+            </details>
+          ))}
         </div>
       </section>
 
-      {/* DevTools */}
-      <section className="mb-20">
-        <h2 className="text-2xl font-bold mb-2 text-center">DevTools</h2>
-        <p className="text-gray-400 text-sm text-center mb-6">
-          Add a floating panel to inspect form state in development.
+      <section className="rounded-2xl border border-brand-700/40 bg-brand-950/20 p-6 sm:p-8">
+        <h2 className="text-2xl font-bold text-white sm:text-3xl">
+          Install And Ship Your First Form Today
+        </h2>
+        <p className="mt-2 max-w-3xl text-sm text-gray-300">
+          Start with the adapter that matches your stack and move from setup to running form
+          quickly.
         </p>
-        <div className="code-block text-gray-300 leading-relaxed">
-          <pre>{`import { FormDevTool } from 'hookform-action-devtools'
-
-function App() {
-  const form = useActionForm(/* ... */)
-  return (
-    <>
-      <MyForm form={form} />
-      {process.env.NODE_ENV === 'development' && (
-        <FormDevTool control={form.control} />
-      )}
-    </>
-  )
-}`}</pre>
+        <div className="mt-5 grid gap-3 md:grid-cols-2">
+          <div className="rounded-lg border border-gray-800 bg-gray-950/70 px-3 py-2 text-xs text-green-300">
+            npm install hookform-action react-hook-form zod
+          </div>
+          <div className="rounded-lg border border-gray-800 bg-gray-950/70 px-3 py-2 text-xs text-green-300">
+            npm install hookform-action-standalone react-hook-form zod
+          </div>
+        </div>
+        <div className="mt-6 flex flex-wrap gap-3">
+          <a
+            href="/examples/login"
+            className="inline-flex items-center rounded-lg bg-brand-600 px-5 py-2.5 text-sm font-semibold text-white transition-colors hover:bg-brand-500"
+          >
+            Open quick start example
+          </a>
+          <a
+            href="/api-reference"
+            className="inline-flex items-center rounded-lg border border-gray-700 px-5 py-2.5 text-sm font-semibold text-gray-200 transition-colors hover:border-gray-500"
+          >
+            Read API reference
+          </a>
         </div>
       </section>
-
-      {/* Footer */}
-      <footer className="text-center text-gray-600 text-sm py-8 border-t border-gray-800">
-        <p>MIT License · Built with ♥ for the React community</p>
-      </footer>
     </div>
   )
 }
diff --git a/apps/docs/app/recipes/custom-error-mapper/page.tsx b/apps/docs/app/recipes/custom-error-mapper/page.tsx
new file mode 100644
index 0000000..c897afc
--- /dev/null
+++ b/apps/docs/app/recipes/custom-error-mapper/page.tsx
@@ -0,0 +1,307 @@
+export default function CustomErrorMapperPage() {
+  return (
+    <div className="max-w-4xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/recipes" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to Recipes
+        </a>
+      </div>
+
+      <div className="mb-12">
+        <div className="flex items-center gap-3 mb-4">
+          <span className="text-xs font-bold bg-gray-700/50 text-gray-400 border border-gray-600/50 rounded-full px-3 py-1">
+            Tier 3 · Specialized
+          </span>
+          <span className="text-gray-500 text-sm font-mono">Recipe #11</span>
+        </div>
+        <h1 className="text-3xl font-bold mb-3">Custom Error Mapper</h1>
+        <p className="text-lg text-gray-400">
+          When your API returns errors in a format different from the default{" "}
+          <code>{`{ errors: { field: string[] } }`}</code>, use a custom <code>errorMapper</code> to translate them into
+          React Hook Form field errors automatically.
+        </p>
+      </div>
+
+      {/* Why it matters */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-3">Why it matters</h2>
+        <p className="text-gray-400 leading-relaxed">
+          APIs designed before this library existed — Laravel backends, Rails APIs, external REST services, tRPC
+          procedures — rarely return errors in the <code>{`{ errors: { field: string[] } }`}</code> format that{" "}
+          <code>defaultErrorMapper</code> expects. Without a custom mapper, the hook cannot automatically set field
+          errors and you end up writing manual <code>setSubmitError</code> calls all over your form components.
+        </p>
+        <p className="text-gray-400 leading-relaxed mt-3">
+          The <code>errorMapper</code> option is a pure function defined once per form (or shared across forms hitting
+          the same API). It receives the raw action result and returns a <code>FieldErrorRecord</code> that the hook
+          applies to the correct fields automatically.
+        </p>
+      </section>
+
+      {/* Full Example */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-6">Full Example — Laravel-style errors</h2>
+
+        <div className="mb-5">
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4 mb-4">
+            <p className="text-sm text-gray-400 mb-2">
+              <span className="text-gray-200 font-medium">The external API returns:</span>
+            </p>
+            <pre className="text-gray-300 text-sm">{`{
+  "message": "The given data was invalid.",
+  "errors": {
+    "email": ["The email has already been taken.", "Must be a valid email."],
+    "password": ["The password must be at least 8 characters."]
+  }
+}`}</pre>
+            <p className="text-sm text-gray-500 mt-2">
+              (Laravel-style — the <code>errors</code> values are arrays of strings, which happens to match the default
+              format. The next example shows a stricter mismatch.)
+            </p>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            Example 1 — Laravel / Rails (arrays of strings)
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useActionForm } from 'hookform-action-standalone'
+import type { FieldErrorRecord } from 'hookform-action-core'
+import { submitRegistrationForm } from './api'
+
+// This API shape matches the default exactly — no custom mapper needed!
+// { errors: { field: string[] } }
+export function RegistrationForm() {
+  const { register, handleSubmit, formState: { errors, isPending } } =
+    useActionForm({
+      submit: submitRegistrationForm,
+      defaultValues: { email: '', password: '', name: '' },
+      // defaultErrorMapper handles this format automatically
+    })
+  // ...
+}`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4 mb-4">
+            <p className="text-sm text-gray-400 mb-2">
+              <span className="text-gray-200 font-medium">A non-standard API (object-per-error format):</span>
+            </p>
+            <pre className="text-gray-300 text-sm">{`{
+  "fieldErrors": {
+    "email": [{ "message": "Already taken", "code": "DUPLICATE" }],
+    "name":  [{ "message": "Too short", "code": "MIN_LENGTH" }]
+  },
+  "globalError": "Validation failed"
+}`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            error-mapper.ts — Shared mapper for this API
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`import type { FieldErrorRecord } from 'hookform-action-core'
+
+interface ApiError {
+  fieldErrors?: Record<string, Array<{ message: string; code: string }>>
+  globalError?: string
+}
+
+// Define outside components for stability (no re-renders)
+export function apiErrorMapper(result: unknown): FieldErrorRecord | null {
+  if (!result || typeof result !== 'object') return null
+  const r = result as ApiError
+
+  if (!r.fieldErrors) return null
+
+  const mapped: FieldErrorRecord = {}
+  for (const [field, errs] of Object.entries(r.fieldErrors)) {
+    // Extract just the message strings
+    mapped[field] = errs.map((e) => e.message)
+  }
+
+  return Object.keys(mapped).length > 0 ? mapped : null
+}`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            registration-form.tsx — Using the custom mapper
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useActionForm } from 'hookform-action-standalone'
+import { apiErrorMapper } from './error-mapper'
+import { submitRegistrationForm } from './api'
+
+interface ApiResult {
+  fieldErrors?: Record<string, Array<{ message: string; code: string }>>
+  globalError?: string
+  userId?: string
+}
+
+export function RegistrationForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isPending, isSubmitSuccessful, actionResult },
+  } = useActionForm<{ email: string; name: string; password: string }, ApiResult>({
+    submit: submitRegistrationForm,
+    defaultValues: { email: '', name: '', password: '' },
+
+    // Plug in the custom mapper — runs after every action call
+    errorMapper: apiErrorMapper,
+
+    onError: (result) => {
+      // Still fires even with custom mapper, good for toasts
+      if (result instanceof Error) {
+        console.error('Network error:', result.message)
+      } else if (result.globalError) {
+        // toast.error(result.globalError)
+      }
+    },
+  })
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      <div>
+        <label>Email</label>
+        <input type="email" {...register('email')} />
+        {/* Errors from apiErrorMapper appear here automatically */}
+        {errors.email && <p className="text-red-400">{errors.email.message}</p>}
+      </div>
+
+      <div>
+        <label>Name</label>
+        <input {...register('name')} />
+        {errors.name && <p className="text-red-400">{errors.name.message}</p>}
+      </div>
+
+      <div>
+        <label>Password</label>
+        <input type="password" {...register('password')} />
+        {errors.password && <p className="text-red-400">{errors.password.message}</p>}
+      </div>
+
+      {/* Show global error from actionResult */}
+      {actionResult?.globalError && (
+        <div className="bg-red-500/10 border border-red-500/30 rounded-lg p-3 text-sm text-red-400">
+          {actionResult.globalError}
+        </div>
+      )}
+
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Registering…' : 'Create Account'}
+      </button>
+    </form>
+  )
+}`}</pre>
+          </div>
+        </div>
+      </section>
+
+      {/* Key Concepts */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">Key Concepts</h2>
+        <div className="space-y-3">
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">errorMapper: (result) =&gt; FieldErrorRecord | null</code>
+            <p className="text-gray-400 text-sm mt-1">
+              A pure function that receives the raw action result (typed as <code>TResult</code>) and returns a{" "}
+              <code>FieldErrorRecord</code> — a <code>Record&lt;string, string[] | undefined&gt;</code>. Return{" "}
+              <code>null</code> or <code>undefined</code> when there are no errors. The hook calls <code>setError</code>{" "}
+              on each field automatically.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">Define mapper outside the component</code>
+            <p className="text-gray-400 text-sm mt-1">
+              The <code>errorMapper</code> is compared by reference between renders. An inline arrow function creates a
+              new reference every time, causing the hook to re-run unnecessarily. Define it at module scope or wrap with{" "}
+              <code>useCallback</code>.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">Global errors via actionResult</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Errors that cannot be mapped to a specific field (e.g. &quot;service unavailable&quot;) should be read
+              from <code>formState.actionResult</code> and rendered separately — not through the field error system.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">Composing with defaultErrorMapper</code>
+            <p className="text-gray-400 text-sm mt-1">
+              You can import and call <code>defaultErrorMapper</code> inside your custom mapper as a fallback for fields
+              that already match the default format, and only override the fields that don&apos;t.
+            </p>
+          </div>
+        </div>
+      </section>
+
+      {/* Pitfalls */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">⚠️ Pitfalls</h2>
+        <ul className="space-y-3">
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Returning an empty object <code>{`{}`}</code> instead of <code>null</code>
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                The hook checks if the returned object is truthy and has keys. An empty object <code>{`{}`}</code> is
+                truthy, but all its field lookups return <code>undefined</code>. Return <code>null</code> or{" "}
+                <code>undefined</code> explicitly when there are no errors to map.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Inline arrow function as <code>errorMapper</code>
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                <code>{"errorMapper: (r) => ..."}</code> creates a new function on every render. Since the hook uses it
+                as a dependency, this can cause performance issues. Always define the mapper at module scope.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">Mapper receives the result even on success</p>
+              <p className="text-sm text-gray-400 mt-1">
+                <code>errorMapper</code> is called after every action invocation, including successful ones. Always add
+                a guard (e.g. check for the presence of an error key) and return <code>null</code> for success
+                responses.
+              </p>
+            </div>
+          </li>
+        </ul>
+      </section>
+
+      {/* Related */}
+      <section className="border-t border-gray-800 pt-8">
+        <h2 className="text-lg font-semibold mb-4">Related</h2>
+        <div className="flex flex-wrap gap-4 text-sm">
+          <a href="/recipes/signup-server-errors" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Sign Up with Server Errors
+          </a>
+          <a href="/recipes/standalone-fetch" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Standalone — Fetch &amp; Custom APIs
+          </a>
+          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → API Reference
+          </a>
+        </div>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/app/recipes/edit-server-data/page.tsx b/apps/docs/app/recipes/edit-server-data/page.tsx
new file mode 100644
index 0000000..8c4e50f
--- /dev/null
+++ b/apps/docs/app/recipes/edit-server-data/page.tsx
@@ -0,0 +1,273 @@
+export default function EditServerDataPage() {
+  return (
+    <div className="max-w-4xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/recipes" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to Recipes
+        </a>
+      </div>
+
+      <div className="mb-12">
+        <div className="flex items-center gap-3 mb-4">
+          <span className="text-xs font-bold bg-red-500/15 text-red-400 border border-red-500/25 rounded-full px-3 py-1">
+            Tier 1 · Must-have
+          </span>
+          <span className="text-gray-500 text-sm font-mono">Recipe #4</span>
+        </div>
+        <h1 className="text-3xl font-bold mb-3">Edit Form with Server-Loaded Data</h1>
+        <p className="text-lg text-gray-400">
+          Pre-populate a form from a Server Component, track which fields the user actually changed, and revalidate the
+          page data after a successful save.
+        </p>
+      </div>
+
+      {/* Why it matters */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-3">Why it matters</h2>
+        <p className="text-gray-400 leading-relaxed">
+          Edit forms are the second most common form type after login. They require loading data from the server and
+          using it as <code>defaultValues</code> — but there&apos;s a fundamental tension: Server Components can fetch
+          data asynchronously, while <code>useActionForm</code> lives in a Client Component. Getting the data handoff
+          right prevents stale defaults and unintended dirty-field detection.
+        </p>
+        <p className="text-gray-400 leading-relaxed mt-3">
+          This recipe shows the canonical Server → Client pattern, how to use <code>isDirty</code> to show the save
+          button only when something changed, and how to use <code>router.refresh()</code> to revalidate without a full
+          page reload.
+        </p>
+      </section>
+
+      {/* Full Example */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-6">Full Example</h2>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            actions.ts
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use server'
+import { z } from 'zod'
+import { withZod } from 'hookform-action-core/with-zod'
+
+const profileSchema = z.object({
+  name: z.string().min(1, 'Name is required'),
+  bio: z.string().max(160, 'Bio must be 160 characters or fewer'),
+  website: z.string().url('Enter a valid URL').optional().or(z.literal('')),
+})
+
+export const updateProfileAction = withZod(profileSchema, async (data) => {
+  // data is typed: { name: string; bio: string; website?: string }
+  await db.profiles.update({
+    where: { userId: session.userId },
+    data,
+  })
+  return { success: true }
+})`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            page.tsx — Server Component
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`// This is a Server Component — it can be async and access the database directly
+import { db } from '@/lib/db'
+import { EditProfileForm } from './edit-profile-form'
+
+export default async function EditProfilePage() {
+  // Fetch the current profile on the server
+  const profile = await db.profiles.findUnique({
+    where: { userId: session.userId },
+    select: { name: true, bio: true, website: true },
+  })
+
+  if (!profile) return <p>Profile not found.</p>
+
+  // Pass to the Client Component as a plain prop
+  return <EditProfileForm defaultValues={profile} />
+}`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            edit-profile-form.tsx — Client Component
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useActionForm } from 'hookform-action'
+import { useRouter } from 'next/navigation'
+import { updateProfileAction } from './actions'
+
+interface EditProfileFormProps {
+  defaultValues: {
+    name: string
+    bio: string
+    website: string
+  }
+}
+
+export function EditProfileForm({ defaultValues }: EditProfileFormProps) {
+  const router = useRouter()
+  const {
+    register,
+    handleSubmit,
+    reset,
+    formState: { errors, isPending, isDirty, dirtyFields },
+  } = useActionForm(updateProfileAction, {
+    defaultValues,
+    onSuccess: (result) => {
+      // Re-fetch the Server Component data without a full reload
+      router.refresh()
+      // Optionally reset to the newly saved values to clear isDirty
+      reset(defaultValues)
+    },
+  })
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      <div>
+        <label htmlFor="name">Display Name</label>
+        <input id="name" {...register('name')} />
+        {errors.name && <p className="text-red-400">{errors.name.message}</p>}
+      </div>
+
+      <div>
+        <label htmlFor="bio">
+          Bio
+          {dirtyFields.bio && (
+            <span className="text-xs text-brand-400 ml-2">modified</span>
+          )}
+        </label>
+        <textarea id="bio" {...register('bio')} rows={3} />
+        {errors.bio && <p className="text-red-400">{errors.bio.message}</p>}
+      </div>
+
+      <div>
+        <label htmlFor="website">Website</label>
+        <input id="website" type="url" {...register('website')} />
+        {errors.website && <p className="text-red-400">{errors.website.message}</p>}
+      </div>
+
+      {/* Only show the Save button when something has changed */}
+      <button
+        type="submit"
+        disabled={isPending || !isDirty}
+        className={!isDirty ? 'opacity-50 cursor-not-allowed' : ''}
+      >
+        {isPending ? 'Saving…' : isDirty ? 'Save Changes' : 'No Changes'}
+      </button>
+    </form>
+  )
+}`}</pre>
+          </div>
+        </div>
+      </section>
+
+      {/* Key Concepts */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">Key Concepts</h2>
+        <div className="space-y-3">
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">Server Component → Client Component data handoff</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Fetch data in an async Server Component, then pass it as a plain prop to the Client Component. The Client
+              Component receives it as a stable object and uses it as <code>defaultValues</code>. This avoids the{" "}
+              <code>useEffect</code> fetch anti-pattern and leverages Next.js caching.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">isDirty / dirtyFields</code>
+            <p className="text-gray-400 text-sm mt-1">
+              <code>isDirty</code> is <code>true</code> when at least one field differs from its{" "}
+              <code>defaultValue</code>. <code>dirtyFields</code> is a record of which specific fields changed. Use them
+              to disable the save button when nothing has been modified and to show per-field change indicators.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">router.refresh()</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Re-executes all Server Components on the current route without a full navigation. The Server Component
+              re-fetches the updated data and passes it as new props to the Client Component. Call it in{" "}
+              <code>onSuccess</code> after a successful save.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">reset(newValues) after save</code>
+            <p className="text-gray-400 text-sm mt-1">
+              After a successful edit, call <code>reset(result.data)</code> or <code>reset(defaultValues)</code> to
+              update the RHF baseline. This clears <code>isDirty</code> so the save button correctly disables again
+              without a full remount.
+            </p>
+          </div>
+        </div>
+      </section>
+
+      {/* Pitfalls */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">⚠️ Pitfalls</h2>
+        <ul className="space-y-3">
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Unstable <code>defaultValues</code> causing unintended resets
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                If <code>defaultValues</code> is an inline object literal created on every render, RHF may re-initialise
+                and clear user edits. Always pass a stable reference — either from a Server Component prop, a{" "}
+                <code>useMemo</code>, or a fetched query result.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                <code>isSubmitSuccessful</code> stays <code>true</code> after save
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                For edit forms you usually want the user to stay on the page and keep editing. Avoid gating the form
+                behind <code>isSubmitSuccessful</code> — it will hide the form after the first save. Use{" "}
+                <code>onSuccess</code> for side effects only.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Forgetting <code>reset()</code> after a successful save
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                Without <code>reset()</code>, <code>isDirty</code> stays <code>true</code> even though the changes were
+                saved. The save button remains enabled and the user may accidentally re-submit.
+              </p>
+            </div>
+          </li>
+        </ul>
+      </section>
+
+      {/* Related */}
+      <section className="border-t border-gray-800 pt-8">
+        <h2 className="text-lg font-semibold mb-4">Related</h2>
+        <div className="flex flex-wrap gap-4 text-sm">
+          <a href="/recipes/reset-after-success" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Reset After Success
+          </a>
+          <a href="/recipes/modal-form" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Modal / Dialog Form
+          </a>
+          <a href="/recipes/signup-server-errors" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Sign Up with Server Errors
+          </a>
+          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → API Reference
+          </a>
+        </div>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/app/recipes/field-array/page.tsx b/apps/docs/app/recipes/field-array/page.tsx
new file mode 100644
index 0000000..ec138ca
--- /dev/null
+++ b/apps/docs/app/recipes/field-array/page.tsx
@@ -0,0 +1,306 @@
+export default function FieldArrayPage() {
+  return (
+    <div className="max-w-4xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/recipes" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to Recipes
+        </a>
+      </div>
+
+      <div className="mb-12">
+        <div className="flex items-center gap-3 mb-4">
+          <span className="text-xs font-bold bg-yellow-500/15 text-yellow-400 border border-yellow-500/25 rounded-full px-3 py-1">
+            Tier 2 · Common
+          </span>
+          <span className="text-gray-500 text-sm font-mono">Recipe #8</span>
+        </div>
+        <h1 className="text-3xl font-bold mb-3">Dynamic Fields with useFieldArray</h1>
+        <p className="text-lg text-gray-400">
+          Add and remove array items at runtime, validate each row independently, and submit the full typed array to
+          your server action.
+        </p>
+      </div>
+
+      {/* Why it matters */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-3">Why it matters</h2>
+        <p className="text-gray-400 leading-relaxed">
+          Dynamic lists — invoice line items, contact addresses, team members, skill tags — are one of the most common
+          patterns in real-world forms. React Hook Form&apos;s <code>useFieldArray</code> is the standard solution, but
+          integrating it with <code>useActionForm</code> has nuances: the <code>control</code> object must come from the
+          hook, arrays don&apos;t play well with <code>FormData</code> actions, and per-item error paths have a specific
+          shape.
+        </p>
+        <p className="text-gray-400 leading-relaxed mt-3">
+          This recipe shows a complete address list form with add, remove, per-field errors, and a <code>withZod</code>{" "}
+          server action that receives and validates the full typed array.
+        </p>
+      </section>
+
+      {/* Full Example */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-6">Full Example — Address List</h2>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            actions.ts
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use server'
+import { z } from 'zod'
+import { withZod } from 'hookform-action-core/with-zod'
+
+const addressSchema = z.object({
+  addresses: z
+    .array(
+      z.object({
+        street:  z.string().min(1, 'Street is required'),
+        city:    z.string().min(1, 'City is required'),
+        country: z.string().min(2, 'Select a country'),
+      })
+    )
+    .min(1, 'Add at least one address'),
+})
+
+export const saveAddressesAction = withZod(addressSchema, async (data) => {
+  // data.addresses is typed as { street: string; city: string; country: string }[]
+  await db.addresses.replaceAll(data.addresses)
+  return { success: true }
+})`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            address-form.tsx
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useFieldArray } from 'react-hook-form'   // from RHF, not hookform-action
+import { useActionForm } from 'hookform-action'
+import { saveAddressesAction } from './actions'
+
+type AddressValues = {
+  addresses: { street: string; city: string; country: string }[]
+}
+
+const EMPTY_ADDRESS = { street: '', city: '', country: '' }
+
+export function AddressForm() {
+  const {
+    register,
+    control,          // ← pass to useFieldArray
+    handleSubmit,
+    formState: { errors, isPending, isSubmitSuccessful },
+  } = useActionForm<AddressValues>(saveAddressesAction, {
+    defaultValues: { addresses: [EMPTY_ADDRESS] },
+  })
+
+  // useFieldArray reads and writes through the same RHF control
+  const { fields, append, remove, move } = useFieldArray({
+    control,
+    name: 'addresses',
+  })
+
+  if (isSubmitSuccessful) {
+    return <p className="text-green-400">Addresses saved!</p>
+  }
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      <div className="space-y-4">
+        {fields.map((field, index) => (
+          // IMPORTANT: use field.id as key — not the array index
+          <div key={field.id} className="border border-gray-800 rounded-lg p-4">
+            <div className="flex items-center justify-between mb-3">
+              <span className="text-sm font-medium text-gray-400">
+                Address {index + 1}
+              </span>
+              {fields.length > 1 && (
+                <button
+                  type="button"
+                  onClick={() => remove(index)}
+                  className="text-sm text-red-400 hover:text-red-300"
+                >
+                  Remove
+                </button>
+              )}
+            </div>
+
+            <div className="space-y-3">
+              <div>
+                <label className="text-xs text-gray-500">Street</label>
+                <input
+                  {...register(\`addresses.\${index}.street\`)}
+                  placeholder="123 Main St"
+                />
+                {errors.addresses?.[index]?.street && (
+                  <p className="text-red-400 text-sm mt-1">
+                    {errors.addresses[index].street?.message}
+                  </p>
+                )}
+              </div>
+
+              <div className="grid grid-cols-2 gap-3">
+                <div>
+                  <label className="text-xs text-gray-500">City</label>
+                  <input
+                    {...register(\`addresses.\${index}.city\`)}
+                    placeholder="New York"
+                  />
+                  {errors.addresses?.[index]?.city && (
+                    <p className="text-red-400 text-sm mt-1">
+                      {errors.addresses[index].city?.message}
+                    </p>
+                  )}
+                </div>
+
+                <div>
+                  <label className="text-xs text-gray-500">Country</label>
+                  <select {...register(\`addresses.\${index}.country\`)}>
+                    <option value="">Select…</option>
+                    <option value="US">United States</option>
+                    <option value="GB">United Kingdom</option>
+                    <option value="BR">Brazil</option>
+                  </select>
+                  {errors.addresses?.[index]?.country && (
+                    <p className="text-red-400 text-sm mt-1">
+                      {errors.addresses[index].country?.message}
+                    </p>
+                  )}
+                </div>
+              </div>
+            </div>
+          </div>
+        ))}
+      </div>
+
+      {/* Array-level error (e.g. "Add at least one address") */}
+      {errors.addresses?.root && (
+        <p className="text-red-400 text-sm mt-2">{errors.addresses.root.message}</p>
+      )}
+
+      <div className="flex gap-3 mt-6">
+        <button
+          type="button"
+          onClick={() => append(EMPTY_ADDRESS)}
+          className="text-sm text-brand-400 hover:text-brand-300"
+        >
+          + Add address
+        </button>
+
+        <button type="submit" disabled={isPending} className="ml-auto">
+          {isPending ? 'Saving…' : 'Save Addresses'}
+        </button>
+      </div>
+    </form>
+  )
+}`}</pre>
+          </div>
+        </div>
+      </section>
+
+      {/* Key Concepts */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">Key Concepts</h2>
+        <div className="space-y-3">
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">useFieldArray requires control</code>
+            <p className="text-gray-400 text-sm mt-1">
+              <code>useFieldArray</code> is from <code>react-hook-form</code> (not this library). It needs the{" "}
+              <code>control</code> object from <code>useActionForm</code>. You cannot use it with the standalone{" "}
+              <code>register</code> spread pattern.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">field.id as key (not index)</code>
+            <p className="text-gray-400 text-sm mt-1">
+              <code>useFieldArray</code> generates stable IDs for each row. Always use <code>field.id</code> as the
+              React <code>key</code>, not the array index. Index-based keys cause incorrect animations and state
+              mismatches when rows are removed.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">{`register(\`name.\${index}.field\`)`} — dot notation</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Use template literal dot-notation to register nested array fields. RHF will collect them into a properly
+              structured array in <code>getValues()</code> and on submit.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">Use withZod (JSON action), not FormData</code>
+            <p className="text-gray-400 text-sm mt-1">
+              FormData doesn&apos;t natively support nested arrays. Always use <code>withZod</code> (which sends JSON)
+              for forms with <code>useFieldArray</code>. If you must use a FormData action, serialize the array manually
+              with <code>JSON.stringify</code>.
+            </p>
+          </div>
+        </div>
+      </section>
+
+      {/* Pitfalls */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">⚠️ Pitfalls</h2>
+        <ul className="space-y-3">
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Using the array index as <code>key</code>
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                When you remove item at index 1 from [0, 1, 2], React reuses the DOM node for the new index 1
+                (previously index 2). Input values get mixed up. Always use <code>field.id</code>.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">Per-item errors path typo</p>
+              <p className="text-sm text-gray-400 mt-1">
+                The errors path is <code>errors.addresses?.[index]?.street?.message</code> — note the optional chaining
+                at each level. Missing any level causes a runtime error when there are no errors.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">EMPTY_ADDRESS defined inside the component</p>
+              <p className="text-sm text-gray-400 mt-1">
+                Define the empty item template outside the component (or with <code>useCallback</code> /{" "}
+                <code>useMemo</code>). An inline object creates a new reference on every render and can cause unexpected{" "}
+                <code>append</code> behaviour.
+              </p>
+            </div>
+          </li>
+        </ul>
+      </section>
+
+      {/* Related */}
+      <section className="border-t border-gray-800 pt-8">
+        <h2 className="text-lg font-semibold mb-4">Related</h2>
+        <div className="flex flex-wrap gap-4 text-sm">
+          <a href="/recipes/nested-fields" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Nested Fields &amp; Sub-components
+          </a>
+          <a href="/recipes/signup-server-errors" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Sign Up with Server Errors
+          </a>
+          <a
+            href="https://react-hook-form.com/docs/usefieldarray"
+            target="_blank"
+            rel="noreferrer"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
+            → RHF useFieldArray docs ↗
+          </a>
+          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → API Reference
+          </a>
+        </div>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/app/recipes/file-upload/page.tsx b/apps/docs/app/recipes/file-upload/page.tsx
new file mode 100644
index 0000000..d7a097b
--- /dev/null
+++ b/apps/docs/app/recipes/file-upload/page.tsx
@@ -0,0 +1,308 @@
+export default function FileUploadPage() {
+  return (
+    <div className="max-w-4xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/recipes" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to Recipes
+        </a>
+      </div>
+
+      <div className="mb-12">
+        <div className="flex items-center gap-3 mb-4">
+          <span className="text-xs font-bold bg-gray-700/50 text-gray-400 border border-gray-600/50 rounded-full px-3 py-1">
+            Tier 3 · Specialized
+          </span>
+          <span className="text-gray-500 text-sm font-mono">Recipe #9</span>
+        </div>
+        <h1 className="text-3xl font-bold mb-3">File Upload</h1>
+        <p className="text-lg text-gray-400">
+          File uploads break the default JSON action model. This recipe shows how to use a FormData action, validate
+          file type and size, show a preview, and surface a loading indicator.
+        </p>
+      </div>
+
+      {/* Why it matters */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-3">Why it matters</h2>
+        <p className="text-gray-400 leading-relaxed">
+          File uploads are fundamentally different from text-field submissions. Files must travel over the wire as{" "}
+          <code>multipart/form-data</code>, not JSON. That means you need a <code>FormDataServerAction</code> instead of
+          the <code>withZod</code> JSON wrapper. Validation also shifts: instead of a Zod schema on an object, you
+          inspect the <code>File</code> object&apos;s <code>size</code>, <code>type</code>, and <code>name</code> on the
+          server.
+        </p>
+        <p className="text-gray-400 leading-relaxed mt-3">
+          Client-side validation (type/size checks before upload) is implemented with a custom <code>schema</code> using
+          Zod&apos;s <code>.refine()</code>. This recipe covers the full pattern: action, form, preview, and a graceful
+          loading state.
+        </p>
+      </section>
+
+      {/* Full Example */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-6">Full Example — Avatar Upload</h2>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            actions.ts — FormData action (arity 2)
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use server'
+
+const ALLOWED_TYPES = ['image/jpeg', 'image/png', 'image/webp']
+const MAX_SIZE_BYTES = 5 * 1024 * 1024  // 5 MB
+
+export async function uploadAvatarAction(
+  prevState: unknown,
+  formData: FormData
+) {
+  const file = formData.get('avatar') as File | null
+
+  if (!file || file.size === 0) {
+    return { errors: { avatar: ['Please select a file'] } }
+  }
+
+  if (file.size > MAX_SIZE_BYTES) {
+    return { errors: { avatar: ['File must be under 5 MB'] } }
+  }
+
+  if (!ALLOWED_TYPES.includes(file.type)) {
+    return { errors: { avatar: ['Only JPEG, PNG, and WebP images are allowed'] } }
+  }
+
+  // Upload to your storage provider (S3, Cloudflare R2, Vercel Blob, etc.)
+  const url = await storage.upload(file)
+
+  // Update the user's profile with the new avatar URL
+  await db.profiles.update({
+    where: { userId: session.userId },
+    data: { avatarUrl: url },
+  })
+
+  return { success: true, url }
+}`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            avatar-upload-form.tsx
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useActionForm } from 'hookform-action'
+import { useRef, useState } from 'react'
+import { z } from 'zod'
+import { uploadAvatarAction } from './actions'
+
+// Client-side schema for early validation (before upload)
+const avatarSchema = z.object({
+  avatar: z
+    .custom<FileList>()
+    .refine((files) => files?.length > 0, 'Please select a file')
+    .refine(
+      (files) => files?.[0]?.size <= 5 * 1024 * 1024,
+      'File must be under 5 MB'
+    )
+    .refine(
+      (files) => ['image/jpeg', 'image/png', 'image/webp'].includes(files?.[0]?.type),
+      'Only JPEG, PNG, and WebP images are allowed'
+    ),
+})
+
+type AvatarResult = {
+  success?: boolean
+  url?: string
+  errors?: { avatar?: string[] }
+}
+
+export function AvatarUploadForm() {
+  const [preview, setPreview] = useState<string | null>(null)
+  const previewUrlRef = useRef<string | null>(null)
+
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isPending, isSubmitSuccessful, actionResult },
+  } = useActionForm<{ avatar: FileList }, AvatarResult>(uploadAvatarAction, {
+    defaultValues: { avatar: undefined as unknown as FileList },
+    schema: avatarSchema,
+    validationMode: 'onChange',
+    onSuccess: (result) => {
+      // Revoke the local preview URL to free memory
+      if (previewUrlRef.current) URL.revokeObjectURL(previewUrlRef.current)
+    },
+  })
+
+  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0]
+    if (!file) return
+
+    // Generate a local preview before uploading
+    if (previewUrlRef.current) URL.revokeObjectURL(previewUrlRef.current)
+    const url = URL.createObjectURL(file)
+    previewUrlRef.current = url
+    setPreview(url)
+  }
+
+  return (
+    <div className="space-y-4">
+      {/* Preview */}
+      {preview && !isSubmitSuccessful && (
+        <div className="w-24 h-24 rounded-full overflow-hidden border-2 border-brand-500">
+          <img src={preview} alt="Preview" className="w-full h-full object-cover" />
+        </div>
+      )}
+
+      {/* Confirmed avatar */}
+      {isSubmitSuccessful && actionResult?.url && (
+        <div className="space-y-2">
+          <div className="w-24 h-24 rounded-full overflow-hidden border-2 border-green-500">
+            <img src={actionResult.url} alt="Your avatar" className="w-full h-full object-cover" />
+          </div>
+          <p className="text-green-400 text-sm">Avatar updated!</p>
+        </div>
+      )}
+
+      <form onSubmit={handleSubmit()}>
+        <div className="space-y-2">
+          <label htmlFor="avatar" className="text-sm font-medium text-gray-300">
+            Choose an image
+          </label>
+          <input
+            id="avatar"
+            type="file"
+            accept="image/jpeg,image/png,image/webp"
+            {...register('avatar', { onChange: handleFileChange })}
+            className="block w-full text-sm text-gray-400 file:mr-4 file:py-2 file:px-4 file:rounded-lg file:border-0 file:bg-brand-600 file:text-white hover:file:bg-brand-500"
+          />
+          {errors.avatar && (
+            <p className="text-red-400 text-sm">{errors.avatar.message}</p>
+          )}
+        </div>
+
+        <button
+          type="submit"
+          disabled={isPending || !preview}
+          className="mt-4 px-4 py-2 bg-brand-600 hover:bg-brand-500 disabled:bg-gray-700 text-white rounded-lg transition-colors"
+        >
+          {isPending ? (
+            <span className="flex items-center gap-2">
+              <svg className="animate-spin h-4 w-4" viewBox="0 0 24 24" aria-hidden="true">
+                <circle cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" fill="none" className="opacity-25" />
+                <path fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" className="opacity-75" />
+              </svg>
+              Uploading…
+            </span>
+          ) : (
+            'Upload Avatar'
+          )}
+        </button>
+      </form>
+    </div>
+  )
+}`}</pre>
+          </div>
+        </div>
+      </section>
+
+      {/* Key Concepts */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">Key Concepts</h2>
+        <div className="space-y-3">
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">FormDataServerAction (arity 2)</code>
+            <p className="text-gray-400 text-sm mt-1">
+              File uploads require the <code>(prevState, formData) =&gt; Promise</code> signature. The hook detects this
+              automatically (by checking the function&apos;s <code>length</code>) and sends the data as{" "}
+              <code>multipart/form-data</code> instead of JSON.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">z.custom&lt;FileList&gt;().refine()</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Zod does not have a built-in file type. Use <code>z.custom&lt;FileList&gt;()</code> with{" "}
+              <code>.refine()</code> for client-side validation. Avoid <code>z.instanceof(File)</code> — it fails in SSR
+              environments where <code>File</code> is not defined.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">URL.createObjectURL + cleanup</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Use <code>URL.createObjectURL</code> for instant image previews. Always call{" "}
+              <code>URL.revokeObjectURL</code> when the preview is no longer needed to prevent memory leaks. Store the
+              URL in a <code>useRef</code> to access it across renders.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">Next.js Server Action file size limit</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Next.js Server Actions have a default body size limit of 1 MB. For larger files, configure{" "}
+              <code>experimental.serverActionsBodySizeLimit</code> in <code>next.config.mjs</code>, or upload directly
+              to your storage provider from the client (signed URL pattern).
+            </p>
+          </div>
+        </div>
+      </section>
+
+      {/* Pitfalls */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">⚠️ Pitfalls</h2>
+        <ul className="space-y-3">
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Using <code>withZod</code> for file uploads
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                <code>withZod</code> serialises data as JSON. Files cannot be serialised to JSON — you will receive an
+                empty object. Always use the raw FormData action signature for file uploads.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Using <code>setValue</code> for file inputs
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                Browser security prevents programmatically setting file input values. Use <code>register</code> normally
+                and listen to <code>onChange</code> for the preview logic. Do not try to control the file input&apos;s
+                value via <code>setValue</code>.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">Forgetting to revoke object URLs</p>
+              <p className="text-sm text-gray-400 mt-1">
+                Every <code>URL.createObjectURL</code> call holds a reference to the file in memory. Revoke it in{" "}
+                <code>onSuccess</code> or in a <code>useEffect</code> cleanup to avoid memory leaks in long-running
+                sessions.
+              </p>
+            </div>
+          </li>
+        </ul>
+      </section>
+
+      {/* Related */}
+      <section className="border-t border-gray-800 pt-8">
+        <h2 className="text-lg font-semibold mb-4">Related</h2>
+        <div className="flex flex-wrap gap-4 text-sm">
+          <a href="/recipes/signup-server-errors" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Sign Up with Server Errors
+          </a>
+          <a href="/recipes/custom-error-mapper" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Custom Error Mapper
+          </a>
+          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → API Reference
+          </a>
+        </div>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/app/recipes/login-form/page.tsx b/apps/docs/app/recipes/login-form/page.tsx
new file mode 100644
index 0000000..2d6daeb
--- /dev/null
+++ b/apps/docs/app/recipes/login-form/page.tsx
@@ -0,0 +1,240 @@
+export default function LoginFormRecipePage() {
+  return (
+    <div className="max-w-4xl mx-auto px-6 py-16">
+      {/* Back */}
+      <div className="mb-8">
+        <a href="/recipes" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to Recipes
+        </a>
+      </div>
+
+      {/* Header */}
+      <div className="mb-12">
+        <div className="flex items-center gap-3 mb-4">
+          <span className="text-xs font-bold bg-red-500/15 text-red-400 border border-red-500/25 rounded-full px-3 py-1">
+            Tier 1 · Must-have
+          </span>
+          <span className="text-gray-500 text-sm font-mono">Recipe #1</span>
+        </div>
+        <h1 className="text-3xl font-bold mb-3">Login Form</h1>
+        <p className="text-lg text-gray-400">
+          The foundation pattern. Learn how <code>withZod</code>, <code>useActionForm</code>, and error display all fit
+          together before moving to more complex recipes.
+        </p>
+        <a
+          href="/examples/login"
+          className="inline-flex items-center gap-1 mt-4 text-sm text-brand-400 hover:text-brand-300 transition-colors"
+        >
+          See live demo →
+        </a>
+      </div>
+
+      {/* Why it matters */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-3">Why it matters</h2>
+        <p className="text-gray-400 leading-relaxed">
+          The login form is the first form every developer builds with this library. It establishes the core mental
+          model: a typed server action wrapped with <code>withZod</code>, a client component calling{" "}
+          <code>useActionForm</code>, and a clean pattern for displaying both client-side validation errors and
+          server-side errors on the same fields.
+        </p>
+        <p className="text-gray-400 leading-relaxed mt-3">
+          Getting this right means understanding the difference between <code>isSubmitting</code> and{" "}
+          <code>isPending</code>, knowing that <code>withZod</code> auto-attaches the schema for client-side inference,
+          and handling the two typical success flows — redirect or in-place success state.
+        </p>
+      </section>
+
+      {/* Full Example */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-6">Full Example</h2>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            actions.ts
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use server'
+import { z } from 'zod'
+import { withZod } from 'hookform-action-core/with-zod'
+
+const loginSchema = z.object({
+  email: z.string().email('Please enter a valid email'),
+  password: z.string().min(8, 'Password must be at least 8 characters'),
+})
+
+export const loginAction = withZod(loginSchema, async (data) => {
+  // data is fully typed: { email: string; password: string }
+
+  // Simulate a credentials check
+  if (data.email === 'wrong@example.com') {
+    return { errors: { email: ['Invalid credentials'] } }
+  }
+
+  // On success: return { success: true } or call redirect()
+  return { success: true }
+})`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            login-form.tsx
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useActionForm } from 'hookform-action'
+import { loginAction } from './actions'
+
+export function LoginForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isPending, isSubmitSuccessful },
+  } = useActionForm(loginAction, {
+    defaultValues: { email: '', password: '' },
+  })
+
+  if (isSubmitSuccessful) {
+    return <p className="text-green-400">Login successful! Redirecting...</p>
+  }
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      <div>
+        <label htmlFor="email">Email</label>
+        <input id="email" type="email" {...register('email')} />
+        {errors.email && <p className="text-red-400">{errors.email.message}</p>}
+      </div>
+
+      <div>
+        <label htmlFor="password">Password</label>
+        <input id="password" type="password" {...register('password')} />
+        {errors.password && <p className="text-red-400">{errors.password.message}</p>}
+      </div>
+
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Signing in…' : 'Sign In'}
+      </button>
+    </form>
+  )
+}`}</pre>
+          </div>
+        </div>
+
+        <div className="bg-blue-500/5 border border-blue-500/20 rounded-lg p-4 text-sm text-gray-400">
+          <span className="text-blue-400 font-medium">Next.js redirect variant: </span>
+          call <code>redirect(&apos;/dashboard&apos;)</code> from <code>next/navigation</code> inside{" "}
+          <code>withZod</code>. The hook treats the thrown redirect as a successful submission —{" "}
+          <code>isSubmitSuccessful</code> will be <code>true</code>, but the page will navigate away before you can
+          render a success state.
+        </div>
+      </section>
+
+      {/* Key Concepts */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">Key Concepts</h2>
+        <div className="space-y-3">
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">withZod(schema, handler)</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Wraps the server action and attaches the Zod schema as <code>action.__schema</code>.{" "}
+              <code>useActionForm</code> reads it automatically for client-side validation. On validation failure,
+              returns <code>{`{ errors: { field: string[] } }`}</code> without ever calling the handler.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">isPending vs isSubmitting</code>
+            <p className="text-gray-400 text-sm mt-1">
+              <code>isPending</code> reflects React&apos;s <code>useTransition</code> — it stays <code>true</code> for
+              the full async round-trip to the server. Use it to disable the submit button. <code>isSubmitting</code> is
+              the synchronous RHF snapshot and may not cover the full window in Next.js transitions.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">handleSubmit()</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Called with no arguments to get the submit handler: <code>{"<form onSubmit={handleSubmit()}>"}</code>.
+              Optionally pass an <code>onValid</code> callback that runs with typed data before the action is called:{" "}
+              <code>{"handleSubmit((data) => console.log(data))"}</code>.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">defaultValues</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Always provide <code>defaultValues</code>. Without them, RHF initialises fields as <code>undefined</code>,
+              which causes React&apos;s uncontrolled-to-controlled warning when the user starts typing, and breaks
+              dirty-field tracking.
+            </p>
+          </div>
+        </div>
+      </section>
+
+      {/* Pitfalls */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">⚠️ Pitfalls</h2>
+        <ul className="space-y-3">
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Using <code>isSubmitting</code> to disable the button
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                Use <code>isPending</code> instead. In Next.js the action runs inside a transition, and{" "}
+                <code>isSubmitting</code> may revert to <code>false</code> before the server response arrives.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Calling <code>redirect()</code> and also returning <code>success: true</code>
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                <code>redirect()</code> throws internally — the return statement is unreachable. Choose one: either
+                redirect or return a result. Doing both is dead code.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Returning errors outside the <code>{`{ errors: { field: string[] } }`}</code> shape
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                The default <code>errorMapper</code> only recognises that exact shape. If your action returns a
+                different format, use a custom <code>errorMapper</code> — see{" "}
+                <a href="/recipes/custom-error-mapper" className="text-brand-400 hover:underline">
+                  Recipe #11
+                </a>
+                .
+              </p>
+            </div>
+          </li>
+        </ul>
+      </section>
+
+      {/* Related */}
+      <section className="border-t border-gray-800 pt-8">
+        <h2 className="text-lg font-semibold mb-4">Related</h2>
+        <div className="flex flex-wrap gap-4 text-sm">
+          <a href="/recipes/signup-server-errors" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Sign Up with Server Errors
+          </a>
+          <a href="/recipes/reset-after-success" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Reset After Success
+          </a>
+          <a href="/examples/login" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Live Example
+          </a>
+          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → API Reference
+          </a>
+        </div>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/app/recipes/modal-form/page.tsx b/apps/docs/app/recipes/modal-form/page.tsx
new file mode 100644
index 0000000..f800245
--- /dev/null
+++ b/apps/docs/app/recipes/modal-form/page.tsx
@@ -0,0 +1,363 @@
+export default function ModalFormPage() {
+  return (
+    <div className="max-w-4xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/recipes" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to Recipes
+        </a>
+      </div>
+
+      <div className="mb-12">
+        <div className="flex items-center gap-3 mb-4">
+          <span className="text-xs font-bold bg-yellow-500/15 text-yellow-400 border border-yellow-500/25 rounded-full px-3 py-1">
+            Tier 2 · Common
+          </span>
+          <span className="text-gray-500 text-sm font-mono">Recipe #7</span>
+        </div>
+        <h1 className="text-3xl font-bold mb-3">Modal / Dialog Form</h1>
+        <p className="text-lg text-gray-400">
+          Forms inside modals have a different lifecycle — they must reset when opened, close on success, and handle
+          focus correctly. This recipe covers the canonical pattern and Shadcn/ui Dialog integration.
+        </p>
+      </div>
+
+      {/* Why it matters */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-3">Why it matters</h2>
+        <p className="text-gray-400 leading-relaxed">
+          A form inside a modal behaves differently from a page-level form. If the modal does not unmount when closed,
+          the form keeps its state — including errors from the last submission. When the user opens it again, they see
+          stale data. When they close it after a success, they may briefly see an empty form before the animation
+          completes.
+        </p>
+        <p className="text-gray-400 leading-relaxed mt-3">
+          This recipe solves these issues with two patterns: the{" "}
+          <strong className="text-gray-200">useEffect reset</strong> pattern (for modals that stay mounted) and the{" "}
+          <strong className="text-gray-200">key remount</strong> pattern (the nuclear option that guarantees a fresh
+          form). It also shows Shadcn/ui <code>Dialog</code> integration.
+        </p>
+      </section>
+
+      {/* Pattern 1 */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-2">Pattern 1 — useEffect reset (stays mounted)</h2>
+        <p className="text-gray-400 text-sm mb-5">
+          Best for modals that are conditionally rendered but not unmounted on close (e.g. animated with CSS opacity).
+          Reset the form when the modal opens and close it on success.
+        </p>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            create-item-modal.tsx
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useEffect } from 'react'
+import { useActionForm } from 'hookform-action'
+import { createItemAction } from './actions'
+
+interface CreateItemModalProps {
+  isOpen: boolean
+  onClose: () => void
+}
+
+export function CreateItemModal({ isOpen, onClose }: CreateItemModalProps) {
+  const {
+    register,
+    handleSubmit,
+    reset,
+    formState: { errors, isPending },
+  } = useActionForm(createItemAction, {
+    defaultValues: { title: '', description: '' },
+    onSuccess: () => {
+      // Step 1: close the modal
+      onClose()
+      // Step 2: reset AFTER close to avoid flash of empty form
+      // We use setTimeout(0) to let the close animation start first
+      setTimeout(() => reset(), 150)
+    },
+  })
+
+  // When the modal opens, clear any leftover state from the previous session
+  useEffect(() => {
+    if (isOpen) reset()
+  }, [isOpen, reset])
+
+  if (!isOpen) return null
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="modal-title"
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/60"
+    >
+      <div className="bg-gray-900 border border-gray-700 rounded-xl p-6 w-full max-w-md">
+        <h2 id="modal-title" className="text-lg font-bold mb-4">
+          Create Item
+        </h2>
+
+        <form onSubmit={handleSubmit()}>
+          <div className="mb-4">
+            <label htmlFor="title" className="block text-sm text-gray-400 mb-1">
+              Title
+            </label>
+            <input
+              id="title"
+              autoFocus
+              {...register('title')}
+              className="w-full bg-gray-800 border border-gray-700 rounded-lg px-3 py-2 text-white"
+            />
+            {errors.title && (
+              <p className="text-red-400 text-sm mt-1">{errors.title.message}</p>
+            )}
+          </div>
+
+          <div className="mb-6">
+            <label htmlFor="description" className="block text-sm text-gray-400 mb-1">
+              Description
+            </label>
+            <textarea
+              id="description"
+              rows={3}
+              {...register('description')}
+              className="w-full bg-gray-800 border border-gray-700 rounded-lg px-3 py-2 text-white"
+            />
+            {errors.description && (
+              <p className="text-red-400 text-sm mt-1">{errors.description.message}</p>
+            )}
+          </div>
+
+          <div className="flex gap-3 justify-end">
+            <button
+              type="button"
+              onClick={onClose}
+              className="px-4 py-2 text-gray-400 hover:text-white transition-colors"
+            >
+              Cancel
+            </button>
+            <button
+              type="submit"
+              disabled={isPending}
+              className="px-4 py-2 bg-brand-600 hover:bg-brand-500 disabled:bg-gray-700 text-white rounded-lg transition-colors"
+            >
+              {isPending ? 'Creating…' : 'Create'}
+            </button>
+          </div>
+        </form>
+      </div>
+    </div>
+  )
+}`}</pre>
+          </div>
+        </div>
+      </section>
+
+      {/* Pattern 2: key remount */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-2">Pattern 2 — key remount (unmount on close)</h2>
+        <p className="text-gray-400 text-sm mb-5">
+          The simplest approach: unmount and remount the form component on every open by passing a <code>key</code> that
+          changes. React destroys and recreates the component, giving you a guaranteed fresh state. Best for modals
+          where no CSS animation is needed.
+        </p>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            parent-component.tsx
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useState } from 'react'
+import { CreateItemModal } from './create-item-modal'
+
+export function ItemList() {
+  const [isOpen, setIsOpen] = useState(false)
+  const [openCount, setOpenCount] = useState(0)
+
+  const handleOpen = () => {
+    setOpenCount((c) => c + 1)  // increment key to force remount
+    setIsOpen(true)
+  }
+
+  return (
+    <>
+      <button onClick={handleOpen}>New Item</button>
+
+      {isOpen && (
+        // key changes on every open → CreateItemModal is remounted with fresh state
+        <CreateItemModal
+          key={openCount}
+          onClose={() => setIsOpen(false)}
+        />
+      )}
+    </>
+  )
+}`}</pre>
+          </div>
+        </div>
+      </section>
+
+      {/* Shadcn/ui Dialog */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-2">Shadcn/ui Dialog integration</h2>
+        <p className="text-gray-400 text-sm mb-5">
+          Shadcn&apos;s <code>Dialog</code> keeps content mounted by default. Use the <code>useEffect</code> reset
+          pattern and wire <code>onOpenChange</code> to close the modal.
+        </p>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            create-item-dialog.tsx
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useEffect } from 'react'
+import { useActionForm } from 'hookform-action'
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogFooter,
+} from '@/components/ui/dialog'
+import { createItemAction } from './actions'
+
+interface CreateItemDialogProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+}
+
+export function CreateItemDialog({ open, onOpenChange }: CreateItemDialogProps) {
+  const {
+    register,
+    handleSubmit,
+    reset,
+    formState: { errors, isPending },
+  } = useActionForm(createItemAction, {
+    defaultValues: { title: '', description: '' },
+    onSuccess: () => {
+      onOpenChange(false)
+      setTimeout(() => reset(), 150)
+    },
+  })
+
+  useEffect(() => {
+    if (open) reset()
+  }, [open, reset])
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Create Item</DialogTitle>
+        </DialogHeader>
+
+        <form id="create-item-form" onSubmit={handleSubmit()}>
+          <div className="space-y-4 py-4">
+            <div>
+              <label htmlFor="title" className="text-sm font-medium">Title</label>
+              <input id="title" {...register('title')} className="w-full mt-1" />
+              {errors.title && <p className="text-red-400 text-sm">{errors.title.message}</p>}
+            </div>
+            <div>
+              <label htmlFor="description" className="text-sm font-medium">Description</label>
+              <textarea id="description" {...register('description')} className="w-full mt-1" />
+              {errors.description && (
+                <p className="text-red-400 text-sm">{errors.description.message}</p>
+              )}
+            </div>
+          </div>
+        </form>
+
+        <DialogFooter>
+          <button type="button" onClick={() => onOpenChange(false)}>Cancel</button>
+          <button type="submit" form="create-item-form" disabled={isPending}>
+            {isPending ? 'Creating…' : 'Create'}
+          </button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}`}</pre>
+          </div>
+        </div>
+      </section>
+
+      {/* Key Concepts */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">Key Concepts</h2>
+        <div className="space-y-3">
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">reset() in useEffect on open</code>
+            <p className="text-gray-400 text-sm mt-1">
+              When the modal opens, reset the form to clear any state from the previous session. This is essential for
+              modals that stay mounted between opens (e.g. animated with CSS).
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">setTimeout before reset on close</code>
+            <p className="text-gray-400 text-sm mt-1">
+              If you call <code>reset()</code> synchronously in <code>onSuccess</code> before closing the modal, the
+              user briefly sees an empty form during the close animation. A small delay prevents the flash.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">autoFocus on first field</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Always add <code>autoFocus</code> to the first input in the modal for accessibility. Screen reader users
+              and keyboard users expect focus to move to the dialog content when it opens.
+            </p>
+          </div>
+        </div>
+      </section>
+
+      {/* Pitfalls */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">⚠️ Pitfalls</h2>
+        <ul className="space-y-3">
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">Hiding the modal with CSS instead of unmounting</p>
+              <p className="text-sm text-gray-400 mt-1">
+                If you use <code>display: none</code> or <code>visibility: hidden</code> to hide the modal, the form
+                component stays mounted and retains all its state. The user will see stale errors and values on the next
+                open. Always pair this approach with an explicit <code>useEffect</code> reset.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Using <code>isSubmitSuccessful</code> to close the modal
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                <code>isSubmitSuccessful</code> does not give you access to the action result. Prefer{" "}
+                <code>onSuccess</code>, which receives the full typed result and is a cleaner place to trigger{" "}
+                <code>onClose()</code>.
+              </p>
+            </div>
+          </li>
+        </ul>
+      </section>
+
+      {/* Related */}
+      <section className="border-t border-gray-800 pt-8">
+        <h2 className="text-lg font-semibold mb-4">Related</h2>
+        <div className="flex flex-wrap gap-4 text-sm">
+          <a href="/recipes/reset-after-success" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Reset After Success
+          </a>
+          <a href="/recipes/edit-server-data" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Edit Form with Server Data
+          </a>
+          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → API Reference
+          </a>
+        </div>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/app/recipes/multi-step-wizard/page.tsx b/apps/docs/app/recipes/multi-step-wizard/page.tsx
new file mode 100644
index 0000000..5f2bc31
--- /dev/null
+++ b/apps/docs/app/recipes/multi-step-wizard/page.tsx
@@ -0,0 +1,351 @@
+export default function MultiStepWizardPage() {
+  return (
+    <div className="max-w-4xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/recipes" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to Recipes
+        </a>
+      </div>
+
+      <div className="mb-12">
+        <div className="flex items-center gap-3 mb-4">
+          <span className="text-xs font-bold bg-red-500/15 text-red-400 border border-red-500/25 rounded-full px-3 py-1">
+            Tier 1 · Must-have
+          </span>
+          <span className="text-xs text-brand-400 font-medium">★ Featured</span>
+          <span className="text-gray-500 text-sm font-mono">Recipe #5</span>
+        </div>
+        <h1 className="text-3xl font-bold mb-3">Multi-Step Wizard</h1>
+        <p className="text-lg text-gray-400">
+          Per-step validation, sessionStorage-backed progress, and safe cleanup on final submit — the most complete
+          demonstration of what makes this library different.
+        </p>
+        <a
+          href="/examples/wizard"
+          className="inline-flex items-center gap-1 mt-4 text-sm text-brand-400 hover:text-brand-300 transition-colors"
+        >
+          See live demo →
+        </a>
+      </div>
+
+      {/* Why it matters */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-3">Why it matters</h2>
+        <p className="text-gray-400 leading-relaxed">
+          Multi-step wizards are notoriously painful to implement: you need to validate only the current step&apos;s
+          fields before advancing, persist progress so the user can close the tab and come back, and cleanly submit all
+          steps&apos; data in a single action at the end.
+        </p>
+        <p className="text-gray-400 leading-relaxed mt-3">
+          <code>hookform-action</code> solves this with a single hook instance spanning all steps.
+          <code>trigger(fields)</code> validates a subset of fields without submitting. <code>persistKey</code>{" "}
+          automatically serialises form state to <code>sessionStorage</code> on every change. And{" "}
+          <code>clearPersistedData()</code> removes the draft cleanly on success. No external state manager needed.
+        </p>
+      </section>
+
+      {/* Full Example */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-6">Full Example</h2>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            actions.ts
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use server'
+import { z } from 'zod'
+import { withZod } from 'hookform-action-core/with-zod'
+
+// Single schema covering all wizard steps
+const onboardingSchema = z.object({
+  // Step 1: Personal Info
+  firstName: z.string().min(2, 'First name must be at least 2 characters'),
+  lastName:  z.string().min(2, 'Last name must be at least 2 characters'),
+  email:     z.string().email('Enter a valid email address'),
+  // Step 2: Company
+  company: z.string().min(1, 'Company name is required'),
+  role:    z.string().min(1, 'Role is required'),
+  // Step 3: Plan
+  plan: z.enum(['free', 'pro', 'enterprise'], {
+    errorMap: () => ({ message: 'Please select a plan' }),
+  }),
+})
+
+export const onboardingAction = withZod(onboardingSchema, async (data) => {
+  // All fields are available and typed here
+  await createAccount(data)
+  return { success: true }
+})`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            wizard-form.tsx
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useActionForm } from 'hookform-action'
+import { useState } from 'react'
+import { onboardingAction } from './actions'
+
+// Map each step index to the fields it owns
+const STEP_FIELDS = {
+  0: ['firstName', 'lastName', 'email'],
+  1: ['company', 'role'],
+  2: ['plan'],
+} as const
+
+export function OnboardingWizard() {
+  const [step, setStep] = useState(0)
+
+  const {
+    register,
+    handleSubmit,
+    trigger,
+    clearPersistedData,
+    formState: { errors, isPending, isSubmitSuccessful },
+  } = useActionForm(onboardingAction, {
+    defaultValues: {
+      firstName: '', lastName: '', email: '',
+      company: '', role: '',
+      plan: '',
+    },
+    // Automatically save progress to sessionStorage
+    persistKey: 'onboarding-wizard',
+    persistDebounce: 250,
+    onSuccess: () => {
+      // Remove the draft once the wizard is complete
+      clearPersistedData()
+    },
+  })
+
+  // Validate only the current step's fields before advancing
+  const handleNext = async () => {
+    const fields = STEP_FIELDS[step as 0 | 1 | 2]
+    const valid = await trigger(fields as never[])
+    if (valid) setStep((s) => s + 1)
+  }
+
+  if (isSubmitSuccessful) {
+    return (
+      <div className="text-center py-16">
+        <p className="text-2xl font-bold text-green-400">🎉 Welcome aboard!</p>
+        <p className="text-gray-400 mt-2">Your account is ready.</p>
+      </div>
+    )
+  }
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      {/* Progress indicator */}
+      <div className="flex gap-2 mb-8">
+        {['Personal', 'Company', 'Plan'].map((label, i) => (
+          <div key={label} className="flex items-center gap-2 flex-1">
+            <div
+              className={
+                i <= step
+                  ? 'w-6 h-6 rounded-full bg-brand-600 text-white text-xs flex items-center justify-center'
+                  : 'w-6 h-6 rounded-full bg-gray-800 text-gray-500 text-xs flex items-center justify-center'
+              }
+            >
+              {i + 1}
+            </div>
+            <span className={i <= step ? 'text-sm text-gray-200' : 'text-sm text-gray-600'}>
+              {label}
+            </span>
+          </div>
+        ))}
+      </div>
+
+      {/* Step 1 */}
+      {step === 0 && (
+        <div className="space-y-4">
+          <div>
+            <label>First Name</label>
+            <input {...register('firstName')} />
+            {errors.firstName && <p className="text-red-400">{errors.firstName.message}</p>}
+          </div>
+          <div>
+            <label>Last Name</label>
+            <input {...register('lastName')} />
+            {errors.lastName && <p className="text-red-400">{errors.lastName.message}</p>}
+          </div>
+          <div>
+            <label>Email</label>
+            <input type="email" {...register('email')} />
+            {errors.email && <p className="text-red-400">{errors.email.message}</p>}
+          </div>
+        </div>
+      )}
+
+      {/* Step 2 */}
+      {step === 1 && (
+        <div className="space-y-4">
+          <div>
+            <label>Company</label>
+            <input {...register('company')} />
+            {errors.company && <p className="text-red-400">{errors.company.message}</p>}
+          </div>
+          <div>
+            <label>Role</label>
+            <input {...register('role')} />
+            {errors.role && <p className="text-red-400">{errors.role.message}</p>}
+          </div>
+        </div>
+      )}
+
+      {/* Step 3 */}
+      {step === 2 && (
+        <div className="space-y-3">
+          <label>Choose a plan</label>
+          {(['free', 'pro', 'enterprise'] as const).map((p) => (
+            <label key={p} className="flex items-center gap-2">
+              <input type="radio" value={p} {...register('plan')} />
+              {p.charAt(0).toUpperCase() + p.slice(1)}
+            </label>
+          ))}
+          {errors.plan && <p className="text-red-400">{errors.plan.message}</p>}
+        </div>
+      )}
+
+      {/* Navigation */}
+      <div className="flex gap-3 mt-8">
+        {step > 0 && (
+          <button type="button" onClick={() => setStep((s) => s - 1)}>
+            Back
+          </button>
+        )}
+        {step < 2 ? (
+          <button type="button" onClick={handleNext}>
+            Next
+          </button>
+        ) : (
+          <button type="submit" disabled={isPending}>
+            {isPending ? 'Creating account…' : 'Complete Setup'}
+          </button>
+        )}
+      </div>
+    </form>
+  )
+}`}</pre>
+          </div>
+        </div>
+      </section>
+
+      {/* Key Concepts */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">Key Concepts</h2>
+        <div className="space-y-3">
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">trigger(fields)</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Runs client-side validation on a specific subset of fields and returns <code>true</code> if all pass. Pass
+              only the fields of the current step to avoid surfacing errors from future steps prematurely. Calling{" "}
+              <code>trigger()</code> with no arguments validates everything — avoid this between steps.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">persistKey + persistDebounce</code>
+            <p className="text-gray-400 text-sm mt-1">
+              <code>persistKey</code> enables automatic <code>sessionStorage</code> persistence. The form state is saved
+              under this key on every change (debounced by <code>persistDebounce</code> ms, default 300) and restored on
+              mount. The user can close the browser and return to find their progress intact.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">clearPersistedData()</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Manually removes the persisted state for this form&apos;s <code>persistKey</code>. Always call it in{" "}
+              <code>onSuccess</code> after wizard completion — otherwise the next user to open the form (or the current
+              user if they start again) will see the completed wizard&apos;s data pre-filled.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">Single hook instance across all steps</code>
+            <p className="text-gray-400 text-sm mt-1">
+              All fields are registered in one <code>useActionForm</code> call. The active step is controlled by plain{" "}
+              <code>useState</code>. This means the entire form state is consistent at all times, and the final submit
+              sends all fields in one action call.
+            </p>
+          </div>
+        </div>
+      </section>
+
+      {/* Pitfalls */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">⚠️ Pitfalls</h2>
+        <ul className="space-y-3">
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Calling <code>trigger()</code> without arguments between steps
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                This validates all fields — including ones in future steps the user has not seen yet — and shows errors
+                prematurely. Always pass the explicit list of fields for the current step.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Using <code>isSubmitSuccessful</code> to advance between steps
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                <code>isSubmitSuccessful</code> only becomes <code>true</code> after the final action call succeeds. Use
+                it exclusively as the guard for the completion screen. Step navigation is purely local state.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Forgetting <code>clearPersistedData()</code> after submission
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                The persistence happens automatically on every change. After success, the persisted data is not removed
+                automatically — you must call <code>clearPersistedData()</code> in <code>onSuccess</code>, or the next
+                visit to the form will restore the completed wizard.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">The current step is not persisted by default</p>
+              <p className="text-sm text-gray-400 mt-1">
+                <code>persistKey</code> saves field values, not the step index. If the user returns after a refresh, the
+                form starts at step 0 with the field values intact. To also persist the step, store it in{" "}
+                <code>sessionStorage</code> alongside the form, or include a hidden <code>currentStep</code> field.
+              </p>
+            </div>
+          </li>
+        </ul>
+      </section>
+
+      {/* Related */}
+      <section className="border-t border-gray-800 pt-8">
+        <h2 className="text-lg font-semibold mb-4">Related</h2>
+        <div className="flex flex-wrap gap-4 text-sm">
+          <a href="/recipes/reset-after-success" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Reset After Success
+          </a>
+          <a href="/recipes/signup-server-errors" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Sign Up with Server Errors
+          </a>
+          <a href="/examples/wizard" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Live Wizard Example
+          </a>
+          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → API Reference
+          </a>
+        </div>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/app/recipes/nested-fields/page.tsx b/apps/docs/app/recipes/nested-fields/page.tsx
new file mode 100644
index 0000000..fea46a1
--- /dev/null
+++ b/apps/docs/app/recipes/nested-fields/page.tsx
@@ -0,0 +1,339 @@
+export default function NestedFieldsPage() {
+  return (
+    <div className="max-w-4xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/recipes" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to Recipes
+        </a>
+      </div>
+
+      <div className="mb-12">
+        <div className="flex items-center gap-3 mb-4">
+          <span className="text-xs font-bold bg-gray-700/50 text-gray-400 border border-gray-600/50 rounded-full px-3 py-1">
+            Tier 3 · Specialized
+          </span>
+          <span className="text-gray-500 text-sm font-mono">Recipe #10</span>
+        </div>
+        <h1 className="text-3xl font-bold mb-3">Nested Fields &amp; Sub-components</h1>
+        <p className="text-lg text-gray-400">
+          Compose large forms from smaller, focused components using <code>useFormContext</code> — without passing{" "}
+          <code>register</code>, <code>errors</code>, or <code>control</code> as props through every level.
+        </p>
+      </div>
+
+      {/* Why it matters */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-3">Why it matters</h2>
+        <p className="text-gray-400 leading-relaxed">
+          Large forms — checkout, onboarding, profile settings — are easier to maintain when split into focused
+          sub-components. But React Hook Form&apos;s <code>register</code>, <code>control</code>, and{" "}
+          <code>formState</code> normally need to be prop-drilled down the tree, which creates tight coupling and
+          verbose component signatures.
+        </p>
+        <p className="text-gray-400 leading-relaxed mt-3">
+          The <code>{"<Form>"}</code> component from <code>hookform-action</code> wraps its children in React Hook
+          Form&apos;s <code>FormProvider</code> automatically. Any component inside the tree can call{" "}
+          <code>useFormContext()</code> to access the full RHF API without any prop passing.
+        </p>
+      </section>
+
+      {/* Full Example */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-6">Full Example — Checkout Form</h2>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            actions.ts
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use server'
+import { z } from 'zod'
+import { withZod } from 'hookform-action-core/with-zod'
+
+export const checkoutSchema = z.object({
+  customer: z.object({
+    name:  z.string().min(1, 'Name is required'),
+    email: z.string().email('Enter a valid email'),
+  }),
+  shipping: z.object({
+    street:  z.string().min(1, 'Street is required'),
+    city:    z.string().min(1, 'City is required'),
+    country: z.string().min(2, 'Select a country'),
+  }),
+})
+
+export type CheckoutValues = z.infer<typeof checkoutSchema>
+
+export const checkoutAction = withZod(checkoutSchema, async (data) => {
+  await processOrder(data)
+  return { success: true }
+})`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            checkout-form.tsx — Root component
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useActionForm } from 'hookform-action'
+import { Form } from 'hookform-action-core'  // or from 'hookform-action'
+import { checkoutAction } from './actions'
+import type { CheckoutValues } from './actions'
+import { CustomerSection } from './CustomerSection'
+import { ShippingSection } from './ShippingSection'
+
+export function CheckoutForm() {
+  // useActionForm returns the full RHF API plus action integration
+  const form = useActionForm<CheckoutValues>(checkoutAction, {
+    defaultValues: {
+      customer: { name: '', email: '' },
+      shipping: { street: '', city: '', country: '' },
+    },
+  })
+
+  return (
+    // <Form> automatically wraps children in <FormProvider>
+    // Sub-components can use useFormContext() without any prop passing
+    <Form form={form}>
+      <CustomerSection />
+      <ShippingSection />
+
+      <button
+        type="submit"
+        disabled={form.formState.isPending}
+        className="w-full py-3 bg-brand-600 hover:bg-brand-500 text-white rounded-lg font-medium"
+      >
+        {form.formState.isPending ? 'Processing…' : 'Place Order'}
+      </button>
+    </Form>
+  )
+}`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            CustomerSection.tsx — Sub-component
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useFormContext } from 'react-hook-form'
+import type { CheckoutValues } from './actions'
+
+export function CustomerSection() {
+  // No props needed — reads form context from the parent <Form>
+  const {
+    register,
+    formState: { errors },
+  } = useFormContext<CheckoutValues>()
+
+  return (
+    <section className="mb-6">
+      <h3 className="text-lg font-semibold mb-4">Customer Info</h3>
+
+      <div className="space-y-4">
+        <div>
+          <label htmlFor="name" className="text-sm text-gray-400">Full Name</label>
+          <input
+            id="name"
+            {...register('customer.name')}   // dot-notation for nested path
+            placeholder="Jane Doe"
+          />
+          {errors.customer?.name && (
+            <p className="text-red-400 text-sm">{errors.customer.name.message}</p>
+          )}
+        </div>
+
+        <div>
+          <label htmlFor="email" className="text-sm text-gray-400">Email</label>
+          <input
+            id="email"
+            type="email"
+            {...register('customer.email')}
+            placeholder="jane@example.com"
+          />
+          {errors.customer?.email && (
+            <p className="text-red-400 text-sm">{errors.customer.email.message}</p>
+          )}
+        </div>
+      </div>
+    </section>
+  )
+}`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            ShippingSection.tsx — Sub-component with Controller
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { Controller, useFormContext } from 'react-hook-form'
+import type { CheckoutValues } from './actions'
+
+export function ShippingSection() {
+  const {
+    register,
+    control,    // ← needed for Controller / useFieldArray in sub-components
+    formState: { errors },
+  } = useFormContext<CheckoutValues>()
+
+  return (
+    <section className="mb-6">
+      <h3 className="text-lg font-semibold mb-4">Shipping Address</h3>
+
+      <div className="space-y-4">
+        <div>
+          <label className="text-sm text-gray-400">Street</label>
+          <input {...register('shipping.street')} placeholder="123 Main St" />
+          {errors.shipping?.street && (
+            <p className="text-red-400 text-sm">{errors.shipping.street.message}</p>
+          )}
+        </div>
+
+        <div className="grid grid-cols-2 gap-3">
+          <div>
+            <label className="text-sm text-gray-400">City</label>
+            <input {...register('shipping.city')} placeholder="New York" />
+            {errors.shipping?.city && (
+              <p className="text-red-400 text-sm">{errors.shipping.city.message}</p>
+            )}
+          </div>
+
+          <div>
+            <label className="text-sm text-gray-400">Country</label>
+            {/* Controller example — for custom select components */}
+            <Controller
+              name="shipping.country"
+              control={control}
+              render={({ field }) => (
+                <select {...field}>
+                  <option value="">Select…</option>
+                  <option value="US">United States</option>
+                  <option value="BR">Brazil</option>
+                </select>
+              )}
+            />
+            {errors.shipping?.country && (
+              <p className="text-red-400 text-sm">{errors.shipping.country.message}</p>
+            )}
+          </div>
+        </div>
+      </div>
+    </section>
+  )
+}`}</pre>
+          </div>
+        </div>
+      </section>
+
+      {/* Key Concepts */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">Key Concepts</h2>
+        <div className="space-y-3">
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">{`<Form form={form}>`} — automatic FormProvider</code>
+            <p className="text-gray-400 text-sm mt-1">
+              The <code>{"<Form>"}</code> component from <code>hookform-action</code> wraps children in RHF&apos;s{" "}
+              <code>FormProvider</code> automatically. You do not need to add <code>FormProvider</code> yourself. All
+              sub-components in the tree can call <code>useFormContext()</code>.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">useFormContext&lt;TFieldValues&gt;()</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Pass the form&apos;s type parameter to get typed access to <code>register</code>, <code>errors</code>, and{" "}
+              <code>control</code>. Without the generic, you get <code>FieldValues</code> (essentially <code>any</code>
+              ).
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">Dot-notation for nested paths</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Register deeply nested fields with dot notation: <code>register(&apos;customer.name&apos;)</code>. RHF
+              will collect these into a properly structured object. The Zod schema&apos;s shape must match exactly.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">control in sub-components</code>
+            <p className="text-gray-400 text-sm mt-1">
+              <code>control</code> is needed for <code>Controller</code> and <code>useFieldArray</code> inside
+              sub-components. Get it from <code>useFormContext()</code> — not passed as a prop from the parent.
+            </p>
+          </div>
+        </div>
+      </section>
+
+      {/* Pitfalls */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">⚠️ Pitfalls</h2>
+        <ul className="space-y-3">
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Double-wrapping with <code>FormProvider</code>
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                <code>{"<Form>"}</code> already includes a <code>FormProvider</code>. Adding another one around it
+                creates nested contexts and causes <code>useFormContext()</code> to read from the innermost (empty)
+                provider.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Sub-components using <code>useFormContext</code> outside <code>{"<Form>"}</code>
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                If a sub-component is rendered outside the <code>{"<Form>"}</code> tree (e.g. in a portal, a story, or a
+                test), <code>useFormContext()</code> will return <code>undefined</code> and throw. Wrap test cases in a
+                mock <code>FormProvider</code>.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">Mismatched dot-notation path and schema shape</p>
+              <p className="text-sm text-gray-400 mt-1">
+                If you register <code>customer.name</code> but the Zod schema expects <code>customerName</code> (flat),
+                the field will not validate correctly and the error path will not match. Keep the schema and the{" "}
+                <code>register</code> paths in sync.
+              </p>
+            </div>
+          </li>
+        </ul>
+      </section>
+
+      {/* Related */}
+      <section className="border-t border-gray-800 pt-8">
+        <h2 className="text-lg font-semibold mb-4">Related</h2>
+        <div className="flex flex-wrap gap-4 text-sm">
+          <a href="/recipes/field-array" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Dynamic Fields with useFieldArray
+          </a>
+          <a href="/recipes/multi-step-wizard" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Multi-Step Wizard
+          </a>
+          <a
+            href="https://react-hook-form.com/docs/useformcontext"
+            target="_blank"
+            rel="noreferrer"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
+            → RHF useFormContext docs ↗
+          </a>
+          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → API Reference
+          </a>
+        </div>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/app/recipes/optimistic-ui/page.tsx b/apps/docs/app/recipes/optimistic-ui/page.tsx
new file mode 100644
index 0000000..8b138a9
--- /dev/null
+++ b/apps/docs/app/recipes/optimistic-ui/page.tsx
@@ -0,0 +1,281 @@
+export default function OptimisticUIPage() {
+  return (
+    <div className="max-w-4xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/recipes" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to Recipes
+        </a>
+      </div>
+
+      <div className="mb-12">
+        <div className="flex items-center gap-3 mb-4">
+          <span className="text-xs font-bold bg-yellow-500/15 text-yellow-400 border border-yellow-500/25 rounded-full px-3 py-1">
+            Tier 2 · Common
+          </span>
+          <span className="text-xs text-cyan-400 font-medium">⚡ Advanced feature</span>
+          <span className="text-gray-500 text-sm font-mono">Recipe #6</span>
+        </div>
+        <h1 className="text-3xl font-bold mb-3">Optimistic UI Updates</h1>
+        <p className="text-lg text-gray-400">
+          Show the result of a submission instantly — before the server responds — and roll back automatically if
+          something goes wrong.
+        </p>
+        <a
+          href="/examples/optimistic"
+          className="inline-flex items-center gap-1 mt-4 text-sm text-cyan-400 hover:text-cyan-300 transition-colors"
+        >
+          See live demo →
+        </a>
+      </div>
+
+      {/* Why it matters */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-3">Why it matters</h2>
+        <p className="text-gray-400 leading-relaxed">
+          Optimistic UI is the difference between a form that feels fast and one that feels slow. Instead of waiting
+          500ms for the server to respond before updating the list, you project the expected result immediately and
+          confirm (or roll back) once the server replies.
+        </p>
+        <p className="text-gray-400 leading-relaxed mt-3">
+          <code>hookform-action</code> implements this via React&apos;s <code>useOptimistic</code> (React 19) with a
+          fallback for React 18. You provide an <code>optimisticData</code> reducer that produces the projected state
+          from the current data and the form values. The hook handles the transition, confirmation, and rollback
+          automatically.
+        </p>
+      </section>
+
+      {/* Full Example */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-6">Full Example — Optimistic Todo List</h2>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            actions.ts
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use server'
+
+export interface Todo {
+  id: string
+  text: string
+  done: boolean
+}
+
+// In-memory store for demo purposes
+let todos: Todo[] = [
+  { id: '1', text: 'Read the docs', done: true },
+  { id: '2', text: 'Build something', done: false },
+]
+
+export async function addTodoAction(raw: unknown) {
+  // Simulate network latency
+  await new Promise((r) => setTimeout(r, 1200))
+
+  const data = raw as { text: string }
+
+  if (!data.text?.trim()) {
+    return { errors: { text: ['Todo text is required'] }, todos }
+  }
+
+  // Type 'fail' to simulate a server error and trigger rollback
+  if (data.text.toLowerCase().includes('fail')) {
+    throw new Error('Server error — optimistic update will be rolled back.')
+  }
+
+  const newTodo: Todo = {
+    id: crypto.randomUUID(),
+    text: data.text.trim(),
+    done: false,
+  }
+
+  todos = [...todos, newTodo]
+  return { todos }
+}`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            todo-form.tsx
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useActionForm } from 'hookform-action'
+import { type Todo, addTodoAction } from './actions'
+
+type AddTodoResult = { todos: Todo[]; errors?: { text?: string[] } }
+
+const initialTodos: Todo[] = [
+  { id: '1', text: 'Read the docs', done: true },
+  { id: '2', text: 'Build something', done: false },
+]
+
+export function TodoForm() {
+  const {
+    register,
+    handleSubmit,
+    reset,
+    formState: { errors, isPending, actionResult },
+    optimistic,
+  } = useActionForm<{ text: string }, AddTodoResult, Todo[]>(addTodoAction, {
+    defaultValues: { text: '' },
+
+    // ── Optimistic UI configuration ─────────────────────────────
+    optimisticKey: 'todos',
+
+    // Initial "confirmed" data before any submissions
+    optimisticInitial: initialTodos,
+
+    // Reducer: given the current list and the submitted values,
+    // return the projected list to show immediately
+    optimisticData: (current, values) => [
+      ...current,
+      { id: \`temp-\${Date.now()}\`, text: values.text, done: false },
+    ],
+    // ────────────────────────────────────────────────────────────
+
+    onSuccess: () => reset(),
+  })
+
+  // Decide which data to render:
+  //   • While the action is in flight → show the optimistic (projected) list
+  //   • After the action resolves   → show the confirmed list from the server
+  const confirmedTodos = actionResult?.todos ?? initialTodos
+  const todos = optimistic?.isPending
+    ? (optimistic.data ?? confirmedTodos)
+    : confirmedTodos
+
+  return (
+    <div>
+      <ul>
+        {todos.map((todo) => (
+          <li
+            key={todo.id}
+            className={
+              todo.id.startsWith('temp-')
+                ? 'opacity-60 italic text-brand-300'  // optimistic item style
+                : 'text-gray-200'
+            }
+          >
+            {todo.done ? '✅' : '⬜'} {todo.text}
+            {todo.id.startsWith('temp-') && ' (saving…)'}
+          </li>
+        ))}
+      </ul>
+
+      <form onSubmit={handleSubmit()} className="mt-4 flex gap-2">
+        <input
+          {...register('text')}
+          placeholder="New todo…"
+          disabled={isPending}
+        />
+        {errors.text && <p className="text-red-400">{errors.text.message}</p>}
+        <button type="submit" disabled={isPending}>Add</button>
+      </form>
+    </div>
+  )
+}`}</pre>
+          </div>
+        </div>
+      </section>
+
+      {/* Key Concepts */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">Key Concepts</h2>
+        <div className="space-y-3">
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">optimisticData (reducer)</code>
+            <p className="text-gray-400 text-sm mt-1">
+              A pure function <code>(currentData, formValues) =&gt; newData</code> that computes the projected state. It
+              runs synchronously on submit — before the server responds. Keep it fast and side-effect-free.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">optimistic.data vs actionResult</code>
+            <p className="text-gray-400 text-sm mt-1">
+              <code>optimistic.data</code> is the projected state (may contain temporary items with fake IDs).{" "}
+              <code>actionResult</code> is the confirmed state returned by the server. Use the pattern shown above:
+              prefer <code>optimistic.data</code> while <code>optimistic.isPending</code> is true, then switch to{" "}
+              <code>actionResult</code>.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">Automatic rollback on error</code>
+            <p className="text-gray-400 text-sm mt-1">
+              When the action throws, the hook automatically reverts <code>optimistic.data</code> to the last confirmed
+              state. You can also trigger a manual rollback via <code>optimistic.rollback()</code> for
+              business-logic-driven reversals.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">React 18 / React 19 compatibility</code>
+            <p className="text-gray-400 text-sm mt-1">
+              On React 19 the hook uses the native <code>useOptimistic</code> API. On React 18 it uses a local state
+              fallback. The behaviour is identical — you don&apos;t need to change any code when upgrading React.
+            </p>
+          </div>
+        </div>
+      </section>
+
+      {/* Pitfalls */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">⚠️ Pitfalls</h2>
+        <ul className="space-y-3">
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Rendering <code>optimistic.data</code> after the action resolves
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                After the action succeeds, <code>optimistic.data</code> still contains the projected state with
+                temporary IDs. Always switch to <code>actionResult</code> once <code>optimistic.isPending</code> is{" "}
+                <code>false</code>.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Inline object literal for <code>optimisticInitial</code>
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                Define <code>optimisticInitial</code> outside the component or use <code>useMemo</code>. An inline array
+                literal creates a new reference on every render and resets the optimistic state unexpectedly.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Forgetting <code>reset()</code> in <code>onSuccess</code>
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                After a successful add, the text input stays filled. Call <code>reset()</code> in <code>onSuccess</code>{" "}
+                to clear the input so the user can type the next item immediately.
+              </p>
+            </div>
+          </li>
+        </ul>
+      </section>
+
+      {/* Related */}
+      <section className="border-t border-gray-800 pt-8">
+        <h2 className="text-lg font-semibold mb-4">Related</h2>
+        <div className="flex flex-wrap gap-4 text-sm">
+          <a href="/recipes/reset-after-success" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Reset After Success
+          </a>
+          <a href="/examples/optimistic" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Live Optimistic Example
+          </a>
+          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → API Reference
+          </a>
+        </div>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/app/recipes/page.tsx b/apps/docs/app/recipes/page.tsx
new file mode 100644
index 0000000..d81f799
--- /dev/null
+++ b/apps/docs/app/recipes/page.tsx
@@ -0,0 +1,253 @@
+export default function RecipesPage() {
+  return (
+    <div className="max-w-4xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to docs
+        </a>
+      </div>
+
+      <div className="mb-14">
+        <div className="inline-flex items-center gap-2 bg-brand-500/10 text-brand-400 border border-brand-500/20 rounded-full px-4 py-1.5 text-sm font-medium mb-6">
+          Recipes
+        </div>
+        <h1 className="text-3xl font-bold mb-4">Recipes &amp; Common Patterns</h1>
+        <p className="text-lg text-gray-400 max-w-2xl">
+          Complete, copy-paste patterns for the most common <code>hookform-action</code> use cases. Each recipe includes
+          a working server action, a typed client component, key concepts, and pitfalls to avoid.
+        </p>
+      </div>
+
+      {/* ── Tier 1: Must-have ──────────────────────────────────── */}
+      <section className="mb-14">
+        <div className="flex items-center gap-3 mb-3">
+          <h2 className="text-xl font-bold">Start Here</h2>
+          <span className="text-xs font-bold bg-red-500/15 text-red-400 border border-red-500/25 rounded-full px-3 py-1">
+            Tier 1 · Must-have
+          </span>
+        </div>
+        <p className="text-gray-500 text-sm mb-6">
+          These five recipes cover the patterns every app needs. Learn them first.
+        </p>
+        <div className="grid sm:grid-cols-2 gap-4">
+          <a
+            href="/recipes/login-form"
+            className="group block bg-gray-900 border border-gray-800 hover:border-brand-500/50 rounded-xl p-5 transition-colors"
+          >
+            <div className="flex items-center gap-2 mb-2">
+              <span className="text-xs text-gray-500 font-mono">#1</span>
+            </div>
+            <h3 className="font-semibold text-white group-hover:text-brand-400 transition-colors mb-1">Login Form</h3>
+            <p className="text-sm text-gray-400">
+              The foundation pattern: <code>withZod</code> action, <code>useActionForm</code>, <code>isPending</code>,
+              and error display.
+            </p>
+          </a>
+
+          <a
+            href="/recipes/signup-server-errors"
+            className="group block bg-gray-900 border border-gray-800 hover:border-brand-500/50 rounded-xl p-5 transition-colors"
+          >
+            <div className="flex items-center gap-2 mb-2">
+              <span className="text-xs text-gray-500 font-mono">#2</span>
+            </div>
+            <h3 className="font-semibold text-white group-hover:text-brand-400 transition-colors mb-1">
+              Sign Up with Server Errors
+            </h3>
+            <p className="text-sm text-gray-400">
+              Business validation errors from the server mapped back to specific form fields.
+            </p>
+          </a>
+
+          <a
+            href="/recipes/reset-after-success"
+            className="group block bg-gray-900 border border-gray-800 hover:border-brand-500/50 rounded-xl p-5 transition-colors"
+          >
+            <div className="flex items-center gap-2 mb-2">
+              <span className="text-xs text-gray-500 font-mono">#3</span>
+            </div>
+            <h3 className="font-semibold text-white group-hover:text-brand-400 transition-colors mb-1">
+              Reset After Success
+            </h3>
+            <p className="text-sm text-gray-400">
+              Three canonical patterns: redirect, in-place reset with <code>onSuccess</code>, and{" "}
+              <code>isSubmitSuccessful</code> guard.
+            </p>
+          </a>
+
+          <a
+            href="/recipes/edit-server-data"
+            className="group block bg-gray-900 border border-gray-800 hover:border-brand-500/50 rounded-xl p-5 transition-colors"
+          >
+            <div className="flex items-center gap-2 mb-2">
+              <span className="text-xs text-gray-500 font-mono">#4</span>
+            </div>
+            <h3 className="font-semibold text-white group-hover:text-brand-400 transition-colors mb-1">
+              Edit Form with Server Data
+            </h3>
+            <p className="text-sm text-gray-400">
+              Pre-populate from a Server Component, track dirty fields, and revalidate on success.
+            </p>
+          </a>
+
+          <a
+            href="/recipes/multi-step-wizard"
+            className="group block bg-gray-900 border border-gray-800 hover:border-brand-500/50 rounded-xl p-5 transition-colors sm:col-span-2"
+          >
+            <div className="flex items-center gap-2 mb-2">
+              <span className="text-xs text-gray-500 font-mono">#5</span>
+              <span className="text-xs text-brand-400 font-medium">★ Featured</span>
+            </div>
+            <h3 className="font-semibold text-white group-hover:text-brand-400 transition-colors mb-1">
+              Multi-Step Wizard
+            </h3>
+            <p className="text-sm text-gray-400">
+              Per-step validation with <code>trigger()</code>, sessionStorage persistence with <code>persistKey</code>,
+              and safe progress clearing on submit.
+            </p>
+          </a>
+        </div>
+      </section>
+
+      {/* ── Tier 2: Common ────────────────────────────────────── */}
+      <section className="mb-14">
+        <div className="flex items-center gap-3 mb-3">
+          <h2 className="text-xl font-bold">Intermediate Patterns</h2>
+          <span className="text-xs font-bold bg-yellow-500/15 text-yellow-400 border border-yellow-500/25 rounded-full px-3 py-1">
+            Tier 2 · Common
+          </span>
+        </div>
+        <p className="text-gray-500 text-sm mb-6">Patterns you will reach for often as your app grows.</p>
+        <div className="grid sm:grid-cols-2 gap-4">
+          <a
+            href="/recipes/optimistic-ui"
+            className="group block bg-gray-900 border border-gray-800 hover:border-cyan-500/50 rounded-xl p-5 transition-colors"
+          >
+            <div className="flex items-center gap-2 mb-2">
+              <span className="text-xs text-gray-500 font-mono">#6</span>
+              <span className="text-xs text-cyan-400 font-medium">⚡ Advanced feature</span>
+            </div>
+            <h3 className="font-semibold text-white group-hover:text-cyan-400 transition-colors mb-1">Optimistic UI</h3>
+            <p className="text-sm text-gray-400">
+              Instant feedback with <code>optimisticData</code>, temporary IDs, and automatic rollback on error.
+            </p>
+          </a>
+
+          <a
+            href="/recipes/modal-form"
+            className="group block bg-gray-900 border border-gray-800 hover:border-brand-500/50 rounded-xl p-5 transition-colors"
+          >
+            <div className="flex items-center gap-2 mb-2">
+              <span className="text-xs text-gray-500 font-mono">#7</span>
+            </div>
+            <h3 className="font-semibold text-white group-hover:text-brand-400 transition-colors mb-1">
+              Modal / Dialog Form
+            </h3>
+            <p className="text-sm text-gray-400">
+              Form lifecycle inside a modal: reset on open, close on success, and Shadcn/ui Dialog integration.
+            </p>
+          </a>
+
+          <a
+            href="/recipes/field-array"
+            className="group block bg-gray-900 border border-gray-800 hover:border-brand-500/50 rounded-xl p-5 transition-colors sm:col-span-2"
+          >
+            <div className="flex items-center gap-2 mb-2">
+              <span className="text-xs text-gray-500 font-mono">#8</span>
+            </div>
+            <h3 className="font-semibold text-white group-hover:text-brand-400 transition-colors mb-1">
+              Dynamic Fields with useFieldArray
+            </h3>
+            <p className="text-sm text-gray-400">
+              Add and remove array items, validate each row, and submit a typed array to the server action using{" "}
+              <code>useFieldArray</code> from React Hook Form.
+            </p>
+          </a>
+        </div>
+      </section>
+
+      {/* ── Tier 3: Advanced ──────────────────────────────────── */}
+      <section className="mb-14">
+        <div className="flex items-center gap-3 mb-3">
+          <h2 className="text-xl font-bold">Advanced Patterns</h2>
+          <span className="text-xs font-bold bg-gray-700/50 text-gray-400 border border-gray-600/50 rounded-full px-3 py-1">
+            Tier 3 · Specialized
+          </span>
+        </div>
+        <p className="text-gray-500 text-sm mb-6">Edge cases, ecosystem integrations, and power-user patterns.</p>
+        <div className="grid sm:grid-cols-2 gap-4">
+          <a
+            href="/recipes/file-upload"
+            className="group block bg-gray-900 border border-gray-800 hover:border-brand-500/50 rounded-xl p-5 transition-colors"
+          >
+            <div className="flex items-center gap-2 mb-2">
+              <span className="text-xs text-gray-500 font-mono">#9</span>
+            </div>
+            <h3 className="font-semibold text-white group-hover:text-brand-400 transition-colors mb-1">File Upload</h3>
+            <p className="text-sm text-gray-400">
+              FormData actions, file type and size validation, image preview, and <code>isPending</code> progress
+              indicator.
+            </p>
+          </a>
+
+          <a
+            href="/recipes/nested-fields"
+            className="group block bg-gray-900 border border-gray-800 hover:border-brand-500/50 rounded-xl p-5 transition-colors"
+          >
+            <div className="flex items-center gap-2 mb-2">
+              <span className="text-xs text-gray-500 font-mono">#10</span>
+            </div>
+            <h3 className="font-semibold text-white group-hover:text-brand-400 transition-colors mb-1">
+              Nested Fields &amp; Sub-components
+            </h3>
+            <p className="text-sm text-gray-400">
+              Compose large forms from smaller components using <code>useFormContext</code> without prop drilling.
+            </p>
+          </a>
+
+          <a
+            href="/recipes/custom-error-mapper"
+            className="group block bg-gray-900 border border-gray-800 hover:border-brand-500/50 rounded-xl p-5 transition-colors"
+          >
+            <div className="flex items-center gap-2 mb-2">
+              <span className="text-xs text-gray-500 font-mono">#11</span>
+            </div>
+            <h3 className="font-semibold text-white group-hover:text-brand-400 transition-colors mb-1">
+              Custom Error Mapper
+            </h3>
+            <p className="text-sm text-gray-400">
+              Translate non-standard API error shapes (Laravel, Rails, REST) to React Hook Form field errors.
+            </p>
+          </a>
+
+          <a
+            href="/recipes/standalone-fetch"
+            className="group block bg-gray-900 border border-gray-800 hover:border-emerald-500/50 rounded-xl p-5 transition-colors"
+          >
+            <div className="flex items-center gap-2 mb-2">
+              <span className="text-xs text-gray-500 font-mono">#12</span>
+              <span className="text-xs text-emerald-400 font-medium">🚀 Standalone</span>
+            </div>
+            <h3 className="font-semibold text-white group-hover:text-emerald-400 transition-colors mb-1">
+              Standalone — Vite, Remix &amp; APIs
+            </h3>
+            <p className="text-sm text-gray-400">
+              Use <code>hookform-action-standalone</code> with <code>fetch</code> or <code>axios</code> outside of
+              Next.js.
+            </p>
+          </a>
+        </div>
+      </section>
+
+      <div className="border-t border-gray-800 pt-8 text-sm text-gray-500">
+        <p>
+          All recipes use real, working code with full TypeScript types. Each pattern maps directly to a capability of
+          the <code>hookform-action</code> API.{" "}
+          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+            Read the API reference →
+          </a>
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docs/app/recipes/reset-after-success/page.tsx b/apps/docs/app/recipes/reset-after-success/page.tsx
new file mode 100644
index 0000000..0ff180d
--- /dev/null
+++ b/apps/docs/app/recipes/reset-after-success/page.tsx
@@ -0,0 +1,301 @@
+export default function ResetAfterSuccessPage() {
+  return (
+    <div className="max-w-4xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/recipes" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to Recipes
+        </a>
+      </div>
+
+      <div className="mb-12">
+        <div className="flex items-center gap-3 mb-4">
+          <span className="text-xs font-bold bg-red-500/15 text-red-400 border border-red-500/25 rounded-full px-3 py-1">
+            Tier 1 · Must-have
+          </span>
+          <span className="text-gray-500 text-sm font-mono">Recipe #3</span>
+        </div>
+        <h1 className="text-3xl font-bold mb-3">Reset After Success</h1>
+        <p className="text-lg text-gray-400">
+          Three canonical patterns for post-submission UX: redirect, in-place reset with a toast, and showing a success
+          state. Choosing the wrong one leads to subtle bugs.
+        </p>
+      </div>
+
+      {/* Why it matters */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-3">Why it matters</h2>
+        <p className="text-gray-400 leading-relaxed">
+          &quot;The form doesn&apos;t clear after I submit&quot; is one of the most common issues raised by developers
+          new to the library. The reason is that <code>isSubmitSuccessful</code> stays <code>true</code> indefinitely,
+          and <code>reset()</code> needs to be called explicitly. These are intentional RHF behaviours — but they need
+          to be wired correctly.
+        </p>
+        <p className="text-gray-400 leading-relaxed mt-3">
+          There are three distinct patterns depending on your UX goal. Pick the right one and you avoid ghost states,
+          stale data, and infinite success screens.
+        </p>
+      </section>
+
+      {/* Pattern 1 */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-2">Pattern 1 — Redirect after submit</h2>
+        <p className="text-gray-400 text-sm mb-5">
+          Best for create-and-navigate flows: create a post, place an order, complete onboarding. The server calls{" "}
+          <code>redirect()</code> and the page navigates away — no client-side reset needed.
+        </p>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            actions.ts
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use server'
+import { redirect } from 'next/navigation'
+import { withZod } from 'hookform-action-core/with-zod'
+import { postSchema } from './schema'
+
+export const createPostAction = withZod(postSchema, async (data) => {
+  const post = await db.posts.create({ data })
+  // redirect() throws internally — the return below is unreachable
+  redirect(\`/posts/\${post.id}\`)
+})`}</pre>
+          </div>
+        </div>
+
+        <div className="bg-blue-500/5 border border-blue-500/20 rounded-lg p-4 text-sm text-gray-400">
+          <span className="text-blue-400 font-medium">Note: </span>
+          After <code>redirect()</code> the hook sets <code>isSubmitSuccessful = true</code>, but the page navigates
+          away immediately so this state is never rendered. You do not need to handle it on the client.
+        </div>
+      </section>
+
+      {/* Pattern 2 */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-2">Pattern 2 — In-place reset with onSuccess</h2>
+        <p className="text-gray-400 text-sm mb-5">
+          Best for forms that stay on the same page after submission: comment boxes, subscription forms, quick-add
+          widgets. Use <code>onSuccess</code> to call <code>reset()</code> and optionally show a toast.
+        </p>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            comment-form.tsx
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useActionForm } from 'hookform-action'
+import { addCommentAction } from './actions'
+
+export function CommentForm() {
+  const {
+    register,
+    handleSubmit,
+    reset,
+    formState: { errors, isPending },
+  } = useActionForm(addCommentAction, {
+    defaultValues: { text: '' },
+    onSuccess: () => {
+      reset()             // Clears all fields back to defaultValues
+      // toast.success('Comment posted!')  // optional side effect
+    },
+  })
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      <textarea {...register('text')} placeholder="Write a comment…" />
+      {errors.text && <p className="text-red-400">{errors.text.message}</p>}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Posting…' : 'Post Comment'}
+      </button>
+    </form>
+  )
+}`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            Resetting to different values (e.g. after edit)
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`onSuccess: (result) => {
+  // Pass new values to reset() — useful after an edit form
+  // where the server returns the updated record
+  reset({
+    title: result.data.title,
+    body: result.data.body,
+  })
+}`}</pre>
+          </div>
+        </div>
+      </section>
+
+      {/* Pattern 3 */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-2">Pattern 3 — isSubmitSuccessful guard</h2>
+        <p className="text-gray-400 text-sm mb-5">
+          Best for single-use forms where you want to replace the form with a success message: contact forms, RSVP
+          forms, one-time redemptions.
+        </p>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            contact-form.tsx
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useActionForm } from 'hookform-action'
+import { sendMessageAction } from './actions'
+
+export function ContactForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isPending, isSubmitSuccessful },
+  } = useActionForm(sendMessageAction, {
+    defaultValues: { name: '', email: '', message: '' },
+  })
+
+  // Replace the form entirely once submitted
+  if (isSubmitSuccessful) {
+    return (
+      <div className="text-center py-12">
+        <p className="text-2xl font-bold text-green-400">Message sent!</p>
+        <p className="text-gray-400 mt-2">We'll get back to you within 24 hours.</p>
+      </div>
+    )
+  }
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      <input {...register('name')} placeholder="Your name" />
+      {errors.name && <p className="text-red-400">{errors.name.message}</p>}
+      <input type="email" {...register('email')} placeholder="Email" />
+      {errors.email && <p className="text-red-400">{errors.email.message}</p>}
+      <textarea {...register('message')} placeholder="Your message" />
+      {errors.message && <p className="text-red-400">{errors.message.message}</p>}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Sending…' : 'Send Message'}
+      </button>
+    </form>
+  )
+}`}</pre>
+          </div>
+        </div>
+      </section>
+
+      {/* Bonus: Wizard cleanup */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-2">Bonus — Clearing persistence after wizard submit</h2>
+        <p className="text-gray-400 text-sm mb-5">
+          When using <code>persistKey</code>, always call <code>clearPersistedData()</code> in <code>onSuccess</code> to
+          remove the saved draft from <code>sessionStorage</code>. Otherwise the user will see stale data if they open
+          the form again.
+        </p>
+
+        <div className="code-block text-gray-300">
+          <pre>{`const { handleSubmit, clearPersistedData } = useActionForm(wizardAction, {
+  defaultValues: { ... },
+  persistKey: 'onboarding-wizard',
+  onSuccess: () => {
+    clearPersistedData()   // ← remove draft from sessionStorage
+    router.push('/dashboard')
+  },
+})`}</pre>
+        </div>
+      </section>
+
+      {/* Key Concepts */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">Key Concepts</h2>
+        <div className="space-y-3">
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">reset()</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Resets all fields to <code>defaultValues</code>, clears all errors, and resets RHF state (
+              <code>isDirty</code>, <code>isSubmitSuccessful</code>, etc.). <code>reset(newValues)</code> additionally
+              updates the stored default values — useful after editing a record.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">isSubmitSuccessful</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Becomes <code>true</code> after a successful action call (no field errors returned) and stays{" "}
+              <code>true</code> until <code>reset()</code> is called or the component unmounts. This is intentional —
+              use it as the guard for your success UI.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">onSuccess callback</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Receives the full action result and fires only when the action succeeds (no field errors). The best place
+              to call <code>reset()</code>, show a toast, or trigger a router navigation.
+            </p>
+          </div>
+        </div>
+      </section>
+
+      {/* Pitfalls */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">⚠️ Pitfalls</h2>
+        <ul className="space-y-3">
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Calling <code>reset()</code> in a <code>useEffect</code> watching <code>isSubmitSuccessful</code>
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                This creates a double-render cycle. Prefer <code>onSuccess</code> — it fires synchronously after the
+                action resolves, before any re-render.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">Resetting inside a modal — flash of empty form</p>
+              <p className="text-sm text-gray-400 mt-1">
+                If you <code>reset()</code> and then close the modal in <code>onSuccess</code>, the form briefly shows
+                empty before the modal animation completes. Prefer resetting in the <code>onClose</code> handler
+                instead, or use a <code>key</code> prop to remount.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                <code>reset()</code> without arguments on an edit form
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                If <code>defaultValues</code> came from the server and the user just saved new data, calling{" "}
+                <code>reset()</code> reverts to the old server data. Use <code>reset(result.data)</code> to update the
+                baseline after a successful edit.
+              </p>
+            </div>
+          </li>
+        </ul>
+      </section>
+
+      {/* Related */}
+      <section className="border-t border-gray-800 pt-8">
+        <h2 className="text-lg font-semibold mb-4">Related</h2>
+        <div className="flex flex-wrap gap-4 text-sm">
+          <a href="/recipes/login-form" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Login Form
+          </a>
+          <a href="/recipes/modal-form" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Modal / Dialog Form
+          </a>
+          <a href="/recipes/multi-step-wizard" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Multi-Step Wizard
+          </a>
+          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → API Reference
+          </a>
+        </div>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/app/recipes/signup-server-errors/page.tsx b/apps/docs/app/recipes/signup-server-errors/page.tsx
new file mode 100644
index 0000000..017898a
--- /dev/null
+++ b/apps/docs/app/recipes/signup-server-errors/page.tsx
@@ -0,0 +1,279 @@
+export default function SignupServerErrorsPage() {
+  return (
+    <div className="max-w-4xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/recipes" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to Recipes
+        </a>
+      </div>
+
+      <div className="mb-12">
+        <div className="flex items-center gap-3 mb-4">
+          <span className="text-xs font-bold bg-red-500/15 text-red-400 border border-red-500/25 rounded-full px-3 py-1">
+            Tier 1 · Must-have
+          </span>
+          <span className="text-gray-500 text-sm font-mono">Recipe #2</span>
+        </div>
+        <h1 className="text-3xl font-bold mb-3">Sign Up with Server Validation Errors</h1>
+        <p className="text-lg text-gray-400">
+          How to return business-logic errors from a server action — duplicate email, taken username, and more — and
+          have them appear on the correct fields automatically.
+        </p>
+      </div>
+
+      {/* Why it matters */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-3">Why it matters</h2>
+        <p className="text-gray-400 leading-relaxed">
+          The login form teaches the happy path. This recipe teaches what actually happens in production: the user
+          submits valid data, but the server rejects it because the email is already registered or the username is
+          taken. These are business-logic errors that Zod&apos;s schema can&apos;t know about.
+        </p>
+        <p className="text-gray-400 leading-relaxed mt-3">
+          <code>hookform-action</code> has a built-in contract for this: return{" "}
+          <code>{`{ errors: { field: string[] } }`}</code> from the action and the hook maps it directly to the
+          corresponding React Hook Form fields — no extra wiring needed. This recipe also shows{" "}
+          <code>setSubmitError</code> for errors set outside the action, and the <code>onError</code> callback for side
+          effects like toasts.
+        </p>
+      </section>
+
+      {/* Full Example */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-6">Full Example</h2>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            actions.ts
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use server'
+import { z } from 'zod'
+import { withZod } from 'hookform-action-core/with-zod'
+
+const signupSchema = z.object({
+  email: z.string().email('Invalid email address'),
+  username: z.string().min(3, 'Username must be at least 3 characters'),
+  password: z.string().min(8, 'Password must be at least 8 characters'),
+})
+
+export const signupAction = withZod(signupSchema, async (data) => {
+  // data is typed: { email: string; username: string; password: string }
+
+  // Simulate DB uniqueness checks
+  if (data.email === 'taken@example.com') {
+    return { errors: { email: ['This email is already registered'] } }
+  }
+
+  if (data.username === 'admin') {
+    return { errors: { username: ['This username is not available'] } }
+  }
+
+  // Multiple field errors at once
+  if (data.email.endsWith('@disposable.com')) {
+    return {
+      errors: {
+        email: ['Disposable email addresses are not allowed'],
+        username: ['Please use your real name'],
+      },
+    }
+  }
+
+  return { success: true }
+})`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            signup-form.tsx
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`'use client'
+import { useActionForm } from 'hookform-action'
+import type { InferActionResult } from 'hookform-action'
+import { signupAction } from './actions'
+
+// Infer the exact return type of the action for type-safe access
+type SignupResult = InferActionResult<typeof signupAction>
+
+export function SignupForm() {
+  const {
+    register,
+    handleSubmit,
+    setSubmitError,
+    formState: { errors, isPending, isSubmitSuccessful, actionResult },
+  } = useActionForm(signupAction, {
+    defaultValues: { email: '', username: '', password: '' },
+    onSuccess: (result: SignupResult) => {
+      // result.success === true here
+      console.log('Account created!')
+    },
+    onError: (result: SignupResult | Error) => {
+      // Fires when field errors are returned OR the action throws
+      // Good place for analytics, toast notifications, etc.
+      if (result instanceof Error) {
+        console.error('Unexpected error:', result.message)
+      }
+    },
+  })
+
+  if (isSubmitSuccessful) {
+    return (
+      <div className="text-green-400">
+        <p>Account created! Check your email to verify.</p>
+      </div>
+    )
+  }
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      <div>
+        <label htmlFor="email">Email</label>
+        <input id="email" type="email" {...register('email')} />
+        {/* Shows both Zod client errors AND server errors from the action */}
+        {errors.email && <p className="text-red-400">{errors.email.message}</p>}
+      </div>
+
+      <div>
+        <label htmlFor="username">Username</label>
+        <input id="username" {...register('username')} />
+        {errors.username && <p className="text-red-400">{errors.username.message}</p>}
+      </div>
+
+      <div>
+        <label htmlFor="password">Password</label>
+        <input id="password" type="password" {...register('password')} />
+        {errors.password && <p className="text-red-400">{errors.password.message}</p>}
+      </div>
+
+      {/* Optional: surface a global error if the action returns one */}
+      {actionResult && 'message' in actionResult && actionResult.message && (
+        <p className="text-red-400 text-sm">{actionResult.message}</p>
+      )}
+
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating account…' : 'Sign Up'}
+      </button>
+    </form>
+  )
+}`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            Using setSubmitError manually
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`// Sometimes you need to set a server error outside the action response,
+// for example after a network check or in an event handler:
+
+const { setSubmitError } = useActionForm(signupAction, { ... })
+
+// Set an error on a specific field programmatically:
+setSubmitError('email', 'This email was flagged as invalid by our provider')`}</pre>
+          </div>
+        </div>
+      </section>
+
+      {/* Key Concepts */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">Key Concepts</h2>
+        <div className="space-y-3">
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">{`{ errors: { field: string[] } }`}</code>
+            <p className="text-gray-400 text-sm mt-1">
+              The default error contract. Return this shape from any action and <code>defaultErrorMapper</code>{" "}
+              automatically sets the corresponding RHF field errors. The key is the field name, the value is an array of
+              message strings (only the first message is shown by RHF by default).
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">formState.actionResult</code>
+            <p className="text-gray-400 text-sm mt-1">
+              The raw return value of the last action call, preserved with full type safety via{" "}
+              <code>InferActionResult&lt;typeof action&gt;</code>. Use it to surface global messages or access non-error
+              data from the response.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">setSubmitError(field, message)</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Programmatically sets a field error as if it came from the server. Useful for client-side checks that
+              happen outside the normal submit flow, such as async email-availability lookups on blur.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">onError callback</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Fires when the action returns field errors <em>or</em> throws an exception. Use it for side effects —
+              toast notifications, error logging, analytics — without polluting the action or the component&apos;s
+              render logic.
+            </p>
+          </div>
+        </div>
+      </section>
+
+      {/* Pitfalls */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">⚠️ Pitfalls</h2>
+        <ul className="space-y-3">
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">Server errors don&apos;t clear when the user retypes</p>
+              <p className="text-sm text-gray-400 mt-1">
+                This is intentional RHF behaviour. A server error set via the error mapper persists until the next
+                submit (or until you call <code>clearErrors(field)</code> manually). To clear on input, use{" "}
+                <code>validationMode: &apos;onChange&apos;</code> with a client-side schema.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">Distinguishing field errors from global errors</p>
+              <p className="text-sm text-gray-400 mt-1">
+                The <code>errors</code> object only contains field-level errors from RHF. To display a global error
+                message (e.g. &quot;Service unavailable&quot;), read it from <code>actionResult</code> and render it
+                separately outside the field markup.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                <code>withZod</code> already returns field errors — don&apos;t double-validate
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                If the schema fails, <code>withZod</code> short-circuits and returns <code>{`{ errors }`}</code> before
+                your handler runs. Do not call <code>schema.safeParse</code> again inside the handler.
+              </p>
+            </div>
+          </li>
+        </ul>
+      </section>
+
+      {/* Related */}
+      <section className="border-t border-gray-800 pt-8">
+        <h2 className="text-lg font-semibold mb-4">Related</h2>
+        <div className="flex flex-wrap gap-4 text-sm">
+          <a href="/recipes/login-form" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Login Form
+          </a>
+          <a href="/recipes/custom-error-mapper" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Custom Error Mapper
+          </a>
+          <a href="/examples/validation" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Live Validation Example
+          </a>
+          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → API Reference
+          </a>
+        </div>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/app/recipes/standalone-fetch/page.tsx b/apps/docs/app/recipes/standalone-fetch/page.tsx
new file mode 100644
index 0000000..afb7011
--- /dev/null
+++ b/apps/docs/app/recipes/standalone-fetch/page.tsx
@@ -0,0 +1,336 @@
+export default function StandaloneFetchPage() {
+  return (
+    <div className="max-w-4xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/recipes" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to Recipes
+        </a>
+      </div>
+
+      <div className="mb-12">
+        <div className="flex items-center gap-3 mb-4">
+          <span className="text-xs font-bold bg-gray-700/50 text-gray-400 border border-gray-600/50 rounded-full px-3 py-1">
+            Tier 3 · Specialized
+          </span>
+          <span className="text-xs text-emerald-400 font-medium">🚀 Standalone</span>
+          <span className="text-gray-500 text-sm font-mono">Recipe #12</span>
+        </div>
+        <h1 className="text-3xl font-bold mb-3">Standalone — Vite, Remix &amp; Custom APIs</h1>
+        <p className="text-lg text-gray-400">
+          Use <code>hookform-action-standalone</code> with any async function — <code>fetch</code>, <code>axios</code>,
+          tRPC, or a custom client — in apps that don&apos;t use Next.js Server Actions.
+        </p>
+        <a
+          href="/standalone"
+          className="inline-flex items-center gap-1 mt-4 text-sm text-emerald-400 hover:text-emerald-300 transition-colors"
+        >
+          Standalone Guide →
+        </a>
+      </div>
+
+      {/* Why it matters */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-3">Why it matters</h2>
+        <p className="text-gray-400 leading-relaxed">
+          Not every React app uses Next.js or Server Actions. Vite SPAs, Remix apps, Astro islands, and React Native
+          projects all need the same ergonomics — typed validation, automatic error mapping, optimistic UI — but with a
+          plain async function as the submit handler.
+        </p>
+        <p className="text-gray-400 leading-relaxed mt-3">
+          The standalone adapter exposes exactly the same hook API. The only difference is: instead of passing a Server
+          Action as the first argument, you pass an options object with a <code>submit</code> function. Everything else
+          — <code>schema</code>, <code>optimisticData</code>, <code>persistKey</code>, <code>onSuccess</code>,{" "}
+          <code>errorMapper</code> — works identically.
+        </p>
+      </section>
+
+      {/* Full Example */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-6">Full Example — Login Form (Vite SPA)</h2>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            api.ts — Typed fetch wrapper
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`// A reusable fetch wrapper that returns a typed result
+// (replace with axios, ky, or your preferred client)
+
+export interface LoginResult {
+  success?: boolean
+  token?: string
+  errors?: {
+    email?: string[]
+    password?: string[]
+  }
+  message?: string
+}
+
+export async function loginApi(data: {
+  email: string
+  password: string
+}): Promise<LoginResult> {
+  const res = await fetch('/api/auth/login', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      // Add auth headers here if needed: Authorization: \`Bearer \${token}\`
+    },
+    body: JSON.stringify(data),
+  })
+
+  // Treat non-2xx as a structured error result, not a thrown error
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}))
+    return {
+      errors: body.errors ?? { email: ['Login failed. Please try again.'] },
+      message: body.message,
+    }
+  }
+
+  return res.json()
+}`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            login-form.tsx — Standalone hook usage
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`import { useActionForm } from 'hookform-action-standalone'
+import { z } from 'zod'
+import { loginApi, type LoginResult } from './api'
+
+// Client-side validation schema (same as in Next.js)
+const loginSchema = z.object({
+  email:    z.string().email('Enter a valid email'),
+  password: z.string().min(8, 'Password must be at least 8 characters'),
+})
+
+export function LoginForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isPending, isSubmitSuccessful },
+  } = useActionForm<{ email: string; password: string }, LoginResult>({
+    // Key difference from Next.js: pass an options object with 'submit'
+    submit: loginApi,
+
+    defaultValues: { email: '', password: '' },
+    schema: loginSchema,
+    validationMode: 'onChange',
+
+    onSuccess: (result) => {
+      if (result.token) {
+        localStorage.setItem('token', result.token)
+        window.location.href = '/dashboard'
+      }
+    },
+    onError: (result) => {
+      if (result instanceof Error) {
+        // toast.error('Network error. Please check your connection.')
+      }
+    },
+  })
+
+  if (isSubmitSuccessful) {
+    return <p className="text-green-400">Signed in! Redirecting…</p>
+  }
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      <div>
+        <label htmlFor="email">Email</label>
+        <input id="email" type="email" {...register('email')} />
+        {errors.email && <p className="text-red-400">{errors.email.message}</p>}
+      </div>
+
+      <div>
+        <label htmlFor="password">Password</label>
+        <input id="password" type="password" {...register('password')} />
+        {errors.password && <p className="text-red-400">{errors.password.message}</p>}
+      </div>
+
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Signing in…' : 'Sign In'}
+      </button>
+    </form>
+  )
+}`}</pre>
+          </div>
+        </div>
+
+        <div className="mb-5">
+          <span className="text-xs font-mono text-gray-400 bg-gray-800 px-2 py-0.5 rounded border border-gray-700">
+            Bonus — axios variant
+          </span>
+          <div className="code-block mt-2 text-gray-300">
+            <pre>{`import axios from 'axios'
+
+// The submit function can throw — the hook catches it and fires onError
+export async function loginApi(data: { email: string; password: string }) {
+  try {
+    const { data: result } = await axios.post('/api/auth/login', data)
+    return result
+  } catch (err) {
+    if (axios.isAxiosError(err) && err.response) {
+      // Return structured errors instead of throwing
+      return err.response.data
+    }
+    throw err  // Re-throw for unexpected errors (network timeout, etc.)
+  }
+}`}</pre>
+          </div>
+        </div>
+      </section>
+
+      {/* API diff table */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">Next.js vs Standalone — API Diff</h2>
+        <div className="overflow-x-auto">
+          <table className="w-full text-sm border-collapse">
+            <thead>
+              <tr className="border-b border-gray-800">
+                <th className="text-left py-2 pr-4 text-gray-400 font-medium">Feature</th>
+                <th className="text-left py-2 pr-4 text-brand-400 font-medium">hookform-action (Next.js)</th>
+                <th className="text-left py-2 text-emerald-400 font-medium">hookform-action-standalone</th>
+              </tr>
+            </thead>
+            <tbody className="text-gray-400">
+              <tr className="border-b border-gray-800/50">
+                <td className="py-2 pr-4 font-mono text-xs">Import</td>
+                <td className="py-2 pr-4 font-mono text-xs">hookform-action</td>
+                <td className="py-2 font-mono text-xs">hookform-action-standalone</td>
+              </tr>
+              <tr className="border-b border-gray-800/50">
+                <td className="py-2 pr-4 font-mono text-xs">Hook signature</td>
+                <td className="py-2 pr-4 font-mono text-xs">useActionForm(action, options?)</td>
+                <td className="py-2 font-mono text-xs">useActionForm(&#123; submit, ...options &#125;)</td>
+              </tr>
+              <tr className="border-b border-gray-800/50">
+                <td className="py-2 pr-4 font-mono text-xs">formAction</td>
+                <td className="py-2 pr-4">✅ Available</td>
+                <td className="py-2">❌ Not available</td>
+              </tr>
+              <tr className="border-b border-gray-800/50">
+                <td className="py-2 pr-4 font-mono text-xs">schema / withZod</td>
+                <td className="py-2 pr-4">✅ Auto-detected from action</td>
+                <td className="py-2">✅ Pass schema option</td>
+              </tr>
+              <tr className="border-b border-gray-800/50">
+                <td className="py-2 pr-4 font-mono text-xs">persistKey</td>
+                <td className="py-2 pr-4">✅</td>
+                <td className="py-2">✅</td>
+              </tr>
+              <tr className="border-b border-gray-800/50">
+                <td className="py-2 pr-4 font-mono text-xs">optimisticData</td>
+                <td className="py-2 pr-4">✅</td>
+                <td className="py-2">✅</td>
+              </tr>
+              <tr>
+                <td className="py-2 pr-4 font-mono text-xs">errorMapper</td>
+                <td className="py-2 pr-4">✅</td>
+                <td className="py-2">✅</td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </section>
+
+      {/* Key Concepts */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">Key Concepts</h2>
+        <div className="space-y-3">
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">submit: async (data) =&gt; TResult</code>
+            <p className="text-gray-400 text-sm mt-1">
+              Any async function that receives the validated form data and returns a result. It can call{" "}
+              <code>fetch</code>, <code>axios</code>, a tRPC procedure, a GraphQL mutation, or any other async
+              operation. If it throws, the hook catches it and fires <code>onError</code>.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">Structured errors vs thrown errors</code>
+            <p className="text-gray-400 text-sm mt-1">
+              For HTTP 4xx errors, return a structured result (with <code>errors</code>) instead of throwing. This
+              allows the <code>errorMapper</code> to set field errors correctly. Only throw for unexpected errors (5xx,
+              network failures) — those trigger <code>onError</code> with an <code>Error</code> instance.
+            </p>
+          </div>
+          <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
+            <code className="text-brand-400">withZod is not used server-side in standalone</code>
+            <p className="text-gray-400 text-sm mt-1">
+              <code>withZod</code> is a wrapper for Next.js Server Actions. In standalone mode, pass the schema via the{" "}
+              <code>schema</code> option for client-side validation only. Server-side validation must be implemented
+              inside your <code>submit</code> function or API handler.
+            </p>
+          </div>
+        </div>
+      </section>
+
+      {/* Pitfalls */}
+      <section className="mb-12">
+        <h2 className="text-xl font-bold mb-4">⚠️ Pitfalls</h2>
+        <ul className="space-y-3">
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">Throwing on HTTP 4xx errors</p>
+              <p className="text-sm text-gray-400 mt-1">
+                If your fetch wrapper throws on 4xx, the hook receives an <code>Error</code> — not a structured result.
+                The <code>errorMapper</code> won&apos;t fire for thrown errors. Return a structured object instead so
+                field errors can be set automatically.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                No <code>formAction</code> in standalone
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                The standalone adapter does not expose <code>formAction</code> — there is no support for the{" "}
+                <code>{"<form action={...}>"}</code> pattern without JavaScript. Progressive enhancement requires the
+                Next.js adapter.
+              </p>
+            </div>
+          </li>
+          <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
+            <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
+            <div>
+              <p className="text-sm font-medium text-gray-200">
+                Inline <code>submit</code> function
+              </p>
+              <p className="text-sm text-gray-400 mt-1">
+                Defining <code>submit</code> as an inline arrow function inside the component creates a new reference on
+                every render. Extract it to module scope or wrap with <code>useCallback</code> to avoid re-initialising
+                the hook.
+              </p>
+            </div>
+          </li>
+        </ul>
+      </section>
+
+      {/* Related */}
+      <section className="border-t border-gray-800 pt-8">
+        <h2 className="text-lg font-semibold mb-4">Related</h2>
+        <div className="flex flex-wrap gap-4 text-sm">
+          <a href="/standalone" className="text-emerald-400 hover:text-emerald-300 transition-colors">
+            → Standalone Guide
+          </a>
+          <a href="/recipes/custom-error-mapper" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Custom Error Mapper
+          </a>
+          <a href="/recipes/login-form" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → Login Form (Next.js)
+          </a>
+          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+            → API Reference
+          </a>
+        </div>
+      </section>
+    </div>
+  );
+}
diff --git a/apps/docs/app/standalone/page.tsx b/apps/docs/app/standalone/page.tsx
index 45a6353..7cd3a72 100644
--- a/apps/docs/app/standalone/page.tsx
+++ b/apps/docs/app/standalone/page.tsx
@@ -8,7 +8,7 @@ export default function StandalonePage() {
       </div>
 
       <div className="inline-flex items-center gap-2 bg-emerald-500/10 text-emerald-400 border border-emerald-500/20 rounded-full px-4 py-1.5 text-sm font-medium mb-6">
-        <span>v3</span>
+        <span>v4</span>
         <span className="text-gray-600">·</span>
         <span>hookform-action-standalone</span>
       </div>
diff --git a/apps/docs/app/submit-lifecycle/page.tsx b/apps/docs/app/submit-lifecycle/page.tsx
new file mode 100644
index 0000000..0f6b017
--- /dev/null
+++ b/apps/docs/app/submit-lifecycle/page.tsx
@@ -0,0 +1,229 @@
+export default function SubmitLifecyclePage() {
+  return (
+    <div className="max-w-5xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to docs
+        </a>
+      </div>
+
+      <h1 className="text-3xl font-bold mb-3">Submit Lifecycle</h1>
+      <p className="text-gray-400 max-w-3xl mb-10">
+        A practical mental model for <code>isSubmitting</code>, <code>isPending</code>,{" "}
+        <code>isSubmitSuccessful</code>, <code>submitErrors</code>, and{" "}
+        <code>actionResult</code>.
+      </p>
+
+      {/* 1. Simple explanation */}
+      <section className="mb-14">
+        <h2 className="text-2xl font-bold mb-4 text-brand-400">1) Simple Explanation</h2>
+        <p className="text-gray-400 mb-5">
+          Think of <code>hookform-action</code> as RHF + an action lifecycle layer.
+        </p>
+        <ol className="space-y-3 text-gray-300 list-decimal list-inside">
+          <li>
+            <span className="font-medium text-gray-200">Idle</span>: no request in flight.
+          </li>
+          <li>
+            <span className="font-medium text-gray-200">Submit starts</span>:{" "}
+            <code>isSubmitting = true</code>, <code>isPending = true</code>,{" "}
+            <code>submitErrors = null</code>.
+          </li>
+          <li>
+            <span className="font-medium text-gray-200">Success</span>:{" "}
+            <code>isPending = false</code>, <code>isSubmitting = false</code>,{" "}
+            <code>isSubmitSuccessful = true</code>, <code>submitErrors = null</code>,{" "}
+            <code>actionResult = result</code>.
+          </li>
+          <li>
+            <span className="font-medium text-gray-200">Field error result</span>:{" "}
+            <code>isPending = false</code>, <code>isSubmitting = false</code>,{" "}
+            <code>isSubmitSuccessful = false</code>, <code>submitErrors = ...</code>,{" "}
+            <code>actionResult = result</code>.
+          </li>
+          <li>
+            <span className="font-medium text-gray-200">Thrown error (network/exception)</span>:{" "}
+            <code>isPending = false</code>, <code>isSubmitting = false</code>,{" "}
+            <code>isSubmitSuccessful = false</code>. Handle this path in <code>onError</code>.
+          </li>
+        </ol>
+      </section>
+
+      {/* 2. State table */}
+      <section className="mb-14">
+        <h2 className="text-2xl font-bold mb-4 text-brand-400">2) State Table</h2>
+        <div className="overflow-x-auto">
+          <table className="w-full text-sm text-left">
+            <thead className="text-gray-400 border-b border-gray-800">
+              <tr>
+                <th className="py-3 pr-4">State</th>
+                <th className="py-3 pr-4">What it means</th>
+                <th className="py-3 pr-4">When it changes</th>
+                <th className="py-3">Use it for</th>
+              </tr>
+            </thead>
+            <tbody className="text-gray-300">
+              <tr className="border-b border-gray-800/50">
+                <td className="py-3 pr-4 font-mono text-brand-300">formState.isSubmitting</td>
+                <td className="py-3 pr-4 text-gray-400">
+                  Submit is running (RHF + action internal state).
+                </td>
+                <td className="py-3 pr-4 text-gray-400">
+                  True at submit start, false on finish/failure.
+                </td>
+                <td className="py-3 text-gray-400">Legacy compatibility and debugging.</td>
+              </tr>
+              <tr className="border-b border-gray-800/50 bg-brand-500/5">
+                <td className="py-3 pr-4 font-mono text-brand-300">formState.isPending</td>
+                <td className="py-3 pr-4 text-gray-400">
+                  Transition + request pending window.
+                </td>
+                <td className="py-3 pr-4 text-gray-400">
+                  Derived from <code>useTransition</code> plus internal pending state.
+                </td>
+                <td className="py-3 text-gray-400">
+                  <strong>Disable button and show loading.</strong>
+                </td>
+              </tr>
+              <tr className="border-b border-gray-800/50">
+                <td className="py-3 pr-4 font-mono text-brand-300">formState.isSubmitSuccessful</td>
+                <td className="py-3 pr-4 text-gray-400">
+                  Last completed submit ended without field errors.
+                </td>
+                <td className="py-3 pr-4 text-gray-400">
+                  True on success, false on validation errors or thrown errors.
+                </td>
+                <td className="py-3 text-gray-400">Post-submit success logic.</td>
+              </tr>
+              <tr className="border-b border-gray-800/50">
+                <td className="py-3 pr-4 font-mono text-brand-300">formState.submitErrors</td>
+                <td className="py-3 pr-4 text-gray-400">
+                  Structured field-level error record.
+                </td>
+                <td className="py-3 pr-4 text-gray-400">
+                  Set on client/server validation errors, cleared at new submit start.
+                </td>
+                <td className="py-3 text-gray-400">Render field/server validation feedback.</td>
+              </tr>
+              <tr className="border-b border-gray-800/50">
+                <td className="py-3 pr-4 font-mono text-brand-300">formState.actionResult</td>
+                <td className="py-3 pr-4 text-gray-400">Full result object from last completed action response.</td>
+                <td className="py-3 pr-4 text-gray-400">
+                  Updated on success and field-error responses.
+                </td>
+                <td className="py-3 text-gray-400">Read confirmed payload with success guards.</td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </section>
+
+      {/* 3. Correct usage examples */}
+      <section className="mb-14">
+        <h2 className="text-2xl font-bold mb-4 text-brand-400">3) Correct Usage</h2>
+        <h3 className="text-lg font-semibold mb-2">Disable + loading with isPending</h3>
+        <div className="code-block mb-6 text-gray-300">
+          <pre>{`const {
+  handleSubmit,
+  formState: { isPending },
+} = useActionForm(action, { defaultValues })
+
+return (
+  <form onSubmit={handleSubmit()}>
+    <button type="submit" disabled={isPending}>
+      {isPending ? 'Saving...' : 'Save'}
+    </button>
+  </form>
+)`}</pre>
+        </div>
+
+        <h3 className="text-lg font-semibold mb-2">Post-submit success logic</h3>
+        <div className="code-block mb-6 text-gray-300">
+          <pre>{`const {
+  formState: { isPending, isSubmitSuccessful },
+} = useActionForm(action, { defaultValues })
+
+useEffect(() => {
+  if (!isPending && isSubmitSuccessful) {
+    toast.success('Saved')
+    // router.push('/dashboard')
+  }
+}, [isPending, isSubmitSuccessful])`}</pre>
+        </div>
+
+        <h3 className="text-lg font-semibold mb-2">Validation errors vs confirmed result</h3>
+        <div className="code-block text-gray-300">
+          <pre>{`const {
+  formState: { submitErrors, actionResult, isSubmitSuccessful, isPending },
+} = useActionForm(action, { defaultValues })
+
+const hasFieldErrors = !!submitErrors
+const confirmedData =
+  !isPending && isSubmitSuccessful ? actionResult : null`}</pre>
+        </div>
+      </section>
+
+      {/* 4. Misinterpretations */}
+      <section className="mb-14">
+        <h2 className="text-2xl font-bold mb-4 text-brand-400">4) Common Misinterpretations</h2>
+        <ul className="space-y-3">
+          <li className="bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4 text-sm text-gray-300">
+            Using <code>isSubmitting</code> for button lock/loading. Prefer <code>isPending</code>.
+          </li>
+          <li className="bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4 text-sm text-gray-300">
+            Treating <code>actionResult</code> as automatic success. It can also hold an error-shaped result.
+          </li>
+          <li className="bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4 text-sm text-gray-300">
+            Running success side-effects only with <code>isSubmitSuccessful</code>. Gate with{" "}
+            <code>!isPending</code> too.
+          </li>
+          <li className="bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4 text-sm text-gray-300">
+            Expecting <code>submitErrors</code> for thrown exceptions. Thrown errors belong to{" "}
+            <code>onError</code>.
+          </li>
+        </ul>
+      </section>
+
+      {/* 5. Documentation recommendations */}
+      <section className="mb-14">
+        <h2 className="text-2xl font-bold mb-4 text-brand-400">5) Recommended Docs Snippets</h2>
+        <div className="grid sm:grid-cols-2 gap-4 text-sm">
+          <div className="bg-gray-900/50 border border-gray-800 rounded-lg p-4">
+            <p className="font-semibold text-gray-200 mb-2">Submit Button Snippet</p>
+            <p className="text-gray-400">
+              Always show <code>disabled</code> and loading from <code>isPending</code>.
+            </p>
+          </div>
+          <div className="bg-gray-900/50 border border-gray-800 rounded-lg p-4">
+            <p className="font-semibold text-gray-200 mb-2">Success Effect Snippet</p>
+            <p className="text-gray-400">
+              Use <code>!isPending && isSubmitSuccessful</code> to trigger post-submit effects.
+            </p>
+          </div>
+          <div className="bg-gray-900/50 border border-gray-800 rounded-lg p-4">
+            <p className="font-semibold text-gray-200 mb-2">Validation Errors Snippet</p>
+            <p className="text-gray-400">
+              Show <code>submitErrors</code> for field-level API errors and keep RHF <code>errors</code> in sync.
+            </p>
+          </div>
+          <div className="bg-gray-900/50 border border-gray-800 rounded-lg p-4">
+            <p className="font-semibold text-gray-200 mb-2">Result Guard Snippet</p>
+            <p className="text-gray-400">
+              Read <code>actionResult</code> only behind explicit success guards.
+            </p>
+          </div>
+        </div>
+      </section>
+
+      <section className="border-t border-gray-800 pt-8">
+        <h2 className="text-xl font-bold mb-3 text-brand-400">How this maps to RHF + transitions + Server Actions</h2>
+        <p className="text-gray-400 leading-relaxed">
+          RHF still owns base form mechanics (<code>register</code>, <code>errors</code>, touched/dirty state).
+          hookform-action wraps submit execution, runs inside <code>startTransition</code>, then composes the final
+          form state (`isPending = transitionPending || internalPending`). In Next.js mode, the adapter also bridges{" "}
+          <code>FormData</code>/<code>prevState</code> signatures before passing control to the same core lifecycle.
+        </p>
+      </section>
+    </div>
+  )
+}
diff --git a/apps/docs/app/troubleshooting/page.tsx b/apps/docs/app/troubleshooting/page.tsx
new file mode 100644
index 0000000..ff9af40
--- /dev/null
+++ b/apps/docs/app/troubleshooting/page.tsx
@@ -0,0 +1,125 @@
+type TroubleshootingItem = {
+  symptom: string
+  likelyCause: string
+  quickFix: string
+}
+
+const troubleshootingItems: TroubleshootingItem[] = [
+  {
+    symptom: 'I click submit and nothing happens.',
+    likelyCause:
+      'handleSubmit is not wired correctly, submit button type is wrong, or client validation blocked execution.',
+    quickFix: 'Use onSubmit={handleSubmit()} and inspect formState.errors after click.',
+  },
+  {
+    symptom: 'Action is not called even with valid-looking fields.',
+    likelyCause: 'Client-side schema validation failed before the network request.',
+    quickFix: 'Check validationMode and verify each field against the schema.',
+  },
+  {
+    symptom: 'Server errors are not shown on inputs.',
+    likelyCause: 'Returned error shape does not match default mapper expectations.',
+    quickFix: 'Return { errors: Record<string, string[]> } or implement errorMapper.',
+  },
+  {
+    symptom: 'Errors show on the wrong field (nested/array forms).',
+    likelyCause: 'Error keys do not match RHF field paths.',
+    quickFix: 'Use RHF paths like address.city and items.0.price in server error keys.',
+  },
+  {
+    symptom: 'Submit button enables too early and allows double submits.',
+    likelyCause: 'UI is using isSubmitting instead of isPending.',
+    quickFix: 'Disable by formState.isPending for end-to-end submit state.',
+  },
+  {
+    symptom: 'Old values keep returning in edit forms.',
+    likelyCause: 'persistKey restored an old draft and overrode defaults.',
+    quickFix: 'Scope persistKey per entity and clear persisted drafts on load/success.',
+  },
+  {
+    symptom: 'optimistic is undefined or has no effect.',
+    likelyCause: 'Incomplete optimistic setup or UI is rendering confirmed data only.',
+    quickFix: 'Provide optimisticKey + optimisticData and render optimistic.data while pending.',
+  },
+  {
+    symptom: 'File upload fails or file is empty on server.',
+    likelyCause: 'Using JSON flow for file input instead of FormData action handling.',
+    quickFix: 'Use a FormData-based action and validate file type/size server-side.',
+  },
+  {
+    symptom: 'onError does not fire when the form is invalid.',
+    likelyCause: 'Invalid client form never reaches action execution.',
+    quickFix:
+      'Use formState.errors for client invalid state; onError handles action failure paths.',
+  },
+  {
+    symptom: 'Standalone flow expects formAction but it does not exist.',
+    likelyCause: 'Standalone API signature differs from Next.js adapter.',
+    quickFix: 'Use submit in options and trigger with handleSubmit().',
+  },
+]
+
+const checklist = [
+  'Confirm package choice: next adapter vs standalone adapter.',
+  'Confirm schema and validationMode match your intended UX.',
+  'Confirm action return shape for field errors.',
+  'Confirm field names and error keys use identical RHF paths.',
+  'Confirm submit buttons are gated by isPending.',
+  'Confirm persistKey scope and clear strategy.',
+  'Confirm optimistic settings and rendering path.',
+  'Confirm file flows use FormData, not JSON.',
+]
+
+export default function TroubleshootingPage() {
+  return (
+    <div className="max-w-5xl mx-auto px-6 py-16">
+      <div className="mb-8 flex items-center justify-between gap-4 flex-wrap">
+        <a href="/" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to docs
+        </a>
+        <div className="flex items-center gap-4 text-sm">
+          <a href="/faq" className="text-brand-400 hover:text-brand-300 transition-colors">
+            FAQ →
+          </a>
+          <a href="/recipes" className="text-cyan-400 hover:text-cyan-300 transition-colors">
+            Recipes →
+          </a>
+        </div>
+      </div>
+
+      <header className="mb-10">
+        <h1 className="text-3xl font-bold mb-3">Troubleshooting</h1>
+        <p className="text-gray-400 max-w-3xl">
+          Debug common adoption problems by symptom. Each item maps directly to a root cause and a
+          minimal correction.
+        </p>
+      </header>
+
+      <section className="space-y-3 mb-10">
+        {troubleshootingItems.map((item) => (
+          <div key={item.symptom} className="border border-gray-800 rounded-xl p-5 bg-gray-900/30">
+            <h2 className="text-base font-semibold text-white mb-2">{item.symptom}</h2>
+            <p className="text-sm text-gray-400 mb-1">
+              <span className="text-gray-300 font-medium">Likely cause:</span> {item.likelyCause}
+            </p>
+            <p className="text-sm text-gray-300">
+              <span className="text-cyan-300 font-medium">Quick fix:</span> {item.quickFix}
+            </p>
+          </div>
+        ))}
+      </section>
+
+      <section className="border border-gray-800 rounded-xl p-6 bg-gradient-to-br from-cyan-500/10 to-brand-500/10">
+        <h2 className="text-lg font-semibold mb-3">60-second checklist</h2>
+        <ol className="space-y-2 text-sm text-gray-300">
+          {checklist.map((item, index) => (
+            <li key={item}>
+              <span className="text-gray-500 mr-2">{index + 1}.</span>
+              {item}
+            </li>
+          ))}
+        </ol>
+      </section>
+    </div>
+  )
+}
diff --git a/apps/docs/app/why/page.tsx b/apps/docs/app/why/page.tsx
new file mode 100644
index 0000000..16a0b58
--- /dev/null
+++ b/apps/docs/app/why/page.tsx
@@ -0,0 +1,415 @@
+export default function WhyPage() {
+  return (
+    <div className="max-w-4xl mx-auto px-6 py-16">
+      <div className="mb-8">
+        <a href="/" className="text-sm text-gray-500 hover:text-gray-300 transition-colors">
+          ← Back to docs
+        </a>
+      </div>
+
+      <h1 className="text-4xl font-extrabold mb-4">Manual setup vs hookform-action</h1>
+      <p className="text-gray-400 text-lg mb-16 max-w-2xl">
+        A concrete comparison of wiring React Hook Form with Server Actions by hand, versus using{" "}
+        <code>hookform-action</code> as the integration layer.
+      </p>
+
+      {/* ------------------------------------------------------------------ */}
+      {/* 1. Comparison table                                                 */}
+      {/* ------------------------------------------------------------------ */}
+      <section className="mb-20">
+        <h2 className="text-2xl font-bold mb-2">Feature comparison</h2>
+        <p className="text-gray-500 text-sm mb-6">
+          Each row maps to real code you either write yourself or get for free.
+        </p>
+        <div className="overflow-x-auto">
+          <table className="w-full text-sm text-left border-collapse">
+            <thead>
+              <tr className="border-b border-gray-800 text-gray-400">
+                <th className="py-3 pr-6 font-semibold">Concern</th>
+                <th className="py-3 pr-6 font-semibold text-red-400">Manual</th>
+                <th className="py-3 font-semibold text-brand-400">hookform-action</th>
+              </tr>
+            </thead>
+            <tbody className="text-gray-300 divide-y divide-gray-800/60">
+              <tr>
+                <td className="py-3.5 pr-6 font-medium">Server-side Zod validation</td>
+                <td className="py-3.5 pr-6 text-gray-400">
+                  Write <code>schema.safeParse()</code> + format errors in every action
+                </td>
+                <td className="py-3.5 text-gray-300">
+                  <code>withZod(schema, handler)</code> — one wrapper, done
+                </td>
+              </tr>
+              <tr>
+                <td className="py-3.5 pr-6 font-medium">Error mapping to RHF fields</td>
+                <td className="py-3.5 pr-6 text-gray-400">
+                  Call <code>setError()</code> for each field after parsing the action result
+                </td>
+                <td className="py-3.5 text-gray-300">
+                  Automatic via <code>defaultErrorMapper</code> — override with <code>errorMapper</code> when needed
+                </td>
+              </tr>
+              <tr>
+                <td className="py-3.5 pr-6 font-medium">Client-side validation</td>
+                <td className="py-3.5 pr-6 text-gray-400">
+                  Pass <code>resolver</code> to <code>useForm</code> and keep schema in sync with server
+                </td>
+                <td className="py-3.5 text-gray-300">
+                  Set <code>validationMode</code> — schema auto-detected from <code>withZod</code>
+                </td>
+              </tr>
+              <tr>
+                <td className="py-3.5 pr-6 font-medium">Pending / loading state</td>
+                <td className="py-3.5 pr-6 text-gray-400">
+                  <code>useTransition</code> + <code>useState</code> wiring around <code>startTransition</code>
+                </td>
+                <td className="py-3.5 text-gray-300">
+                  <code>formState.isPending</code> backed by <code>useTransition</code> internally
+                </td>
+              </tr>
+              <tr>
+                <td className="py-3.5 pr-6 font-medium">Optimistic UI</td>
+                <td className="py-3.5 pr-6 text-gray-400">
+                  <code>useOptimistic</code> + <code>useTransition</code> + manual rollback logic
+                </td>
+                <td className="py-3.5 text-gray-300">
+                  <code>optimisticData</code> option — hook handles pending state and rollback
+                </td>
+              </tr>
+              <tr>
+                <td className="py-3.5 pr-6 font-medium">Multi-step persistence</td>
+                <td className="py-3.5 pr-6 text-gray-400">
+                  Custom <code>useEffect</code> + <code>sessionStorage</code> reads/writes per step
+                </td>
+                <td className="py-3.5 text-gray-300">
+                  <code>persistKey</code> option — debounced, SSR-safe, clears on success
+                </td>
+              </tr>
+              <tr>
+                <td className="py-3.5 pr-6 font-medium">FormData support</td>
+                <td className="py-3.5 pr-6 text-gray-400">
+                  Detect action arity and convert <code>FormData</code> to object manually
+                </td>
+                <td className="py-3.5 text-gray-300">
+                  Detected automatically via action arity — <code>withZod</code> handles conversion
+                </td>
+              </tr>
+              <tr>
+                <td className="py-3.5 pr-6 font-medium">Success / error callbacks</td>
+                <td className="py-3.5 pr-6 text-gray-400">
+                  Inline <code>.then()</code>/<code>.catch()</code> chains after calling the action
+                </td>
+                <td className="py-3.5 text-gray-300">
+                  <code>onSuccess</code> / <code>onError</code> options
+                </td>
+              </tr>
+              <tr>
+                <td className="py-3.5 pr-6 font-medium">Debug tooling</td>
+                <td className="py-3.5 pr-6 text-gray-400">RHF DevTools (state only)</td>
+                <td className="py-3.5 text-gray-300">
+                  <code>hookform-action-devtools</code> — full submission history + form state panel
+                </td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </section>
+
+      {/* ------------------------------------------------------------------ */}
+      {/* 2. Workflow comparison                                               */}
+      {/* ------------------------------------------------------------------ */}
+      <section className="mb-20">
+        <h2 className="text-2xl font-bold mb-6">Workflow comparison</h2>
+        <div className="grid sm:grid-cols-2 gap-6">
+          {/* Manual */}
+          <div className="border border-red-800/40 bg-red-950/10 rounded-xl p-6">
+            <h3 className="text-base font-semibold text-red-400 mb-4">Manual — steps per form</h3>
+            <ol className="space-y-3 text-sm text-gray-300 list-decimal list-inside marker:text-red-600">
+              <li>Define Zod schema in a shared module</li>
+              <li>
+                Pass <code>zodResolver(schema)</code> to <code>useForm</code>
+              </li>
+              <li>
+                In the Server Action: call <code>schema.safeParse(data)</code>, format <code>fieldErrors</code>, return
+                them
+              </li>
+              <li>
+                In the component: inspect action result, loop over errors, call <code>setError(field, …)</code> for each
+              </li>
+              <li>
+                Wire <code>useTransition</code> around the action call to get <code>isPending</code>
+              </li>
+              <li>
+                If you need optimistic UI: add <code>useOptimistic</code>, compute next state, pass to{" "}
+                <code>startTransition</code>, handle rollback
+              </li>
+              <li>
+                If you need persistence: write a <code>useEffect</code> to save/restore from <code>sessionStorage</code>
+                , debounce it, clear on unmount
+              </li>
+            </ol>
+            <p className="mt-4 text-xs text-red-400/70">Each new form repeats steps 3–7 from scratch.</p>
+          </div>
+
+          {/* hookform-action */}
+          <div className="border border-brand-700/40 bg-brand-950/10 rounded-xl p-6">
+            <h3 className="text-base font-semibold text-brand-400 mb-4">hookform-action — steps per form</h3>
+            <ol className="space-y-3 text-sm text-gray-300 list-decimal list-inside marker:text-brand-600">
+              <li>
+                Wrap server action with <code>withZod(schema, handler)</code>
+              </li>
+              <li>
+                Call <code>useActionForm(action, options)</code> in the component
+              </li>
+              <li>
+                Use <code>register</code>, <code>handleSubmit()</code>, and <code>formState.errors</code> as you
+                normally would with RHF
+              </li>
+            </ol>
+            <p className="mt-4 text-xs text-brand-400/70">
+              Steps 4–7 from the manual list become opt-in options: <code>validationMode</code>,{" "}
+              <code>optimisticData</code>, <code>persistKey</code>.
+            </p>
+          </div>
+        </div>
+      </section>
+
+      {/* ------------------------------------------------------------------ */}
+      {/* 3. Side-by-side code                                                */}
+      {/* ------------------------------------------------------------------ */}
+      <section className="mb-20">
+        <h2 className="text-2xl font-bold mb-2">Code comparison — Login form</h2>
+        <p className="text-gray-500 text-sm mb-8">
+          Same feature set: server validation, automatic error display, pending state.
+        </p>
+
+        {/* Server Action */}
+        <h3 className="text-base font-semibold text-gray-300 mb-3">
+          <span className="text-gray-500">01 /</span> Server Action
+        </h3>
+        <div className="grid sm:grid-cols-2 gap-4 mb-10">
+          <div>
+            <p className="text-xs text-red-400 font-medium mb-2 uppercase tracking-widest">Manual</p>
+            <div className="code-block text-gray-300 text-xs leading-relaxed">
+              <pre>{`// actions.ts
+'use server'
+import { z } from 'zod'
+
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+})
+
+export async function loginAction(data: unknown) {
+  const parsed = schema.safeParse(data)
+
+  if (!parsed.success) {
+    // Must manually format Zod errors
+    // every time, in every action
+    return {
+      errors: parsed.error.flatten().fieldErrors,
+    }
+  }
+
+  const user = await authenticate(parsed.data)
+  if (!user) {
+    return { errors: { email: ['Invalid credentials'] } }
+  }
+
+  return { success: true }
+}`}</pre>
+            </div>
+          </div>
+          <div>
+            <p className="text-xs text-brand-400 font-medium mb-2 uppercase tracking-widest">hookform-action</p>
+            <div className="code-block text-gray-300 text-xs leading-relaxed">
+              <pre>{`// actions.ts
+'use server'
+import { z } from 'zod'
+import { withZod } from 'hookform-action-core/with-zod'
+
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+})
+
+export const loginAction = withZod(
+  schema,
+  // handler only runs if validation passes
+  // data is fully typed — no casts needed
+  async (data) => {
+    const user = await authenticate(data)
+    if (!user) {
+      return { errors: { email: ['Invalid credentials'] } }
+    }
+    return { success: true }
+  }
+)`}</pre>
+            </div>
+          </div>
+        </div>
+
+        {/* Client component */}
+        <h3 className="text-base font-semibold text-gray-300 mb-3">
+          <span className="text-gray-500">02 /</span> Client component
+        </h3>
+        <div className="grid sm:grid-cols-2 gap-4">
+          <div>
+            <p className="text-xs text-red-400 font-medium mb-2 uppercase tracking-widest">Manual</p>
+            <div className="code-block text-gray-300 text-xs leading-relaxed">
+              <pre>{`// LoginForm.tsx
+'use client'
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { useTransition } from 'react'
+import { z } from 'zod'
+import { loginAction } from './actions'
+
+// Schema must be re-imported/re-defined
+// on the client to feed zodResolver
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+})
+
+type Fields = z.infer<typeof schema>
+
+export function LoginForm() {
+  const [isPending, startTransition] = useTransition()
+
+  const {
+    register,
+    handleSubmit,
+    setError,
+    formState: { errors, isSubmitting },
+  } = useForm<Fields>({
+    resolver: zodResolver(schema),
+    defaultValues: { email: '', password: '' },
+  })
+
+  const onSubmit = (values: Fields) => {
+    startTransition(async () => {
+      const result = await loginAction(values)
+      // Must manually walk error keys
+      if (result?.errors) {
+        for (const [field, messages] of
+          Object.entries(result.errors)) {
+          setError(field as keyof Fields, {
+            message: (messages as string[])[0],
+          })
+        }
+      }
+    })
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email')} />
+      {errors.email && <p>{errors.email.message}</p>}
+      <input {...register('password')} type="password" />
+      {errors.password && <p>{errors.password.message}</p>}
+      <button disabled={isPending || isSubmitting}>
+        {isPending ? 'Signing in…' : 'Sign In'}
+      </button>
+    </form>
+  )
+}`}</pre>
+            </div>
+          </div>
+          <div>
+            <p className="text-xs text-brand-400 font-medium mb-2 uppercase tracking-widest">hookform-action</p>
+            <div className="code-block text-gray-300 text-xs leading-relaxed">
+              <pre>{`// LoginForm.tsx
+'use client'
+import { useActionForm } from 'hookform-action'
+import { loginAction } from './actions'
+
+// No resolver — schema is auto-detected
+// from the withZod wrapper on the action
+
+export function LoginForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isPending },
+  } = useActionForm(loginAction, {
+    defaultValues: { email: '', password: '' },
+    // enable real-time validation with
+    // the same schema — no extra imports
+    validationMode: 'onChange',
+  })
+
+  return (
+    <form onSubmit={handleSubmit()}>
+      <input {...register('email')} />
+      {errors.email && <p>{errors.email.message}</p>}
+      <input {...register('password')} type="password" />
+      {errors.password && <p>{errors.password.message}</p>}
+      <button disabled={isPending}>
+        {isPending ? 'Signing in…' : 'Sign In'}
+      </button>
+    </form>
+  )
+}`}</pre>
+            </div>
+          </div>
+        </div>
+
+        {/* Delta callout */}
+        <div className="mt-6 grid sm:grid-cols-3 gap-4 text-center text-sm">
+          <div className="bg-gray-900/50 border border-gray-800 rounded-xl p-4">
+            <p className="text-2xl font-bold text-red-400 mb-1">~55</p>
+            <p className="text-gray-500 text-xs">lines — manual client component</p>
+          </div>
+          <div className="bg-gray-900/50 border border-gray-800 rounded-xl p-4">
+            <p className="text-2xl font-bold text-brand-400 mb-1">~25</p>
+            <p className="text-gray-500 text-xs">lines — with hookform-action</p>
+          </div>
+          <div className="bg-gray-900/50 border border-gray-800 rounded-xl p-4">
+            <p className="text-2xl font-bold text-emerald-400 mb-1">−3</p>
+            <p className="text-gray-500 text-xs">concepts to keep in sync (resolver, transition, setError loop)</p>
+          </div>
+        </div>
+      </section>
+
+      {/* ------------------------------------------------------------------ */}
+      {/* 4. Conclusion                                                        */}
+      {/* ------------------------------------------------------------------ */}
+      <section className="mb-12">
+        <h2 className="text-2xl font-bold mb-4">Bottom line</h2>
+        <div className="bg-gray-900/50 border border-gray-800 rounded-xl p-8 space-y-4 text-gray-300 leading-relaxed">
+          <p>
+            The manual approach works. React Hook Form, Zod, and Server Actions are well-designed primitives and wiring
+            them yourself is absolutely viable on a small form.
+          </p>
+          <p>
+            The friction compounds as the app grows: every new form repeats the same <code>safeParse</code> boilerplate
+            on the server, the same <code>setError</code> loop on the client, the same <code>useTransition</code>{" "}
+            wrapper for pending state. When you add optimistic updates or multi-step persistence the surface area grows
+            further.
+          </p>
+          <p>
+            <code>hookform-action</code> doesn&apos;t hide any of those primitives — it codifies the patterns you would
+            write anyway into a single hook and a single server wrapper. You keep full access to the underlying{" "}
+            <code>useForm</code> instance and can still pass any RHF option. The goal is to remove the repetitive
+            plumbing, not to abstract away control.
+          </p>
+          <div className="pt-2 flex gap-4">
+            <a
+              href="/examples/login"
+              className="inline-flex items-center px-5 py-2.5 bg-brand-600 hover:bg-brand-500 text-white rounded-lg font-medium text-sm transition-colors"
+            >
+              See it in action →
+            </a>
+            <a
+              href="/api-reference"
+              className="inline-flex items-center px-5 py-2.5 border border-gray-700 hover:border-gray-500 text-gray-300 rounded-lg font-medium text-sm transition-colors"
+            >
+              Full API reference
+            </a>
+          </div>
+        </div>
+      </section>
+    </div>
+  );
+}
diff --git a/packages/core/README.md b/packages/core/README.md
index 9048668..93d82f9 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -1,11 +1,21 @@
 # hookform-action-core
 
-Framework-agnostic core for **hookform-action** — provides the foundational hooks, Zod integration, persistence helpers, and type system shared by all adapters.
+The framework-agnostic core of **hookform-action** for typed React Hook Form submit flows: `withZod`, automatic Zod error mapping, persistence, and optimistic UI. Shared by all adapters.
 
 [![npm version](https://img.shields.io/npm/v/hookform-action-core?style=flat-square&color=5c7cfa)](https://www.npmjs.com/package/hookform-action-core)
 [![npm downloads](https://img.shields.io/npm/dm/hookform-action-core?style=flat-square&color=748ffc)](https://www.npmjs.com/package/hookform-action-core)
 [![license](https://img.shields.io/npm/l/hookform-action-core?style=flat-square)](https://github.com/gabpaesschulz/hookform-action/blob/main/LICENSE)
 
+## Mental Model
+
+`hookform-action-core` is the **framework-agnostic engine**. It doesn't know about Next.js routing or `fetch` — it only understands: _"I have an async function and a schema; wire them into React Hook Form."_
+
+- **`withZod`** — wraps your handler with Zod validation on the server and attaches the schema so the client hook can detect it automatically for real-time validation
+- **`useActionFormCore`** — low-level hook managing the full submit lifecycle (client validation → async call → error mapping → optimistic state → persistence)
+- **Adapters** (`hookform-action`, `hookform-action-standalone`) are thin wrappers that call `useActionFormCore` with environment-specific submission logic
+
+Most users never install this package directly — they install an adapter instead.
+
 > **Most users should install an adapter instead:**
 >
 > - [`hookform-action`](https://www.npmjs.com/package/hookform-action) — for **Next.js** Server Actions
diff --git a/packages/core/package.json b/packages/core/package.json
index 5b98f96..4695595 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,7 +1,7 @@
 {
   "name": "hookform-action-core",
   "version": "4.0.3",
-  "description": "Seamless integration between React Hook Form and Server Actions with Zod validation, automatic type inference, optimistic UI, and multi-step form persistence.",
+  "description": "Framework-agnostic core for typed React Hook Form submit flows: withZod, error mapping, optimistic UI, and persistence.",
   "keywords": [
     "next.js",
     "react-hook-form",
diff --git a/packages/core/src/__tests__/client-validation.test.ts b/packages/core/src/__tests__/client-validation.test.ts
index 11902ed..34e7b07 100644
--- a/packages/core/src/__tests__/client-validation.test.ts
+++ b/packages/core/src/__tests__/client-validation.test.ts
@@ -1,276 +1,276 @@
-import { act, renderHook, waitFor } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
-import { z } from 'zod'
-import type { JsonServerAction } from '../types'
-import { useActionForm } from '../use-action-form'
-import { withZod } from '../with-zod'
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+import type { JsonServerAction } from "../types";
+import { useActionForm } from "../use-action-form";
+import { withZod } from "../with-zod";
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 const signupSchema = z.object({
-  email: z.string().email('Invalid email address'),
-  password: z.string().min(8, 'Password must be at least 8 characters'),
-})
+  email: z.string().email("Invalid email address"),
+  password: z.string().min(8, "Password must be at least 8 characters"),
+});
 
 /** JSON action that always succeeds */
 function createSuccessAction(): JsonServerAction<{ success: true }> {
-  return vi.fn(async (_data: unknown) => ({ success: true as const }))
+  return vi.fn(async (_data: unknown) => ({ success: true as const }));
 }
 
 // ---------------------------------------------------------------------------
 // Tests: Explicit schema validation
 // ---------------------------------------------------------------------------
 
-describe('useActionForm – client-side Zod validation (explicit schema)', () => {
-  it('validates on submit by default and blocks submission on error', async () => {
-    const action = createSuccessAction()
+describe("useActionForm – client-side Zod validation (explicit schema)", () => {
+  it("validates on submit by default and blocks submission on error", async () => {
+    const action = createSuccessAction();
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: 'invalid', password: 'short' },
+        defaultValues: { email: "invalid", password: "short" },
         schema: signupSchema,
-        validationMode: 'onSubmit',
+        clientValidation: "onSubmit",
       }),
-    )
+    );
 
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
       // Action should NOT have been called because client validation failed
-      expect(action).not.toHaveBeenCalled()
+      expect(action).not.toHaveBeenCalled();
       // Errors should be set
-      expect(result.current.formState.submitErrors).not.toBeNull()
-    })
-  })
+      expect(result.current.formState.serverErrors).not.toBeNull();
+    });
+  });
 
-  it('allows submission when client validation passes', async () => {
-    const action = createSuccessAction()
+  it("allows submission when client validation passes", async () => {
+    const action = createSuccessAction();
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: 'valid@test.com', password: '12345678' },
+        defaultValues: { email: "valid@test.com", password: "12345678" },
         schema: signupSchema,
-        validationMode: 'onSubmit',
+        clientValidation: "onSubmit",
       }),
-    )
+    );
 
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
-      expect(action).toHaveBeenCalled()
-      expect(result.current.formState.isSubmitSuccessful).toBe(true)
-    })
-  })
+      expect(action).toHaveBeenCalled();
+      expect(result.current.formState.isSubmitSuccessful).toBe(true);
+    });
+  });
 
-  it('sets specific field errors from client validation', async () => {
-    const action = createSuccessAction()
+  it("sets specific field errors from client validation", async () => {
+    const action = createSuccessAction();
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: 'bad', password: '12345678' },
+        defaultValues: { email: "bad", password: "12345678" },
         schema: signupSchema,
-        validationMode: 'onSubmit',
+        clientValidation: "onSubmit",
       }),
-    )
+    );
 
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
       // Only email should have an error
-      const emailState = result.current.getFieldState('email')
-      expect(emailState.error?.message).toBe('Invalid email address')
-    })
-  })
+      const emailState = result.current.getFieldState("email");
+      expect(emailState.error?.message).toBe("Invalid email address");
+    });
+  });
 
-  it('validates onChange when validationMode is onChange', async () => {
-    const action = createSuccessAction()
+  it("validates onChange when clientValidation is onChange", async () => {
+    const action = createSuccessAction();
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: '', password: '' },
+        defaultValues: { email: "", password: "" },
         schema: signupSchema,
-        validationMode: 'onChange',
+        clientValidation: "onChange",
       }),
-    )
+    );
 
     // Trigger a change with invalid value
     act(() => {
-      result.current.setValue('email', 'bad-email', { shouldDirty: true })
-    })
+      result.current.setValue("email", "bad-email", { shouldDirty: true });
+    });
 
     // Wait for the watch subscription to fire
     await waitFor(() => {
-      const emailState = result.current.getFieldState('email')
-      expect(emailState.error?.message).toBe('Invalid email address')
-    })
-  })
+      const emailState = result.current.getFieldState("email");
+      expect(emailState.error?.message).toBe("Invalid email address");
+    });
+  });
 
-  it('clears errors when field becomes valid on onChange', async () => {
-    const action = createSuccessAction()
+  it("clears errors when field becomes valid on onChange", async () => {
+    const action = createSuccessAction();
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: '', password: '' },
+        defaultValues: { email: "", password: "" },
         schema: signupSchema,
-        validationMode: 'onChange',
+        clientValidation: "onChange",
       }),
-    )
+    );
 
     // Set invalid value
     act(() => {
-      result.current.setValue('email', 'bad', { shouldDirty: true })
-    })
+      result.current.setValue("email", "bad", { shouldDirty: true });
+    });
 
     await waitFor(() => {
-      const emailState = result.current.getFieldState('email')
-      expect(emailState.error?.message).toBe('Invalid email address')
-    })
+      const emailState = result.current.getFieldState("email");
+      expect(emailState.error?.message).toBe("Invalid email address");
+    });
 
     // Set valid value
     act(() => {
-      result.current.setValue('email', 'valid@test.com', { shouldDirty: true })
-    })
+      result.current.setValue("email", "valid@test.com", { shouldDirty: true });
+    });
 
     await waitFor(() => {
-      const emailState = result.current.getFieldState('email')
-      expect(emailState.error).toBeUndefined()
-    })
-  })
-})
+      const emailState = result.current.getFieldState("email");
+      expect(emailState.error).toBeUndefined();
+    });
+  });
+});
 
 // ---------------------------------------------------------------------------
 // Tests: Auto-detected schema from withZod
 // ---------------------------------------------------------------------------
 
-describe('useActionForm – auto-detected schema from withZod', () => {
-  it('withZod attaches __schema to the action', () => {
-    const action = withZod(signupSchema, async (_data) => ({ success: true as const }))
-    expect(action.__schema).toBe(signupSchema)
-  })
+describe("useActionForm – auto-detected schema from withZod", () => {
+  it("withZod attaches __schema to the action", () => {
+    const action = withZod(signupSchema, async (_data) => ({ success: true as const }));
+    expect(action.__schema).toBe(signupSchema);
+  });
 
-  it('auto-detects schema from withZod action and validates on submit', async () => {
+  it("auto-detects schema from withZod action and validates on submit", async () => {
     const handler = vi.fn(async (data: unknown) => ({
       success: true as const,
       data,
-    }))
-    const action = withZod(signupSchema, handler)
+    }));
+    const action = withZod(signupSchema, handler);
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: 'invalid', password: 'short' },
+        defaultValues: { email: "invalid", password: "short" },
         // No explicit schema – should auto-detect from action.__schema
-        validationMode: 'onSubmit',
+        clientValidation: "onSubmit",
       }),
-    )
+    );
 
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
       // Handler should NOT have been called since client validation fails
-      expect(handler).not.toHaveBeenCalled()
-      expect(result.current.formState.submitErrors).not.toBeNull()
-    })
-  })
+      expect(handler).not.toHaveBeenCalled();
+      expect(result.current.formState.serverErrors).not.toBeNull();
+    });
+  });
 
-  it('auto-detected schema validates onChange', async () => {
+  it("auto-detected schema validates onChange", async () => {
     const action = withZod(signupSchema, async (_data) => ({
       success: true as const,
-    }))
+    }));
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: '', password: '' },
+        defaultValues: { email: "", password: "" },
         // Auto-detects schema, validates on change
-        validationMode: 'onChange',
+        clientValidation: "onChange",
       }),
-    )
+    );
 
     act(() => {
-      result.current.setValue('email', 'bad', { shouldDirty: true })
-    })
+      result.current.setValue("email", "bad", { shouldDirty: true });
+    });
 
     await waitFor(() => {
-      const emailState = result.current.getFieldState('email')
-      expect(emailState.error?.message).toBe('Invalid email address')
-    })
-  })
+      const emailState = result.current.getFieldState("email");
+      expect(emailState.error?.message).toBe("Invalid email address");
+    });
+  });
 
-  it('explicit schema takes priority over auto-detected', async () => {
+  it("explicit schema takes priority over auto-detected", async () => {
     const customSchema = z.object({
-      email: z.string().email('Custom error message'),
+      email: z.string().email("Custom error message"),
       password: z.string().min(1),
-    })
+    });
 
     const action = withZod(signupSchema, async (_data) => ({
       success: true as const,
-    }))
+    }));
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: 'bad', password: '12345678' },
+        defaultValues: { email: "bad", password: "12345678" },
         schema: customSchema, // This should take priority
-        validationMode: 'onSubmit',
+        clientValidation: "onSubmit",
       }),
-    )
+    );
 
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
-      const emailState = result.current.getFieldState('email')
-      expect(emailState.error?.message).toBe('Custom error message') // From custom schema, not withZod
-    })
-  })
-})
+      const emailState = result.current.getFieldState("email");
+      expect(emailState.error?.message).toBe("Custom error message"); // From custom schema, not withZod
+    });
+  });
+});
 
 // ---------------------------------------------------------------------------
 // Tests: isPending state (useTransition integration)
 // ---------------------------------------------------------------------------
 
-describe('useActionForm – isPending / useTransition', () => {
-  it('formState includes isPending property', () => {
-    const action = createSuccessAction()
+describe("useActionForm – isPending / useTransition", () => {
+  it("formState includes isPending property", () => {
+    const action = createSuccessAction();
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: '' },
+        defaultValues: { email: "" },
       }),
-    )
+    );
 
-    expect(result.current.formState.isPending).toBe(false)
-  })
+    expect(result.current.formState.isPending).toBe(false);
+  });
 
-  it('isPending resolves to false after successful submission', async () => {
-    const action = createSuccessAction()
+  it("isPending resolves to false after successful submission", async () => {
+    const action = createSuccessAction();
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: 'test@test.com', password: '12345678' },
+        defaultValues: { email: "test@test.com", password: "12345678" },
       }),
-    )
+    );
 
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
-      expect(result.current.formState.isPending).toBe(false)
-      expect(result.current.formState.isSubmitSuccessful).toBe(true)
-    })
-  })
-})
+      expect(result.current.formState.isPending).toBe(false);
+      expect(result.current.formState.isSubmitSuccessful).toBe(true);
+    });
+  });
+});
diff --git a/packages/core/src/__tests__/optimistic.test.ts b/packages/core/src/__tests__/optimistic.test.ts
index 76388d2..7ea09a3 100644
--- a/packages/core/src/__tests__/optimistic.test.ts
+++ b/packages/core/src/__tests__/optimistic.test.ts
@@ -1,209 +1,204 @@
-import { act, renderHook, waitFor } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
-import type { JsonServerAction } from '../types'
-import { useActionForm } from '../use-action-form'
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import type { JsonServerAction } from "../types";
+import { useActionForm } from "../use-action-form";
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 interface TodoItem {
-  id: string
-  title: string
-  completed: boolean
+  id: string;
+  title: string;
+  completed: boolean;
 }
 
 /** JSON action that succeeds – simulates updating a todo */
 function createUpdateTodoAction(): JsonServerAction<{ success: true; data: TodoItem }> {
   return vi.fn(async (data: unknown) => {
-    const d = data as Record<string, unknown>
+    const d = data as Record<string, unknown>;
     return {
       success: true as const,
       data: {
-        id: (d.id as string) ?? 'todo-1',
+        id: (d.id as string) ?? "todo-1",
         title: d.title as string,
         completed: (d.completed as boolean) ?? false,
       },
-    }
-  })
+    };
+  });
 }
 
 /** JSON action that returns errors */
 function createErrorTodoAction(): JsonServerAction<{ errors: { title: string[] } }> {
   return vi.fn(async (_data: unknown) => ({
-    errors: { title: ['Title is required'] },
-  }))
+    errors: { title: ["Title is required"] },
+  }));
 }
 
 /** JSON action that throws */
 function createThrowingTodoAction(): JsonServerAction<{ success: true }> {
   return vi.fn(async (_data: unknown) => {
-    throw new Error('Network error')
-  })
+    throw new Error("Network error");
+  });
 }
 
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('useActionForm – optimistic updates', () => {
+describe("useActionForm – optimistic updates", () => {
   const INITIAL_TODO: TodoItem = {
-    id: 'todo-1',
-    title: 'Buy groceries',
+    id: "todo-1",
+    title: "Buy groceries",
     completed: false,
-  }
+  };
 
-  it('returns optimistic state when optimisticKey and optimisticData are provided', () => {
-    const action = createUpdateTodoAction()
+  it("returns optimistic state when optimisticReducer is provided", () => {
+    const action = createUpdateTodoAction();
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { title: 'Buy groceries', completed: false },
-        optimisticKey: 'todo-1',
-        optimisticInitial: INITIAL_TODO,
-        optimisticData: (current, formValues) => ({
+        defaultValues: { title: "Buy groceries", completed: false },
+        optimisticDefault: INITIAL_TODO,
+        optimisticReducer: (current, formValues) => ({
           ...current,
           title: formValues.title,
           completed: formValues.completed,
         }),
       }),
-    )
+    );
 
-    expect(result.current.optimistic).toBeDefined()
-    expect(result.current.optimistic?.data).toEqual(INITIAL_TODO)
-    expect(result.current.optimistic?.isPending).toBe(false)
-    expect(typeof result.current.optimistic?.rollback).toBe('function')
-  })
+    expect(result.current.optimistic).toBeDefined();
+    expect(result.current.optimistic?.data).toEqual(INITIAL_TODO);
+    expect(result.current.optimistic?.isPending).toBe(false);
+    expect(typeof result.current.optimistic?.rollback).toBe("function");
+  });
 
-  it('returns undefined optimistic when no optimisticKey is set', () => {
-    const action = createUpdateTodoAction()
+  it("returns undefined optimistic when no optimisticReducer is set", () => {
+    const action = createUpdateTodoAction();
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { title: '' },
+        defaultValues: { title: "" },
       }),
-    )
+    );
 
-    expect(result.current.optimistic).toBeUndefined()
-  })
+    expect(result.current.optimistic).toBeUndefined();
+  });
 
-  it('updates optimistic data on successful submit', async () => {
-    const action = createUpdateTodoAction()
+  it("updates optimistic data on successful submit", async () => {
+    const action = createUpdateTodoAction();
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { title: 'Updated title', completed: true },
-        optimisticKey: 'todo-1',
-        optimisticInitial: INITIAL_TODO,
-        optimisticData: (current, formValues) => ({
+        defaultValues: { title: "Updated title", completed: true },
+        optimisticDefault: INITIAL_TODO,
+        optimisticReducer: (current, formValues) => ({
           ...current,
           title: formValues.title,
           completed: formValues.completed,
         }),
       }),
-    )
+    );
 
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(true)
-    })
+      expect(result.current.formState.isSubmitSuccessful).toBe(true);
+    });
 
     // After successful submit, the optimistic state should reflect the update
-    expect(result.current.optimistic?.data.title).toBe('Updated title')
-    expect(result.current.optimistic?.data.completed).toBe(true)
-  })
+    expect(result.current.optimistic?.data.title).toBe("Updated title");
+    expect(result.current.optimistic?.data.completed).toBe(true);
+  });
 
-  it('rolls back optimistic data on action error', async () => {
-    const action = createErrorTodoAction()
+  it("rolls back optimistic data on action error", async () => {
+    const action = createErrorTodoAction();
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { title: '' },
-        optimisticKey: 'todo-1',
-        optimisticInitial: INITIAL_TODO,
-        optimisticData: (current, formValues) => ({
+        defaultValues: { title: "" },
+        optimisticDefault: INITIAL_TODO,
+        optimisticReducer: (current, formValues) => ({
           ...current,
           title: formValues.title,
         }),
       }),
-    )
+    );
 
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(false)
-    })
+      expect(result.current.formState.isSubmitSuccessful).toBe(false);
+    });
 
     // Should have rolled back to original
-    expect(result.current.optimistic?.data.title).toBe('Buy groceries')
-  })
+    expect(result.current.optimistic?.data.title).toBe("Buy groceries");
+  });
 
-  it('rolls back optimistic data on action throw', async () => {
-    const action = createThrowingTodoAction()
+  it("rolls back optimistic data on action throw", async () => {
+    const action = createThrowingTodoAction();
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { title: 'Will fail' },
-        optimisticKey: 'todo-1',
-        optimisticInitial: INITIAL_TODO,
-        optimisticData: (current, formValues) => ({
+        defaultValues: { title: "Will fail" },
+        optimisticDefault: INITIAL_TODO,
+        optimisticReducer: (current, formValues) => ({
           ...current,
           title: formValues.title,
         }),
       }),
-    )
+    );
 
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitting).toBe(false)
-    })
+      expect(result.current.formState.isSubmitting).toBe(false);
+    });
 
     // Should have rolled back to original
-    expect(result.current.optimistic?.data.title).toBe('Buy groceries')
-  })
+    expect(result.current.optimistic?.data.title).toBe("Buy groceries");
+  });
 
-  it('manual rollback restores confirmed state', async () => {
-    const action = createUpdateTodoAction()
+  it("manual rollback restores confirmed state", async () => {
+    const action = createUpdateTodoAction();
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { title: 'Updated title', completed: false },
-        optimisticKey: 'todo-1',
-        optimisticInitial: INITIAL_TODO,
-        optimisticData: (current, formValues) => ({
+        defaultValues: { title: "Updated title", completed: false },
+        optimisticDefault: INITIAL_TODO,
+        optimisticReducer: (current, formValues) => ({
           ...current,
           title: formValues.title,
         }),
       }),
-    )
+    );
 
     // Submit successfully to update confirmed state
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(true)
-    })
+      expect(result.current.formState.isSubmitSuccessful).toBe(true);
+    });
 
     // Now manually rollback
     act(() => {
-      result.current.optimistic?.rollback()
-    })
+      result.current.optimistic?.rollback();
+    });
 
     // The confirmed state after success should be the updated value
-    expect(result.current.optimistic?.data.title).toBe('Updated title')
-  })
-})
+    expect(result.current.optimistic?.data.title).toBe("Updated title");
+  });
+});
diff --git a/packages/core/src/__tests__/persistence.test.ts b/packages/core/src/__tests__/persistence.test.ts
index 86236a9..2453b39 100644
--- a/packages/core/src/__tests__/persistence.test.ts
+++ b/packages/core/src/__tests__/persistence.test.ts
@@ -1,155 +1,155 @@
-import { act, renderHook, waitFor } from '@testing-library/react'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { loadPersistedValues, savePersistedValues } from '../persist'
-import type { ServerAction } from '../types'
-import { useActionForm } from '../use-action-form'
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { loadPersistedValues, savePersistedValues } from "../persist";
+import type { ServerAction } from "../types";
+import { useActionForm } from "../use-action-form";
 
 // ---------------------------------------------------------------------------
 // Persistence integration tests
 // ---------------------------------------------------------------------------
 
-describe('useActionForm – persistence', () => {
-  const PERSIST_KEY = 'wizard-step-1'
+describe("useActionForm – persistence", () => {
+  const PERSIST_KEY = "wizard-step-1";
 
   beforeEach(() => {
-    sessionStorage.clear()
-  })
+    sessionStorage.clear();
+  });
 
-  it('restores values from sessionStorage on mount', () => {
+  it("restores values from sessionStorage on mount", () => {
     // Pre-populate storage
-    savePersistedValues(PERSIST_KEY, { email: 'stored@test.com', name: 'Bob' })
+    savePersistedValues(PERSIST_KEY, { email: "stored@test.com", name: "Bob" });
 
     const action: ServerAction<{ success: true }> = vi.fn(async () => ({
       success: true as const,
-    }))
+    }));
 
     const { result } = renderHook(() =>
       useActionForm(action, {
         persistKey: PERSIST_KEY,
-        defaultValues: { email: '', name: '' },
+        defaultValues: { email: "", name: "" },
       }),
-    )
+    );
 
-    expect(result.current.getValues('email')).toBe('stored@test.com')
-    expect(result.current.getValues('name')).toBe('Bob')
-  })
+    expect(result.current.getValues("email")).toBe("stored@test.com");
+    expect(result.current.getValues("name")).toBe("Bob");
+  });
 
-  it('persists form values to sessionStorage when fields change', async () => {
+  it("persists form values to sessionStorage when fields change", async () => {
     const action: ServerAction<{ success: true }> = vi.fn(async () => ({
       success: true as const,
-    }))
+    }));
 
     const { result } = renderHook(() =>
       useActionForm(action, {
         persistKey: PERSIST_KEY,
-        defaultValues: { email: '' },
+        defaultValues: { email: "" },
         persistDebounce: 50, // shorter for tests
       }),
-    )
+    );
 
     act(() => {
-      result.current.setValue('email', 'typing@test.com')
-    })
+      result.current.setValue("email", "typing@test.com");
+    });
 
     // Wait for debounce
-    await new Promise((r) => setTimeout(r, 100))
+    await new Promise((r) => setTimeout(r, 100));
 
-    const stored = loadPersistedValues<{ email: string }>(PERSIST_KEY)
-    expect(stored?.email).toBe('typing@test.com')
-  })
+    const stored = loadPersistedValues<{ email: string }>(PERSIST_KEY);
+    expect(stored?.email).toBe("typing@test.com");
+  });
 
-  it('clears sessionStorage after successful submission', async () => {
-    savePersistedValues(PERSIST_KEY, { email: 'old@test.com' })
+  it("clears sessionStorage after successful submission", async () => {
+    savePersistedValues(PERSIST_KEY, { email: "old@test.com" });
 
     const action: ServerAction<{ success: true }> = vi.fn(async () => ({
       success: true as const,
-    }))
+    }));
 
     const { result } = renderHook(() =>
       useActionForm(action, {
         persistKey: PERSIST_KEY,
-        defaultValues: { email: 'old@test.com' },
+        defaultValues: { email: "old@test.com" },
       }),
-    )
+    );
 
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(true)
-    })
+      expect(result.current.formState.isSubmitSuccessful).toBe(true);
+    });
 
-    expect(loadPersistedValues(PERSIST_KEY)).toBeNull()
-  })
+    expect(loadPersistedValues(PERSIST_KEY)).toBeNull();
+  });
 
-  it('does NOT clear sessionStorage when submission has errors', async () => {
-    savePersistedValues(PERSIST_KEY, { email: 'bad@test.com' })
+  it("does NOT clear sessionStorage when submission has errors", async () => {
+    savePersistedValues(PERSIST_KEY, { email: "bad@test.com" });
 
     const action: ServerAction<{ errors: { email: string[] } }> = vi.fn(async () => ({
-      errors: { email: ['Invalid'] },
-    }))
+      errors: { email: ["Invalid"] },
+    }));
 
     const { result } = renderHook(() =>
       useActionForm(action, {
         persistKey: PERSIST_KEY,
-        defaultValues: { email: 'bad@test.com' },
+        defaultValues: { email: "bad@test.com" },
       }),
-    )
+    );
 
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(false)
-    })
+      expect(result.current.formState.isSubmitSuccessful).toBe(false);
+    });
 
     // Storage should still exist
-    expect(loadPersistedValues(PERSIST_KEY)).not.toBeNull()
-  })
+    expect(loadPersistedValues(PERSIST_KEY)).not.toBeNull();
+  });
 
-  it('manually persists via persist()', () => {
+  it("manually persists via persist()", () => {
     const action: ServerAction<{ success: true }> = vi.fn(async () => ({
       success: true as const,
-    }))
+    }));
 
     const { result } = renderHook(() =>
       useActionForm(action, {
         persistKey: PERSIST_KEY,
-        defaultValues: { email: '' },
+        defaultValues: { email: "" },
       }),
-    )
+    );
 
     act(() => {
-      result.current.setValue('email', 'manual@test.com')
-      result.current.persist()
-    })
+      result.current.setValue("email", "manual@test.com");
+      result.current.persist();
+    });
 
-    const stored = loadPersistedValues<{ email: string }>(PERSIST_KEY)
-    expect(stored?.email).toBe('manual@test.com')
-  })
+    const stored = loadPersistedValues<{ email: string }>(PERSIST_KEY);
+    expect(stored?.email).toBe("manual@test.com");
+  });
 
-  it('clears persisted data via clearPersistedData()', () => {
-    savePersistedValues(PERSIST_KEY, { email: 'clear@test.com' })
+  it("clears persisted data via clearPersisted()", () => {
+    savePersistedValues(PERSIST_KEY, { email: "clear@test.com" });
 
     const action: ServerAction<{ success: true }> = vi.fn(async () => ({
       success: true as const,
-    }))
+    }));
 
     const { result } = renderHook(() =>
       useActionForm(action, {
         persistKey: PERSIST_KEY,
-        defaultValues: { email: '' },
+        defaultValues: { email: "" },
       }),
-    )
+    );
 
     act(() => {
-      result.current.clearPersistedData()
-    })
+      result.current.clearPersisted();
+    });
 
-    expect(loadPersistedValues(PERSIST_KEY)).toBeNull()
-  })
-})
+    expect(loadPersistedValues(PERSIST_KEY)).toBeNull();
+  });
+});
diff --git a/packages/core/src/__tests__/use-action-form-core.test.ts b/packages/core/src/__tests__/use-action-form-core.test.ts
index 6689f9a..9a73016 100644
--- a/packages/core/src/__tests__/use-action-form-core.test.ts
+++ b/packages/core/src/__tests__/use-action-form-core.test.ts
@@ -1,340 +1,334 @@
-import { act, renderHook, waitFor } from '@testing-library/react'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import type { SubmitFunction } from '../core-types'
-import { useActionFormCore } from '../use-action-form-core'
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { SubmitFunction } from "../core-types";
+import { useActionFormCore } from "../use-action-form-core";
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-function createSuccessSubmit(): SubmitFunction<
-  Record<string, unknown>,
-  { success: true; data: string }
-> {
+function createSuccessSubmit(): SubmitFunction<Record<string, unknown>, { success: true; data: string }> {
   return vi.fn(async (_data: Record<string, unknown>) => ({
     success: true as const,
-    data: 'ok',
-  }))
+    data: "ok",
+  }));
 }
 
-function createErrorSubmit(): SubmitFunction<
-  Record<string, unknown>,
-  { errors: { email: string[] } }
-> {
+function createErrorSubmit(): SubmitFunction<Record<string, unknown>, { errors: { email: string[] } }> {
   return vi.fn(async (_data: Record<string, unknown>) => ({
-    errors: { email: ['Invalid email address'] },
-  }))
+    errors: { email: ["Invalid email address"] },
+  }));
 }
 
 function createThrowingSubmit(): SubmitFunction<Record<string, unknown>, { success: true }> {
   return vi.fn(async (_data: Record<string, unknown>) => {
-    throw new Error('Network failure')
-  })
+    throw new Error("Network failure");
+  });
 }
 
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('useActionFormCore', () => {
+describe("useActionFormCore", () => {
   beforeEach(() => {
-    sessionStorage.clear()
-  })
+    sessionStorage.clear();
+  });
 
   // ---- Basic rendering ----------------------------------------------------
 
-  it('returns all expected core properties', () => {
-    const submit = createSuccessSubmit()
-    const { result } = renderHook(() => useActionFormCore(submit))
+  it("returns all expected core properties", () => {
+    const submit = createSuccessSubmit();
+    const { result } = renderHook(() => useActionFormCore(submit));
 
-    expect(result.current.register).toBeDefined()
-    expect(result.current.handleSubmit).toBeDefined()
-    expect(result.current.formState).toBeDefined()
-    expect(result.current.setSubmitError).toBeDefined()
-    expect(result.current.persist).toBeDefined()
-    expect(result.current.clearPersistedData).toBeDefined()
-    expect(result.current.control).toBeDefined()
-  })
+    expect(result.current.register).toBeDefined();
+    expect(result.current.handleSubmit).toBeDefined();
+    expect(result.current.formState).toBeDefined();
+    expect(result.current.setServerError).toBeDefined();
+    expect(result.current.persist).toBeDefined();
+    expect(result.current.clearPersisted).toBeDefined();
+    expect(result.current.control).toBeDefined();
+  });
 
   it("does NOT have formAction (that's adapter-specific)", () => {
-    const submit = createSuccessSubmit()
-    const { result } = renderHook(() => useActionFormCore(submit))
+    const submit = createSuccessSubmit();
+    const { result } = renderHook(() => useActionFormCore(submit));
 
-    expect((result.current as Record<string, unknown>).formAction).toBeUndefined()
-  })
+    expect((result.current as Record<string, unknown>).formAction).toBeUndefined();
+  });
 
-  it('uses provided defaultValues', () => {
-    const submit = createSuccessSubmit()
+  it("uses provided defaultValues", () => {
+    const submit = createSuccessSubmit();
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { email: 'test@example.com' },
+        defaultValues: { email: "test@example.com" },
       }),
-    )
+    );
 
-    expect(result.current.getValues('email')).toBe('test@example.com')
-  })
+    expect(result.current.getValues("email")).toBe("test@example.com");
+  });
 
   // ---- Successful submission ----------------------------------------------
 
-  it('calls the submit function on handleSubmit', async () => {
-    const submit = createSuccessSubmit()
+  it("calls the submit function on handleSubmit", async () => {
+    const submit = createSuccessSubmit();
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { email: 'test@example.com' },
+        defaultValues: { email: "test@example.com" },
       }),
-    )
+    );
 
     await act(async () => {
-      await result.current.handleSubmit()()
-    })
+      await result.current.handleSubmit()();
+    });
 
     await waitFor(() => {
-      expect(submit).toHaveBeenCalledWith({ email: 'test@example.com' })
-    })
-  })
+      expect(submit).toHaveBeenCalledWith({ email: "test@example.com" });
+    });
+  });
 
-  it('sets isSubmitSuccessful after success', async () => {
-    const submit = createSuccessSubmit()
+  it("sets isSubmitSuccessful after success", async () => {
+    const submit = createSuccessSubmit();
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { name: 'test' },
+        defaultValues: { name: "test" },
       }),
-    )
+    );
 
     await act(async () => {
-      await result.current.handleSubmit()()
-    })
+      await result.current.handleSubmit()();
+    });
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(true)
-      expect(result.current.formState.actionResult).toEqual({ success: true, data: 'ok' })
-    })
-  })
+      expect(result.current.formState.isSubmitSuccessful).toBe(true);
+      expect(result.current.formState.lastResult).toEqual({ success: true, data: "ok" });
+    });
+  });
 
   // ---- Error handling -----------------------------------------------------
 
-  it('maps server errors to form fields', async () => {
-    const submit = createErrorSubmit()
+  it("maps server errors to form fields", async () => {
+    const submit = createErrorSubmit();
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { email: '' },
+        defaultValues: { email: "" },
       }),
-    )
+    );
 
     await act(async () => {
-      await result.current.handleSubmit()()
-    })
+      await result.current.handleSubmit()();
+    });
 
     await waitFor(() => {
-      expect(result.current.formState.submitErrors).toEqual({
-        email: ['Invalid email address'],
-      })
-      expect(result.current.formState.isSubmitSuccessful).toBe(false)
-    })
-  })
-
-  it('handles thrown errors gracefully', async () => {
-    const submit = createThrowingSubmit()
-    const onError = vi.fn()
+      expect(result.current.formState.serverErrors).toEqual({
+        email: ["Invalid email address"],
+      });
+      expect(result.current.formState.isSubmitSuccessful).toBe(false);
+    });
+  });
+
+  it("handles thrown errors gracefully", async () => {
+    const submit = createThrowingSubmit();
+    const onError = vi.fn();
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { email: '' },
+        defaultValues: { email: "" },
         onError,
       }),
-    )
+    );
 
     await act(async () => {
-      await result.current.handleSubmit()()
-    })
+      await result.current.handleSubmit()();
+    });
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(false)
-      expect(onError).toHaveBeenCalled()
-    })
-  })
+      expect(result.current.formState.isSubmitSuccessful).toBe(false);
+      expect(onError).toHaveBeenCalled();
+    });
+  });
 
   // ---- Callbacks ----------------------------------------------------------
 
-  it('calls onSuccess callback', async () => {
-    const submit = createSuccessSubmit()
-    const onSuccess = vi.fn()
+  it("calls onSuccess callback", async () => {
+    const submit = createSuccessSubmit();
+    const onSuccess = vi.fn();
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { name: 'test' },
+        defaultValues: { name: "test" },
         onSuccess,
       }),
-    )
+    );
 
     await act(async () => {
-      await result.current.handleSubmit()()
-    })
+      await result.current.handleSubmit()();
+    });
 
     await waitFor(() => {
-      expect(onSuccess).toHaveBeenCalledWith({ success: true, data: 'ok' })
-    })
-  })
+      expect(onSuccess).toHaveBeenCalledWith({ success: true, data: "ok" });
+    });
+  });
 
-  it('calls onError callback on field errors', async () => {
-    const submit = createErrorSubmit()
-    const onError = vi.fn()
+  it("calls onError callback on field errors", async () => {
+    const submit = createErrorSubmit();
+    const onError = vi.fn();
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { email: '' },
+        defaultValues: { email: "" },
         onError,
       }),
-    )
+    );
 
     await act(async () => {
-      await result.current.handleSubmit()()
-    })
+      await result.current.handleSubmit()();
+    });
 
     await waitFor(() => {
-      expect(onError).toHaveBeenCalled()
-    })
-  })
+      expect(onError).toHaveBeenCalled();
+    });
+  });
 
   // ---- Persistence --------------------------------------------------------
 
-  it('persists values to sessionStorage', async () => {
-    const submit = createSuccessSubmit()
+  it("persists values to sessionStorage", async () => {
+    const submit = createSuccessSubmit();
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { email: '' },
-        persistKey: 'test-core-form',
+        defaultValues: { email: "" },
+        persistKey: "test-core-form",
         persistDebounce: 0,
       }),
-    )
+    );
 
     await act(async () => {
-      result.current.persist()
-    })
+      result.current.persist();
+    });
 
-    const stored = sessionStorage.getItem('test-core-form')
-    expect(stored).toBeTruthy()
-  })
+    const stored = sessionStorage.getItem("test-core-form");
+    expect(stored).toBeTruthy();
+  });
 
-  it('clears persisted data', async () => {
-    sessionStorage.setItem('test-core-clear', JSON.stringify({ email: 'old@test.com' }))
+  it("clears persisted data", async () => {
+    sessionStorage.setItem("test-core-clear", JSON.stringify({ email: "old@test.com" }));
 
-    const submit = createSuccessSubmit()
+    const submit = createSuccessSubmit();
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        persistKey: 'test-core-clear',
+        persistKey: "test-core-clear",
       }),
-    )
+    );
 
     await act(async () => {
-      result.current.clearPersistedData()
-    })
+      result.current.clearPersisted();
+    });
 
-    expect(sessionStorage.getItem('test-core-clear')).toBeNull()
-  })
+    expect(sessionStorage.getItem("test-core-clear")).toBeNull();
+  });
 
-  // ---- setSubmitError -----------------------------------------------------
+  // ---- setServerError -----------------------------------------------------
 
-  it('allows manually setting a server error', async () => {
-    const submit = createSuccessSubmit()
+  it("allows manually setting a server error", async () => {
+    const submit = createSuccessSubmit();
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { email: '' },
+        defaultValues: { email: "" },
       }),
-    )
+    );
 
     act(() => {
-      result.current.setSubmitError('email', 'Custom server error')
-    })
+      result.current.setServerError("email", "Custom server error");
+    });
 
     await waitFor(() => {
-      const emailState = result.current.getFieldState('email')
-      expect(emailState.error?.message).toBe('Custom server error')
-      expect(emailState.error?.type).toBe('server')
-    })
-  })
+      const emailState = result.current.getFieldState("email");
+      expect(emailState.error?.message).toBe("Custom server error");
+      expect(emailState.error?.type).toBe("server");
+    });
+  });
 
   // ---- DevTools control metadata ------------------------------------------
 
-  it('exposes submission history on control for DevTools', async () => {
-    const submit = createSuccessSubmit()
+  it("exposes submission history on control for DevTools", async () => {
+    const submit = createSuccessSubmit();
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { name: 'test' },
+        defaultValues: { name: "test" },
       }),
-    )
+    );
 
     // Initially empty
-    expect(result.current.control._submissionHistory).toEqual([])
+    expect(result.current.control._submissionHistory).toEqual([]);
 
     await act(async () => {
-      await result.current.handleSubmit()()
-    })
+      await result.current.handleSubmit()();
+    });
 
     await waitFor(() => {
-      const history = result.current.control._submissionHistory
-      expect(history).toBeDefined()
-      expect(history?.length).toBe(1)
-      expect(history?.[0]?.success).toBe(true)
-      expect(history?.[0]?.payload).toEqual({ name: 'test' })
-    })
-  })
+      const history = result.current.control._submissionHistory;
+      expect(history).toBeDefined();
+      expect(history?.length).toBe(1);
+      expect(history?.[0]?.success).toBe(true);
+      expect(history?.[0]?.payload).toEqual({ name: "test" });
+    });
+  });
 
   // ---- Plugin lifecycle ---------------------------------------------------
 
-  it('calls plugin onBeforeSubmit and can prevent submission', async () => {
-    const submit = createSuccessSubmit()
-    const onBeforeSubmit = vi.fn().mockReturnValue(false)
+  it("calls plugin onBeforeSubmit and can prevent submission", async () => {
+    const submit = createSuccessSubmit();
+    const onBeforeSubmit = vi.fn().mockReturnValue(false);
 
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { name: 'test' },
-        plugins: [{ name: 'blocker', onBeforeSubmit }],
+        defaultValues: { name: "test" },
+        plugins: [{ name: "blocker", onBeforeSubmit }],
       }),
-    )
+    );
 
     await act(async () => {
-      await result.current.handleSubmit()()
-    })
+      await result.current.handleSubmit()();
+    });
 
     await waitFor(() => {
-      expect(onBeforeSubmit).toHaveBeenCalled()
-      expect(submit).not.toHaveBeenCalled()
-    })
-  })
+      expect(onBeforeSubmit).toHaveBeenCalled();
+      expect(submit).not.toHaveBeenCalled();
+    });
+  });
 
-  it('calls plugin onSuccess after successful submission', async () => {
-    const submit = createSuccessSubmit()
-    const pluginOnSuccess = vi.fn()
+  it("calls plugin onSuccess after successful submission", async () => {
+    const submit = createSuccessSubmit();
+    const pluginOnSuccess = vi.fn();
 
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { name: 'test' },
-        plugins: [{ name: 'logger', onSuccess: pluginOnSuccess }],
+        defaultValues: { name: "test" },
+        plugins: [{ name: "logger", onSuccess: pluginOnSuccess }],
       }),
-    )
+    );
 
     await act(async () => {
-      await result.current.handleSubmit()()
-    })
+      await result.current.handleSubmit()();
+    });
 
     await waitFor(() => {
-      expect(pluginOnSuccess).toHaveBeenCalledWith({ success: true, data: 'ok' }, { name: 'test' })
-    })
-  })
+      expect(pluginOnSuccess).toHaveBeenCalledWith({ success: true, data: "ok" }, { name: "test" });
+    });
+  });
 
-  it('calls plugin onMount and cleanup', () => {
-    const cleanup = vi.fn()
-    const onMount = vi.fn().mockReturnValue(cleanup)
-    const submit = createSuccessSubmit()
+  it("calls plugin onMount and cleanup", () => {
+    const cleanup = vi.fn();
+    const onMount = vi.fn().mockReturnValue(cleanup);
+    const submit = createSuccessSubmit();
 
     const { unmount } = renderHook(() =>
       useActionFormCore(submit, {
-        plugins: [{ name: 'mounter', onMount }],
+        plugins: [{ name: "mounter", onMount }],
       }),
-    )
+    );
 
-    expect(onMount).toHaveBeenCalled()
+    expect(onMount).toHaveBeenCalled();
 
-    unmount()
+    unmount();
 
-    expect(cleanup).toHaveBeenCalled()
-  })
-})
+    expect(cleanup).toHaveBeenCalled();
+  });
+});
diff --git a/packages/core/src/__tests__/use-action-form.test.ts b/packages/core/src/__tests__/use-action-form.test.ts
index 0f2a3a1..67ed55a 100644
--- a/packages/core/src/__tests__/use-action-form.test.ts
+++ b/packages/core/src/__tests__/use-action-form.test.ts
@@ -1,7 +1,7 @@
-import { act, renderHook, waitFor } from '@testing-library/react'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import type { FormDataServerAction, JsonServerAction } from '../types'
-import { useActionForm } from '../use-action-form'
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { FormDataServerAction, JsonServerAction } from "../types";
+import { useActionForm } from "../use-action-form";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -9,327 +9,326 @@ import { useActionForm } from '../use-action-form'
 
 /** Classic FormData action (arity 2) */
 function createSuccessAction(): FormDataServerAction<{ success: true; data: string }> {
-  return vi.fn(async (_prev: unknown, _fd: FormData) => ({ success: true as const, data: 'ok' }))
+  return vi.fn(async (_prev: unknown, _fd: FormData) => ({ success: true as const, data: "ok" }));
 }
 
 /** Classic FormData action that returns errors (arity 2) */
 function createErrorAction(): FormDataServerAction<{
-  errors: { email: string[]; name?: string[] }
+  errors: { email: string[]; name?: string[] };
 }> {
   return vi.fn(async (_prev: unknown, _fd: FormData) => ({
-    errors: { email: ['Invalid email address'], name: ['Name is required'] },
-  }))
+    errors: { email: ["Invalid email address"], name: ["Name is required"] },
+  }));
 }
 
 /** Classic FormData action that throws (arity 2) */
 function createThrowingAction(): FormDataServerAction<{ success: true }> {
   return vi.fn(async (_prev: unknown, _fd: FormData) => {
-    throw new Error('Network failure')
-  })
+    throw new Error("Network failure");
+  });
 }
 
 /** JSON action (arity 1) – success */
 function createJsonSuccessAction(): JsonServerAction<{ success: true; data: string }> {
-  return vi.fn(async (_data: unknown) => ({ success: true as const, data: 'json-ok' }))
+  return vi.fn(async (_data: unknown) => ({ success: true as const, data: "json-ok" }));
 }
 
 /** JSON action (arity 1) – returns errors */
 function createJsonErrorAction(): JsonServerAction<{
-  errors: { email: string[] }
+  errors: { email: string[] };
 }> {
   return vi.fn(async (_data: unknown) => ({
-    errors: { email: ['Invalid email from JSON action'] },
-  }))
+    errors: { email: ["Invalid email from JSON action"] },
+  }));
 }
 
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('useActionForm', () => {
+describe("useActionForm", () => {
   beforeEach(() => {
-    sessionStorage.clear()
-  })
+    sessionStorage.clear();
+  });
 
   // ---- Basic rendering ----------------------------------------------------
 
-  it('returns all expected properties', () => {
-    const action = createSuccessAction()
-    const { result } = renderHook(() => useActionForm(action))
-
-    expect(result.current.register).toBeDefined()
-    expect(result.current.handleSubmit).toBeDefined()
-    expect(result.current.formState).toBeDefined()
-    expect(result.current.setSubmitError).toBeDefined()
-    expect(result.current.persist).toBeDefined()
-    expect(result.current.clearPersistedData).toBeDefined()
-    expect(result.current.formAction).toBeDefined()
-  })
-
-  it('uses provided defaultValues', () => {
-    const action = createSuccessAction()
+  it("returns all expected properties", () => {
+    const action = createSuccessAction();
+    const { result } = renderHook(() => useActionForm(action));
+
+    expect(result.current.register).toBeDefined();
+    expect(result.current.handleSubmit).toBeDefined();
+    expect(result.current.formState).toBeDefined();
+    expect(result.current.setServerError).toBeDefined();
+    expect(result.current.persist).toBeDefined();
+    expect(result.current.clearPersisted).toBeDefined();
+    expect(result.current.formAction).toBeDefined();
+  });
+
+  it("uses provided defaultValues", () => {
+    const action = createSuccessAction();
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: 'test@example.com' },
+        defaultValues: { email: "test@example.com" },
       }),
-    )
+    );
 
-    expect(result.current.getValues('email')).toBe('test@example.com')
-  })
+    expect(result.current.getValues("email")).toBe("test@example.com");
+  });
 
   // ---- Successful submission ----------------------------------------------
 
-  it('submits successfully and updates action state', async () => {
-    const action = createSuccessAction()
-    const onSuccess = vi.fn()
+  it("submits successfully and updates action state", async () => {
+    const action = createSuccessAction();
+    const onSuccess = vi.fn();
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: 'user@test.com' },
+        defaultValues: { email: "user@test.com" },
         onSuccess,
       }),
-    )
+    );
 
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(true)
-      expect(result.current.formState.submitErrors).toBeNull()
-      expect(result.current.formState.actionResult).toEqual({
+      expect(result.current.formState.isSubmitSuccessful).toBe(true);
+      expect(result.current.formState.serverErrors).toBeNull();
+      expect(result.current.formState.lastResult).toEqual({
         success: true,
-        data: 'ok',
-      })
-      expect(onSuccess).toHaveBeenCalledWith({ success: true, data: 'ok' })
-    })
-  })
+        data: "ok",
+      });
+      expect(onSuccess).toHaveBeenCalledWith({ success: true, data: "ok" });
+    });
+  });
 
   // ---- Error mapping ------------------------------------------------------
 
-  it('maps server errors to RHF fields automatically', async () => {
-    const action = createErrorAction()
-    const onError = vi.fn()
+  it("maps server errors to RHF fields automatically", async () => {
+    const action = createErrorAction();
+    const onError = vi.fn();
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: '', name: '' },
+        defaultValues: { email: "", name: "" },
         onError,
       }),
-    )
+    );
 
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(false)
-      expect(result.current.formState.submitErrors).toEqual({
-        email: ['Invalid email address'],
-        name: ['Name is required'],
-      })
+      expect(result.current.formState.isSubmitSuccessful).toBe(false);
+      expect(result.current.formState.serverErrors).toEqual({
+        email: ["Invalid email address"],
+        name: ["Name is required"],
+      });
       // Use getFieldState to check RHF errors (avoids proxy subscription issue in tests)
-      const emailState = result.current.getFieldState('email')
-      const nameState = result.current.getFieldState('name')
-      expect(emailState.error?.message).toBe('Invalid email address')
-      expect(nameState.error?.message).toBe('Name is required')
-      expect(onError).toHaveBeenCalled()
-    })
-  })
+      const emailState = result.current.getFieldState("email");
+      const nameState = result.current.getFieldState("name");
+      expect(emailState.error?.message).toBe("Invalid email address");
+      expect(nameState.error?.message).toBe("Name is required");
+      expect(onError).toHaveBeenCalled();
+    });
+  });
 
-  // ---- setSubmitError -----------------------------------------------------
+  // ---- setServerError -----------------------------------------------------
 
-  it('allows manually setting a server error', async () => {
-    const action = createSuccessAction()
-    const { result } = renderHook(() => useActionForm(action, { defaultValues: { email: '' } }))
+  it("allows manually setting a server error", async () => {
+    const action = createSuccessAction();
+    const { result } = renderHook(() => useActionForm(action, { defaultValues: { email: "" } }));
 
     act(() => {
-      result.current.setSubmitError('email', 'Already taken')
-    })
+      result.current.setServerError("email", "Already taken");
+    });
 
     await waitFor(() => {
-      const emailState = result.current.getFieldState('email')
-      expect(emailState.error?.message).toBe('Already taken')
-      expect(emailState.error?.type).toBe('server')
-    })
-  })
+      const emailState = result.current.getFieldState("email");
+      expect(emailState.error?.message).toBe("Already taken");
+      expect(emailState.error?.type).toBe("server");
+    });
+  });
 
   // ---- Throwing action ----------------------------------------------------
 
-  it('handles action that throws an error', async () => {
-    const action = createThrowingAction()
-    const onError = vi.fn()
+  it("handles action that throws an error", async () => {
+    const action = createThrowingAction();
+    const onError = vi.fn();
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: '' },
+        defaultValues: { email: "" },
         onError,
       }),
-    )
+    );
 
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(false)
-      expect(result.current.formState.isSubmitting).toBe(false)
-      expect(onError).toHaveBeenCalledWith(expect.any(Error))
-    })
-  })
+      expect(result.current.formState.isSubmitSuccessful).toBe(false);
+      expect(result.current.formState.isSubmitting).toBe(false);
+      expect(onError).toHaveBeenCalledWith(expect.any(Error));
+    });
+  });
 
   // ---- Custom error mapper ------------------------------------------------
 
-  it('supports custom error mapper', async () => {
-    const action: FormDataServerAction<{ validationErrors: { field: string; msg: string }[] }> =
-      vi.fn(async (_prev: unknown, _fd: FormData) => ({
-        validationErrors: [{ field: 'email', msg: 'Bad email' }],
-      }))
+  it("supports custom error mapper", async () => {
+    const action: FormDataServerAction<{ validationErrors: { field: string; msg: string }[] }> = vi.fn(
+      async (_prev: unknown, _fd: FormData) => ({
+        validationErrors: [{ field: "email", msg: "Bad email" }],
+      }),
+    );
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: '' },
+        defaultValues: { email: "" },
         errorMapper: (res) => {
-          if ('validationErrors' in res && Array.isArray(res.validationErrors)) {
-            const errors: Record<string, string[]> = {}
+          if ("validationErrors" in res && Array.isArray(res.validationErrors)) {
+            const errors: Record<string, string[]> = {};
             for (const err of res.validationErrors) {
-              errors[err.field] = [err.msg]
+              errors[err.field] = [err.msg];
             }
-            return errors
+            return errors;
           }
-          return null
+          return null;
         },
       }),
-    )
+    );
 
     await act(async () => {
-      const handler = result.current.handleSubmit()
-      await handler()
-    })
+      const handler = result.current.handleSubmit();
+      await handler();
+    });
 
     await waitFor(() => {
-      const emailState = result.current.getFieldState('email')
-      expect(emailState.error?.message).toBe('Bad email')
-    })
-  })
+      const emailState = result.current.getFieldState("email");
+      expect(emailState.error?.message).toBe("Bad email");
+    });
+  });
 
   // ---- onValid callback ---------------------------------------------------
 
-  it('calls onValid callback before submitting', async () => {
-    const action = createSuccessAction()
-    const onValid = vi.fn()
+  it("calls onValid callback before submitting", async () => {
+    const action = createSuccessAction();
+    const onValid = vi.fn();
 
-    const { result } = renderHook(() =>
-      useActionForm(action, { defaultValues: { email: 'a@b.com' } }),
-    )
+    const { result } = renderHook(() => useActionForm(action, { defaultValues: { email: "a@b.com" } }));
 
     await act(async () => {
-      const handler = result.current.handleSubmit(onValid)
-      await handler()
-    })
+      const handler = result.current.handleSubmit(onValid);
+      await handler();
+    });
 
-    expect(onValid).toHaveBeenCalledWith({ email: 'a@b.com' })
-    expect(action).toHaveBeenCalled()
-  })
+    expect(onValid).toHaveBeenCalledWith({ email: "a@b.com" });
+    expect(action).toHaveBeenCalled();
+  });
 
   // ---- formAction ---------------------------------------------------------
 
-  it('formAction submits directly with FormData', async () => {
-    const action = createSuccessAction()
-    const { result } = renderHook(() => useActionForm(action))
+  it("formAction submits directly with FormData", async () => {
+    const action = createSuccessAction();
+    const { result } = renderHook(() => useActionForm(action));
 
-    const fd = new FormData()
-    fd.append('email', 'direct@test.com')
+    const fd = new FormData();
+    fd.append("email", "direct@test.com");
 
     await act(async () => {
-      await result.current.formAction(fd)
-    })
+      await result.current.formAction(fd);
+    });
 
     await waitFor(() => {
-      expect(action).toHaveBeenCalledWith(null, fd)
-      expect(result.current.formState.isSubmitSuccessful).toBe(true)
-    })
-  })
+      expect(action).toHaveBeenCalledWith(null, fd);
+      expect(result.current.formState.isSubmitSuccessful).toBe(true);
+    });
+  });
 
   // =========================================================================
   // JSON action tests (arity 1)
   // =========================================================================
 
-  describe('JSON actions (arity 1)', () => {
-    it('submits successfully with a JSON action', async () => {
-      const action = createJsonSuccessAction()
-      const onSuccess = vi.fn()
+  describe("JSON actions (arity 1)", () => {
+    it("submits successfully with a JSON action", async () => {
+      const action = createJsonSuccessAction();
+      const onSuccess = vi.fn();
 
       const { result } = renderHook(() =>
         useActionForm(action, {
-          defaultValues: { email: 'json@test.com' },
+          defaultValues: { email: "json@test.com" },
           onSuccess,
         }),
-      )
+      );
 
       await act(async () => {
-        const handler = result.current.handleSubmit()
-        await handler()
-      })
+        const handler = result.current.handleSubmit();
+        await handler();
+      });
 
       await waitFor(() => {
-        expect(result.current.formState.isSubmitSuccessful).toBe(true)
-        expect(result.current.formState.actionResult).toEqual({
+        expect(result.current.formState.isSubmitSuccessful).toBe(true);
+        expect(result.current.formState.lastResult).toEqual({
           success: true,
-          data: 'json-ok',
-        })
-        expect(onSuccess).toHaveBeenCalledWith({ success: true, data: 'json-ok' })
+          data: "json-ok",
+        });
+        expect(onSuccess).toHaveBeenCalledWith({ success: true, data: "json-ok" });
         // The action should have been called with a plain object, NOT FormData
-        expect(action).toHaveBeenCalledWith({ email: 'json@test.com' })
-      })
-    })
+        expect(action).toHaveBeenCalledWith({ email: "json@test.com" });
+      });
+    });
 
-    it('maps errors from a JSON action to RHF fields', async () => {
-      const action = createJsonErrorAction()
-      const onError = vi.fn()
+    it("maps errors from a JSON action to RHF fields", async () => {
+      const action = createJsonErrorAction();
+      const onError = vi.fn();
 
       const { result } = renderHook(() =>
         useActionForm(action, {
-          defaultValues: { email: '' },
+          defaultValues: { email: "" },
           onError,
         }),
-      )
+      );
 
       await act(async () => {
-        const handler = result.current.handleSubmit()
-        await handler()
-      })
+        const handler = result.current.handleSubmit();
+        await handler();
+      });
 
       await waitFor(() => {
-        expect(result.current.formState.isSubmitSuccessful).toBe(false)
-        expect(result.current.formState.submitErrors).toEqual({
-          email: ['Invalid email from JSON action'],
-        })
-        const emailState = result.current.getFieldState('email')
-        expect(emailState.error?.message).toBe('Invalid email from JSON action')
-        expect(onError).toHaveBeenCalled()
-      })
-    })
-
-    it('formAction converts FormData to object for JSON actions', async () => {
-      const action = createJsonSuccessAction()
-      const { result } = renderHook(() => useActionForm(action))
-
-      const fd = new FormData()
-      fd.append('email', 'fd-to-json@test.com')
+        expect(result.current.formState.isSubmitSuccessful).toBe(false);
+        expect(result.current.formState.serverErrors).toEqual({
+          email: ["Invalid email from JSON action"],
+        });
+        const emailState = result.current.getFieldState("email");
+        expect(emailState.error?.message).toBe("Invalid email from JSON action");
+        expect(onError).toHaveBeenCalled();
+      });
+    });
+
+    it("formAction converts FormData to object for JSON actions", async () => {
+      const action = createJsonSuccessAction();
+      const { result } = renderHook(() => useActionForm(action));
+
+      const fd = new FormData();
+      fd.append("email", "fd-to-json@test.com");
 
       await act(async () => {
-        await result.current.formAction(fd)
-      })
+        await result.current.formAction(fd);
+      });
 
       await waitFor(() => {
         // JSON action should receive a plain object, not FormData
-        expect(action).toHaveBeenCalledWith({ email: 'fd-to-json@test.com' })
-        expect(result.current.formState.isSubmitSuccessful).toBe(true)
-      })
-    })
-  })
-})
+        expect(action).toHaveBeenCalledWith({ email: "fd-to-json@test.com" });
+        expect(result.current.formState.isSubmitSuccessful).toBe(true);
+      });
+    });
+  });
+});
diff --git a/packages/core/src/core-types.ts b/packages/core/src/core-types.ts
index cec9208..8e2a418 100644
--- a/packages/core/src/core-types.ts
+++ b/packages/core/src/core-types.ts
@@ -1,5 +1,5 @@
-import type { DefaultValues, FieldValues, Mode, UseFormReturn } from 'react-hook-form'
-import type { ZodSchema } from 'zod'
+import type { DefaultValues, FieldValues, Mode, UseFormReturn } from "react-hook-form";
+import type { ZodSchema } from "zod";
 
 // ---------------------------------------------------------------------------
 // Field-level error shape (Zod `.flatten().fieldErrors` compatible)
@@ -9,7 +9,7 @@ import type { ZodSchema } from 'zod'
  * Record mapping field names to arrays of error messages.
  * This is the shape produced by `ZodError.flatten().fieldErrors`.
  */
-export type FieldErrorRecord = Record<string, string[] | undefined>
+export type FieldErrorRecord = Record<string, string[] | undefined>;
 
 // ---------------------------------------------------------------------------
 // Default action result shape
@@ -19,10 +19,10 @@ export type FieldErrorRecord = Record<string, string[] | undefined>
  * Standard result type from an action that uses Zod validation.
  */
 export interface ActionResult<TData = unknown> {
-  success?: boolean
-  errors?: FieldErrorRecord
-  data?: TData
-  message?: string
+  success?: boolean;
+  errors?: FieldErrorRecord;
+  data?: TData;
+  message?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -33,7 +33,7 @@ export interface ActionResult<TData = unknown> {
  * A function that takes the raw action result and extracts field errors.
  * Return `null` or `undefined` if there are no errors.
  */
-export type ErrorMapper<TResult> = (result: TResult) => FieldErrorRecord | null | undefined
+export type ErrorMapper<TResult> = (result: TResult) => FieldErrorRecord | null | undefined;
 
 /**
  * Default error mapper that works with the standard Zod flatten format:
@@ -42,14 +42,14 @@ export type ErrorMapper<TResult> = (result: TResult) => FieldErrorRecord | null
 export function defaultErrorMapper<TResult>(result: TResult): FieldErrorRecord | null | undefined {
   if (
     result &&
-    typeof result === 'object' &&
-    'errors' in result &&
+    typeof result === "object" &&
+    "errors" in result &&
     result.errors &&
-    typeof result.errors === 'object'
+    typeof result.errors === "object"
   ) {
-    return result.errors as FieldErrorRecord
+    return result.errors as FieldErrorRecord;
   }
-  return null
+  return null;
 }
 
 // ---------------------------------------------------------------------------
@@ -62,7 +62,7 @@ export function defaultErrorMapper<TResult>(result: TResult): FieldErrorRecord |
  * - `'onChange'` – validate on every field change
  * - `'onBlur'`  – validate when a field loses focus
  */
-export type ClientValidationMode = 'onSubmit' | 'onChange' | 'onBlur'
+export type ClientValidationMode = "onSubmit" | "onChange" | "onBlur";
 
 // ---------------------------------------------------------------------------
 // Optimistic UI types
@@ -76,7 +76,7 @@ export type ClientValidationMode = 'onSubmit' | 'onChange' | 'onBlur'
 export type OptimisticReducer<TOptimistic, TFieldValues extends FieldValues = FieldValues> = (
   currentData: TOptimistic,
   formValues: TFieldValues,
-) => TOptimistic
+) => TOptimistic;
 
 /**
  * The optimistic state object returned by the hook when
@@ -84,11 +84,11 @@ export type OptimisticReducer<TOptimistic, TFieldValues extends FieldValues = Fi
  */
 export interface OptimisticState<TOptimistic> {
   /** The current optimistic data (updated instantly on submit). */
-  data: TOptimistic
+  data: TOptimistic;
   /** Whether an optimistic update is pending (action in flight). */
-  isPending: boolean
+  isPending: boolean;
   /** Manually revert to the last confirmed state. */
-  rollback: () => void
+  rollback: () => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -99,9 +99,7 @@ export interface OptimisticState<TOptimistic> {
  * A generic async submit function. Adapters (Next.js, standalone, etc.)
  * are responsible for wrapping their specific action into this shape.
  */
-export type SubmitFunction<TFieldValues extends FieldValues, TResult> = (
-  data: TFieldValues,
-) => Promise<TResult>
+export type SubmitFunction<TFieldValues extends FieldValues, TResult> = (data: TFieldValues) => Promise<TResult>;
 
 // ---------------------------------------------------------------------------
 // Plugin interface (internal, v3)
@@ -111,20 +109,17 @@ export type SubmitFunction<TFieldValues extends FieldValues, TResult> = (
  * Internal plugin interface for extending useActionFormCore behavior.
  * Not part of the public API yet — used for internal composition.
  */
-export interface ActionFormPlugin<
-  TFieldValues extends FieldValues = FieldValues,
-  TResult = ActionResult,
-> {
+export interface ActionFormPlugin<TFieldValues extends FieldValues = FieldValues, TResult = ActionResult> {
   /** Unique name for debugging */
-  name: string
+  name: string;
   /** Called before submit. Return false to prevent submission. */
-  onBeforeSubmit?: (data: TFieldValues) => boolean | Promise<boolean>
+  onBeforeSubmit?: (data: TFieldValues) => boolean | Promise<boolean>;
   /** Called after a successful submission. */
-  onSuccess?: (result: TResult, data: TFieldValues) => void
+  onSuccess?: (result: TResult, data: TFieldValues) => void;
   /** Called after a failed submission. */
-  onError?: (error: TResult | Error, data: TFieldValues) => void
+  onError?: (error: TResult | Error, data: TFieldValues) => void;
   /** Called on mount. Return a cleanup function. */
-  onMount?: () => (() => void) | undefined
+  onMount?: () => (() => void) | undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -141,41 +136,41 @@ export interface UseActionFormCoreOptions<
    * If `persistKey` is provided and stored data exists, persisted values
    * take precedence.
    */
-  defaultValues?: DefaultValues<TFieldValues>
+  defaultValues?: DefaultValues<TFieldValues>;
 
   /**
    * Validation mode passed to React Hook Form.
    * @default 'onSubmit'
    */
-  mode?: Mode
+  mode?: Mode;
 
   /**
    * When provided, enables transparent sessionStorage persistence.
    * The form state is saved under this key and restored on mount.
    */
-  persistKey?: string
+  persistKey?: string;
 
   /**
    * Custom function to extract field errors from the action result.
    * By default supports the Zod `.flatten().fieldErrors` format.
    */
-  errorMapper?: ErrorMapper<TResult>
+  errorMapper?: ErrorMapper<TResult>;
 
   /**
    * Callback fired after a successful submission (no field errors returned).
    */
-  onSuccess?: (result: TResult) => void
+  onSuccess?: (result: TResult) => void;
 
   /**
    * Callback fired when the action throws or returns field errors.
    */
-  onError?: (result: TResult | Error) => void
+  onError?: (result: TResult | Error) => void;
 
   /**
    * Debounce interval (ms) for sessionStorage persistence.
    * @default 300
    */
-  persistDebounce?: number
+  persistDebounce?: number;
 
   // ---- Client-side Zod validation -----------------------------------------
 
@@ -183,35 +178,49 @@ export interface UseActionFormCoreOptions<
    * Zod schema for client-side validation.
    * If provided, fields are validated in real-time (based on `validationMode`).
    */
-  schema?: ZodSchema
+  schema?: ZodSchema;
 
   /**
    * Controls when client-side Zod schema validation runs.
    * Only takes effect when `schema` is provided.
    * @default 'onSubmit'
    */
-  validationMode?: ClientValidationMode
+  validationMode?: ClientValidationMode;
+
+  /**
+   * Alias for `validationMode`.
+   * @deprecated Use `validationMode` instead.
+   */
+  clientValidation?: ClientValidationMode;
 
   // ---- Optimistic UI ------------------------------------------------------
 
   /**
-   * Unique key identifying the optimistic state.
-   * When provided (along with `optimisticData`), enables optimistic updates.
+   * Optional key used to enable optimistic UI mode and identify optimistic data.
+   */
+  optimisticKey?: string;
+
+  /**
+   * Reducer that computes optimistic data from current data + submitted values.
+   */
+  optimisticData?: OptimisticReducer<TOptimistic, TFieldValues>;
+
+  /**
+   * Initial (confirmed) data used by optimistic mode.
    */
-  optimisticKey?: string
+  optimisticInitial?: TOptimistic;
 
   /**
-   * Reducer that computes the optimistic state from the current data and
-   * the form values being submitted.
-   * Required when `optimisticKey` is set.
+   * Alias for `optimisticData`.
+   * @deprecated Use `optimisticData` instead.
    */
-  optimisticData?: OptimisticReducer<TOptimistic, TFieldValues>
+  optimisticReducer?: OptimisticReducer<TOptimistic, TFieldValues>;
 
   /**
-   * Initial data for the optimistic state.
-   * This is the "confirmed" state before any optimistic updates.
+   * Alias for `optimisticInitial`.
+   * @deprecated Use `optimisticInitial` instead.
    */
-  optimisticInitial?: TOptimistic
+  optimisticDefault?: TOptimistic;
 
   // ---- Internal plugins (v3) ----------------------------------------------
 
@@ -219,7 +228,7 @@ export interface UseActionFormCoreOptions<
    * Internal plugin array. Not part of the public API yet.
    * @internal
    */
-  plugins?: ActionFormPlugin<TFieldValues, TResult>[]
+  plugins?: ActionFormPlugin<TFieldValues, TResult>[];
 }
 
 // ---------------------------------------------------------------------------
@@ -228,17 +237,27 @@ export interface UseActionFormCoreOptions<
 
 export interface ActionFormState<TResult> {
   /** Whether the form is currently being submitted. */
-  isSubmitting: boolean
+  isSubmitting: boolean;
   /** Whether the last submission was successful (no field errors). */
-  isSubmitSuccessful: boolean
+  isSubmitSuccessful: boolean;
   /** Raw error record returned by the action (via errorMapper). */
-  submitErrors: FieldErrorRecord | null
-  /** The full result from the last action invocation, if any. */
-  actionResult: TResult | null
+  submitErrors: FieldErrorRecord | null;
+  /** Full result from the last action invocation, if any. */
+  actionResult: TResult | null;
+  /**
+   * Alias for `submitErrors`.
+   * @deprecated Use `submitErrors` instead.
+   */
+  serverErrors: FieldErrorRecord | null;
+  /**
+   * Alias for `actionResult`.
+   * @deprecated Use `actionResult` instead.
+   */
+  lastResult: TResult | null;
   /**
    * `true` while a transition is pending.
    */
-  isPending: boolean
+  isPending: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -249,7 +268,7 @@ export interface UseActionFormCoreReturn<
   TFieldValues extends FieldValues = FieldValues,
   TResult = ActionResult,
   TOptimistic = undefined,
-> extends Omit<UseFormReturn<TFieldValues>, 'handleSubmit'> {
+> extends Omit<UseFormReturn<TFieldValues>, "handleSubmit"> {
   /**
    * Enhanced handleSubmit that submits via the provided submit function.
    * Call with no arguments: `onSubmit={handleSubmit()}`.
@@ -257,46 +276,58 @@ export interface UseActionFormCoreReturn<
    */
   handleSubmit: (
     onValid?: (data: TFieldValues) => void | Promise<void>,
-  ) => (e?: React.BaseSyntheticEvent) => Promise<void>
+  ) => (e?: React.BaseSyntheticEvent) => Promise<void>;
 
   /**
    * Extended form state including action status.
    */
-  formState: UseFormReturn<TFieldValues>['formState'] & ActionFormState<TResult>
+  formState: UseFormReturn<TFieldValues>["formState"] & ActionFormState<TResult>;
 
   /**
    * Manually set a server-side error on a specific field.
    */
-  setSubmitError: (field: keyof TFieldValues & string, message: string) => void
+  setSubmitError: (field: keyof TFieldValues & string, message: string) => void;
+
+  /**
+   * Alias for `setSubmitError`.
+   * @deprecated Use `setSubmitError` instead.
+   */
+  setServerError: (field: keyof TFieldValues & string, message: string) => void;
 
   /**
    * Manually persist the current form state to sessionStorage.
    * Only works when `persistKey` is set.
    */
-  persist: () => void
+  persist: () => void;
 
   /**
    * Clear persisted data from sessionStorage.
    * Only works when `persistKey` is set.
    */
-  clearPersistedData: () => void
+  clearPersistedData: () => void;
+
+  /**
+   * Alias for `clearPersistedData`.
+   * @deprecated Use `clearPersistedData` instead.
+   */
+  clearPersisted: () => void;
 
   /**
    * Optimistic state. Only populated when `optimisticKey` is provided.
    * Contains `data`, `isPending`, and `rollback()`.
    */
-  optimistic: TOptimistic extends undefined ? undefined : OptimisticState<TOptimistic>
+  optimistic: TOptimistic extends undefined ? undefined : OptimisticState<TOptimistic>;
 
   /**
    * A control object that exposes internals for DevTools.
    * @internal
    */
-  control: UseFormReturn<TFieldValues>['control'] & {
+  control: UseFormReturn<TFieldValues>["control"] & {
     /** Submission history for DevTools inspection. */
-    _submissionHistory?: SubmissionRecord<TResult>[]
+    _submissionHistory?: SubmissionRecord<TResult>[];
     /** The core action form state. */
-    _actionFormState?: ActionFormState<TResult>
-  }
+    _actionFormState?: ActionFormState<TResult>;
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -305,17 +336,17 @@ export interface UseActionFormCoreReturn<
 
 export interface SubmissionRecord<TResult> {
   /** Unique ID for this submission */
-  id: string
+  id: string;
   /** Timestamp of submission */
-  timestamp: number
+  timestamp: number;
   /** The payload sent */
-  payload: Record<string, unknown>
+  payload: Record<string, unknown>;
   /** The response from the action */
-  response: TResult | null
+  response: TResult | null;
   /** Error, if any */
-  error: Error | null
+  error: Error | null;
   /** Duration in ms */
-  duration: number
+  duration: number;
   /** Whether the submission was successful */
-  success: boolean
+  success: boolean;
 }
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
index b502173..19668d4 100644
--- a/packages/core/src/types.ts
+++ b/packages/core/src/types.ts
@@ -1,5 +1,5 @@
-import type { DefaultValues, FieldValues, Mode, UseFormReturn } from 'react-hook-form'
-import type { ZodSchema } from 'zod'
+import type { DefaultValues, FieldValues, Mode, UseFormReturn } from "react-hook-form";
+import type { ZodSchema } from "zod";
 
 // ---------------------------------------------------------------------------
 // Server Action type – supports both Next.js App Router conventions:
@@ -10,7 +10,7 @@ import type { ZodSchema } from 'zod'
 /**
  * A Server Action that receives a single JSON payload and returns a promise.
  */
-export type JsonServerAction<TResult = unknown> = (data: unknown) => Promise<TResult>
+export type JsonServerAction<TResult = unknown> = (data: unknown) => Promise<TResult>;
 
 /**
  * A Server Action that receives the previous state and a FormData.
@@ -19,28 +19,23 @@ export type JsonServerAction<TResult = unknown> = (data: unknown) => Promise<TRe
 export type FormDataServerAction<TResult = unknown> = (
   prevState: Awaited<TResult> | null,
   formData: FormData,
-) => Promise<TResult>
+) => Promise<TResult>;
 
 /**
  * Represents a Next.js Server Action function signature.
  * Supports both the classic (prevState, formData) signature and the
  * simpler (data) => Promise signature for JSON-based actions.
  */
-export type ServerAction<TResult = unknown> =
-  | JsonServerAction<TResult>
-  | FormDataServerAction<TResult>
+export type ServerAction<TResult = unknown> = JsonServerAction<TResult> | FormDataServerAction<TResult>;
 
 /**
  * A Server Action created with `withZod` that has the schema attached.
  * This allows `useActionForm` to automatically infer the schema for
  * client-side validation.
  */
-export type ZodServerAction<
-  TSchema extends ZodSchema = ZodSchema,
-  TResult = unknown,
-> = ServerAction<TResult> & {
-  __schema: TSchema
-}
+export type ZodServerAction<TSchema extends ZodSchema = ZodSchema, TResult = unknown> = ServerAction<TResult> & {
+  __schema: TSchema;
+};
 
 // ---------------------------------------------------------------------------
 // Infer the result type of a Server Action
@@ -52,8 +47,8 @@ export type ZodServerAction<
 export type InferActionResult<TAction> = TAction extends JsonServerAction<infer R>
   ? Awaited<R>
   : TAction extends FormDataServerAction<infer R>
-    ? Awaited<R>
-    : never
+  ? Awaited<R>
+  : never;
 
 // ---------------------------------------------------------------------------
 // Standard field-level error shape returned by Zod `.flatten().fieldErrors`
@@ -63,7 +58,7 @@ export type InferActionResult<TAction> = TAction extends JsonServerAction<infer
  * Record mapping field names to arrays of error messages.
  * This is the shape produced by `ZodError.flatten().fieldErrors`.
  */
-export type FieldErrorRecord = Record<string, string[] | undefined>
+export type FieldErrorRecord = Record<string, string[] | undefined>;
 
 // ---------------------------------------------------------------------------
 // Default action result shape (what most Server Actions return)
@@ -73,10 +68,10 @@ export type FieldErrorRecord = Record<string, string[] | undefined>
  * Standard result type from a Server Action that uses Zod validation.
  */
 export interface ActionResult<TData = unknown> {
-  success?: boolean
-  errors?: FieldErrorRecord
-  data?: TData
-  message?: string
+  success?: boolean;
+  errors?: FieldErrorRecord;
+  data?: TData;
+  message?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -87,16 +82,14 @@ export interface ActionResult<TData = unknown> {
  * A function that takes the raw action result and extracts field errors.
  * Return `null` or `undefined` if there are no errors.
  */
-export type ErrorMapper<TResult> = (result: TResult) => FieldErrorRecord | null | undefined
+export type ErrorMapper<TResult> = (result: TResult) => FieldErrorRecord | null | undefined;
 
 /**
  * Detect whether a Server Action uses the FormData signature (arity === 2)
  * or the JSON signature (arity <= 1).
  */
-export function isFormDataAction<TResult>(
-  action: ServerAction<TResult>,
-): action is FormDataServerAction<TResult> {
-  return action.length >= 2
+export function isFormDataAction<TResult>(action: ServerAction<TResult>): action is FormDataServerAction<TResult> {
+  return action.length >= 2;
 }
 
 /**
@@ -106,14 +99,14 @@ export function isFormDataAction<TResult>(
 export function defaultErrorMapper<TResult>(result: TResult): FieldErrorRecord | null | undefined {
   if (
     result &&
-    typeof result === 'object' &&
-    'errors' in result &&
+    typeof result === "object" &&
+    "errors" in result &&
     result.errors &&
-    typeof result.errors === 'object'
+    typeof result.errors === "object"
   ) {
-    return result.errors as FieldErrorRecord
+    return result.errors as FieldErrorRecord;
   }
-  return null
+  return null;
 }
 
 /**
@@ -123,7 +116,7 @@ export function defaultErrorMapper<TResult>(result: TResult): FieldErrorRecord |
 export function hasAttachedSchema<TResult>(
   action: ServerAction<TResult>,
 ): action is ZodServerAction<ZodSchema, TResult> {
-  return '__schema' in action && (action as unknown as Record<string, unknown>).__schema != null
+  return "__schema" in action && (action as unknown as Record<string, unknown>).__schema != null;
 }
 
 // ---------------------------------------------------------------------------
@@ -136,7 +129,7 @@ export function hasAttachedSchema<TResult>(
  * - `'onChange'` – validate on every field change
  * - `'onBlur'`  – validate when a field loses focus
  */
-export type ClientValidationMode = 'onSubmit' | 'onChange' | 'onBlur'
+export type ClientValidationMode = "onSubmit" | "onChange" | "onBlur";
 
 // ---------------------------------------------------------------------------
 // Optimistic UI types
@@ -150,7 +143,7 @@ export type ClientValidationMode = 'onSubmit' | 'onChange' | 'onBlur'
 export type OptimisticReducer<TOptimistic, TFieldValues extends FieldValues = FieldValues> = (
   currentData: TOptimistic,
   formValues: TFieldValues,
-) => TOptimistic
+) => TOptimistic;
 
 /**
  * The optimistic state object returned by `useActionForm` when
@@ -158,11 +151,11 @@ export type OptimisticReducer<TOptimistic, TFieldValues extends FieldValues = Fi
  */
 export interface OptimisticState<TOptimistic> {
   /** The current optimistic data (updated instantly on submit). */
-  data: TOptimistic
+  data: TOptimistic;
   /** Whether an optimistic update is pending (action in flight). */
-  isPending: boolean
+  isPending: boolean;
   /** Manually revert to the last confirmed state. */
-  rollback: () => void
+  rollback: () => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -179,41 +172,41 @@ export interface UseActionFormOptions<
    * If `persistKey` is provided and stored data exists, persisted values
    * take precedence.
    */
-  defaultValues?: DefaultValues<TFieldValues>
+  defaultValues?: DefaultValues<TFieldValues>;
 
   /**
    * Validation mode passed to React Hook Form.
    * @default 'onSubmit'
    */
-  mode?: Mode
+  mode?: Mode;
 
   /**
    * When provided, enables transparent sessionStorage persistence.
    * The form state is saved under this key and restored on mount.
    */
-  persistKey?: string
+  persistKey?: string;
 
   /**
    * Custom function to extract field errors from the action result.
    * By default supports the Zod `.flatten().fieldErrors` format.
    */
-  errorMapper?: ErrorMapper<TResult>
+  errorMapper?: ErrorMapper<TResult>;
 
   /**
    * Callback fired after a successful submission (no field errors returned).
    */
-  onSuccess?: (result: TResult) => void
+  onSuccess?: (result: TResult) => void;
 
   /**
    * Callback fired when the action throws or returns field errors.
    */
-  onError?: (result: TResult | Error) => void
+  onError?: (result: TResult | Error) => void;
 
   /**
    * Debounce interval (ms) for sessionStorage persistence.
    * @default 300
    */
-  persistDebounce?: number
+  persistDebounce?: number;
 
   // ---- v2: Client-side Zod validation -------------------------------------
 
@@ -222,36 +215,49 @@ export interface UseActionFormOptions<
    * If provided, fields are validated in real-time (based on `validationMode`).
    * If the action was created with `withZod`, the schema is auto-detected.
    */
-  schema?: ZodSchema
+  schema?: ZodSchema;
 
   /**
    * Controls when client-side Zod schema validation runs.
    * Only takes effect when `schema` is provided (or inferred from `withZod`).
    * @default 'onSubmit'
    */
-  validationMode?: ClientValidationMode
+  validationMode?: ClientValidationMode;
+
+  /**
+   * Alias for `validationMode`.
+   * @deprecated Use `validationMode` instead.
+   */
+  clientValidation?: ClientValidationMode;
 
   // ---- v2: Optimistic UI --------------------------------------------------
 
   /**
-   * Unique key identifying the optimistic state.
-   * When provided (along with `optimisticData`), enables React 19's
-   * `useOptimistic` integration.
+   * Optional key used to enable optimistic UI mode and identify optimistic data.
+   */
+  optimisticKey?: string;
+
+  /**
+   * Reducer that computes optimistic data from current data + submitted values.
+   */
+  optimisticData?: OptimisticReducer<TOptimistic, TFieldValues>;
+
+  /**
+   * Initial (confirmed) data used by optimistic mode.
    */
-  optimisticKey?: string
+  optimisticInitial?: TOptimistic;
 
   /**
-   * Reducer that computes the optimistic state from the current data and
-   * the form values being submitted.
-   * Required when `optimisticKey` is set.
+   * Alias for `optimisticData`.
+   * @deprecated Use `optimisticData` instead.
    */
-  optimisticData?: OptimisticReducer<TOptimistic, TFieldValues>
+  optimisticReducer?: OptimisticReducer<TOptimistic, TFieldValues>;
 
   /**
-   * Initial data for the optimistic state.
-   * This is the "confirmed" state before any optimistic updates.
+   * Alias for `optimisticInitial`.
+   * @deprecated Use `optimisticInitial` instead.
    */
-  optimisticInitial?: TOptimistic
+  optimisticDefault?: TOptimistic;
 }
 
 // ---------------------------------------------------------------------------
@@ -260,18 +266,28 @@ export interface UseActionFormOptions<
 
 export interface ActionFormState<TResult> {
   /** Whether the form is currently being submitted to the server action. */
-  isSubmitting: boolean
+  isSubmitting: boolean;
   /** Whether the last submission was successful (no field errors). */
-  isSubmitSuccessful: boolean
+  isSubmitSuccessful: boolean;
   /** Raw error record returned by the server action (via errorMapper). */
-  submitErrors: FieldErrorRecord | null
-  /** The full result from the last action invocation, if any. */
-  actionResult: TResult | null
+  submitErrors: FieldErrorRecord | null;
+  /** Full result from the last action invocation, if any. */
+  actionResult: TResult | null;
+  /**
+   * Alias for `submitErrors`.
+   * @deprecated Use `submitErrors` instead.
+   */
+  serverErrors: FieldErrorRecord | null;
+  /**
+   * Alias for `actionResult`.
+   * @deprecated Use `actionResult` instead.
+   */
+  lastResult: TResult | null;
   /**
    * `true` while a transition is pending (React 19 `useTransition`).
    * Falls back to `isSubmitting` on React 18.
    */
-  isPending: boolean
+  isPending: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -282,7 +298,7 @@ export interface UseActionFormReturn<
   TFieldValues extends FieldValues = FieldValues,
   TResult = ActionResult,
   TOptimistic = undefined,
-> extends Omit<UseFormReturn<TFieldValues>, 'handleSubmit'> {
+> extends Omit<UseFormReturn<TFieldValues>, "handleSubmit"> {
   /**
    * Enhanced handleSubmit that submits to the Server Action.
    * Call with no arguments: `onSubmit={handleSubmit()}`.
@@ -290,38 +306,50 @@ export interface UseActionFormReturn<
    */
   handleSubmit: (
     onValid?: (data: TFieldValues) => void | Promise<void>,
-  ) => (e?: React.BaseSyntheticEvent) => Promise<void>
+  ) => (e?: React.BaseSyntheticEvent) => Promise<void>;
 
   /**
    * Extended form state including server action status.
    */
-  formState: UseFormReturn<TFieldValues>['formState'] & ActionFormState<TResult>
+  formState: UseFormReturn<TFieldValues>["formState"] & ActionFormState<TResult>;
 
   /**
    * Manually set a server-side error on a specific field.
    */
-  setSubmitError: (field: keyof TFieldValues & string, message: string) => void
+  setSubmitError: (field: keyof TFieldValues & string, message: string) => void;
+
+  /**
+   * Alias for `setSubmitError`.
+   * @deprecated Use `setSubmitError` instead.
+   */
+  setServerError: (field: keyof TFieldValues & string, message: string) => void;
 
   /**
    * Manually persist the current form state to sessionStorage.
    * Only works when `persistKey` is set.
    */
-  persist: () => void
+  persist: () => void;
 
   /**
    * Clear persisted data from sessionStorage.
    * Only works when `persistKey` is set.
    */
-  clearPersistedData: () => void
+  clearPersistedData: () => void;
+
+  /**
+   * Alias for `clearPersistedData`.
+   * @deprecated Use `clearPersistedData` instead.
+   */
+  clearPersisted: () => void;
 
   /**
    * The underlying form action compatible with Next.js `<form action={…}>`.
    */
-  formAction: (formData: FormData) => Promise<void>
+  formAction: (formData: FormData) => Promise<void>;
 
   /**
    * Optimistic state (v2). Only populated when `optimisticKey` is provided.
    * Contains `data`, `isPending`, and `rollback()`.
    */
-  optimistic: TOptimistic extends undefined ? undefined : OptimisticState<TOptimistic>
+  optimistic: TOptimistic extends undefined ? undefined : OptimisticState<TOptimistic>;
 }
diff --git a/packages/core/src/use-action-form-core.ts b/packages/core/src/use-action-form-core.ts
index 573f2c4..53666f5 100644
--- a/packages/core/src/use-action-form-core.ts
+++ b/packages/core/src/use-action-form-core.ts
@@ -1,8 +1,8 @@
-'use client'
+"use client";
 
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { type DefaultValues, type FieldPath, type FieldValues, useForm } from 'react-hook-form'
-import type { ZodError, ZodSchema } from 'zod'
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { type DefaultValues, type FieldPath, type FieldValues, useForm } from "react-hook-form";
+import type { ZodError, ZodSchema } from "zod";
 
 import type {
   ActionFormState,
@@ -14,37 +14,30 @@ import type {
   SubmitFunction,
   UseActionFormCoreOptions,
   UseActionFormCoreReturn,
-} from './core-types'
-import { defaultErrorMapper } from './core-types'
-import { clearPersistedValues, debounce, loadPersistedValues, savePersistedValues } from './persist'
-import {
-  hasUseOptimistic,
-  useOptimistic as useOptimisticReact19,
-  useTransition,
-} from './react-shim'
+} from "./core-types";
+import { defaultErrorMapper } from "./core-types";
+import { clearPersistedValues, debounce, loadPersistedValues, savePersistedValues } from "./persist";
+import { hasUseOptimistic, useOptimistic as useOptimisticReact19, useTransition } from "./react-shim";
 
 // ---------------------------------------------------------------------------
 // Internal: client-side Zod validation helper
 // ---------------------------------------------------------------------------
 
-function validateWithSchema(
-  schema: ZodSchema,
-  values: Record<string, unknown>,
-): FieldErrorRecord | null {
-  const result = schema.safeParse(values)
-  if (result.success) return null
+function validateWithSchema(schema: ZodSchema, values: Record<string, unknown>): FieldErrorRecord | null {
+  const result = schema.safeParse(values);
+  if (result.success) return null;
 
-  const zodError = result.error as ZodError
-  const flat = zodError.flatten()
-  const errors: FieldErrorRecord = {}
+  const zodError = result.error as ZodError;
+  const flat = zodError.flatten();
+  const errors: FieldErrorRecord = {};
 
   for (const [field, messages] of Object.entries(flat.fieldErrors)) {
     if (messages && messages.length > 0) {
-      errors[field] = messages as string[]
+      errors[field] = messages as string[];
     }
   }
 
-  return Object.keys(errors).length > 0 ? errors : null
+  return Object.keys(errors).length > 0 ? errors : null;
 }
 
 // ---------------------------------------------------------------------------
@@ -52,8 +45,8 @@ function validateWithSchema(
 // ---------------------------------------------------------------------------
 
 function useOptimisticFallback<T>(initial: T): [T, (value: T) => void] {
-  const [state, setState] = useState<T>(initial)
-  return [state, setState]
+  const [state, setState] = useState<T>(initial);
+  return [state, setState];
 }
 
 // ---------------------------------------------------------------------------
@@ -86,50 +79,57 @@ export function useActionFormCore<
 ): UseActionFormCoreReturn<TFieldValues, TResult, TOptimistic> {
   const {
     defaultValues: optionDefaults,
-    mode = 'onSubmit',
+    mode = "onSubmit",
     persistKey,
     errorMapper = defaultErrorMapper as ErrorMapper<TResult>,
     onSuccess,
     onError,
     persistDebounce = 300,
     schema: optionsSchema,
-    validationMode = 'onSubmit',
+    validationMode,
+    clientValidation,
     optimisticKey,
     optimisticData,
     optimisticInitial,
+    optimisticReducer,
+    optimisticDefault,
     plugins = [],
-  } = options
+  } = options;
+
+  const resolvedValidationMode = validationMode ?? clientValidation ?? "onSubmit";
+  const resolvedOptimisticData = optimisticData ?? optimisticReducer;
+  const resolvedOptimisticInitial = (optimisticInitial ?? optimisticDefault) as TOptimistic;
 
   // ----- Resolve Zod schema -----------------------------------------------
 
-  const resolvedSchema = useMemo(() => optionsSchema ?? undefined, [optionsSchema])
+  const resolvedSchema = useMemo(() => optionsSchema ?? undefined, [optionsSchema]);
 
   // ----- Resolve initial values (persisted > options) ----------------------
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: intentionally run once on mount
   const resolvedDefaults = useMemo<DefaultValues<TFieldValues> | undefined>(() => {
     if (persistKey) {
-      const persisted = loadPersistedValues<TFieldValues>(persistKey)
+      const persisted = loadPersistedValues<TFieldValues>(persistKey);
       if (persisted) {
         return {
           ...(optionDefaults as Record<string, unknown> | undefined),
           ...persisted,
-        } as DefaultValues<TFieldValues>
+        } as DefaultValues<TFieldValues>;
       }
     }
-    return optionDefaults
-  }, [])
+    return optionDefaults;
+  }, []);
 
   // ----- React Hook Form ---------------------------------------------------
 
   const form = useForm<TFieldValues>({
     defaultValues: resolvedDefaults,
     mode,
-  })
+  });
 
   // ----- useTransition (React 18 & 19) ------------------------------------
 
-  const [isTransitioning, startTransition] = useTransition()
+  const [isTransitioning, startTransition] = useTransition();
 
   // ----- Action state ------------------------------------------------------
 
@@ -138,112 +138,117 @@ export function useActionFormCore<
     isSubmitSuccessful: false,
     submitErrors: null,
     actionResult: null,
+    serverErrors: null,
+    lastResult: null,
     isPending: false,
-  })
+  });
 
   // ----- Submission history (for DevTools) ----------------------------------
 
-  const submissionHistoryRef = useRef<SubmissionRecord<TResult>[]>([])
+  const submissionHistoryRef = useRef<SubmissionRecord<TResult>[]>([]);
 
   // ----- Optimistic UI (React 19 only) -------------------------------------
 
-  const hasOptimistic = optimisticKey != null && optimisticData != null
+  const hasOptimistic = resolvedOptimisticData != null && (optimisticKey != null || optimisticReducer != null);
 
-  const useOptimisticHook =
-    hasUseOptimistic && useOptimisticReact19 ? useOptimisticReact19 : useOptimisticFallback
+  const useOptimisticHook = hasUseOptimistic && useOptimisticReact19 ? useOptimisticReact19 : useOptimisticFallback;
 
-  const [optimisticState, setOptimistic] = useOptimisticHook(optimisticInitial as TOptimistic)
+  const [optimisticState, setOptimistic] = useOptimisticHook(resolvedOptimisticInitial);
 
-  const confirmedOptimisticRef = useRef<TOptimistic>(optimisticInitial as TOptimistic)
+  const confirmedOptimisticRef = useRef<TOptimistic>(resolvedOptimisticInitial);
 
   const rollbackOptimistic = useCallback(() => {
-    setOptimistic(confirmedOptimisticRef.current)
-  }, [setOptimistic])
+    setOptimistic(confirmedOptimisticRef.current);
+  }, [setOptimistic]);
 
   // ----- Persistence -------------------------------------------------------
 
   const debouncedSave = useMemo(() => {
-    if (!persistKey) return null
+    if (!persistKey) return null;
     return debounce((values: TFieldValues) => {
-      savePersistedValues(persistKey, values)
-    }, persistDebounce)
-  }, [persistKey, persistDebounce])
+      savePersistedValues(persistKey, values);
+    }, persistDebounce);
+  }, [persistKey, persistDebounce]);
 
   useEffect(() => {
-    if (!persistKey || !debouncedSave) return
+    if (!persistKey || !debouncedSave) return;
 
     const subscription = form.watch((values) => {
-      debouncedSave(values as TFieldValues)
-    })
+      debouncedSave(values as TFieldValues);
+    });
 
-    return () => subscription.unsubscribe()
-  }, [persistKey, debouncedSave, form])
+    return () => subscription.unsubscribe();
+  }, [persistKey, debouncedSave, form]);
 
   // ----- Client-side Zod validation (onChange / onBlur) ---------------------
 
   useEffect(() => {
-    if (!resolvedSchema || validationMode === 'onSubmit') return
+    if (!resolvedSchema || resolvedValidationMode === "onSubmit") return;
 
     const subscription = form.watch((values, { name, type }) => {
-      if (!name) return
+      if (!name) return;
 
-      if (validationMode === 'onChange' || type === 'blur') {
-        const fieldResult = resolvedSchema.safeParse(values)
+      if (resolvedValidationMode === "onChange" || type === "blur") {
+        const fieldResult = resolvedSchema.safeParse(values);
         if (fieldResult.success) {
-          form.clearErrors(name as FieldPath<TFieldValues>)
+          form.clearErrors(name as FieldPath<TFieldValues>);
         } else {
-          const zodError = fieldResult.error as ZodError
-          const flat = zodError.flatten()
-          const fieldErrors = flat.fieldErrors[name]
+          const zodError = fieldResult.error as ZodError;
+          const flat = zodError.flatten();
+          const fieldErrors = flat.fieldErrors[name];
 
           if (fieldErrors && fieldErrors.length > 0) {
             form.setError(name as FieldPath<TFieldValues>, {
-              type: 'validation',
+              type: "validation",
               message: fieldErrors[0],
-            })
+            });
           } else {
-            form.clearErrors(name as FieldPath<TFieldValues>)
+            form.clearErrors(name as FieldPath<TFieldValues>);
           }
         }
       }
-    })
+    });
 
-    return () => subscription.unsubscribe()
-  }, [resolvedSchema, validationMode, form])
+    return () => subscription.unsubscribe();
+  }, [resolvedSchema, resolvedValidationMode, form]);
 
   // ----- Plugin lifecycle: onMount -----------------------------------------
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: plugins identity changes every render; run once on mount
   useEffect(() => {
-    const cleanups = plugins.map((p) => p.onMount?.()).filter(Boolean) as (() => void)[]
+    const cleanups = plugins.map((p) => p.onMount?.()).filter(Boolean) as (() => void)[];
 
     return () => {
       for (const cleanup of cleanups) {
-        cleanup()
+        cleanup();
       }
-    }
-  }, []) // eslint-disable-line react-hooks/exhaustive-deps -- run once on mount
+    };
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps -- run once on mount
 
   // ----- Manual persist / clear --------------------------------------------
 
   const persist = useCallback(() => {
-    if (!persistKey) return
-    savePersistedValues(persistKey, form.getValues())
-  }, [persistKey, form])
+    if (!persistKey) return;
+    savePersistedValues(persistKey, form.getValues());
+  }, [persistKey, form]);
 
-  const clearPersisted = useCallback(() => {
-    if (!persistKey) return
-    clearPersistedValues(persistKey)
-  }, [persistKey])
+  const clearPersistedData = useCallback(() => {
+    if (!persistKey) return;
+    clearPersistedValues(persistKey);
+  }, [persistKey]);
+
+  const clearPersisted = clearPersistedData;
 
   // ----- Set a server error on a field -------------------------------------
 
   const setSubmitError = useCallback(
     (field: keyof TFieldValues & string, message: string) => {
-      form.setError(field as never, { type: 'server', message })
+      form.setError(field as never, { type: "server", message });
     },
     [form],
-  )
+  );
+
+  const setServerError = setSubmitError;
 
   // ----- Map server errors to RHF ------------------------------------------
 
@@ -252,40 +257,42 @@ export function useActionFormCore<
       for (const [field, messages] of Object.entries(errors)) {
         if (messages && messages.length > 0) {
           form.setError(field as never, {
-            type: 'server',
+            type: "server",
             message: messages[0],
-          })
+          });
         }
       }
     },
     [form],
-  )
+  );
 
   // ----- Core submit logic -------------------------------------------------
 
   const executeSubmit = useCallback(
     async (data: TFieldValues) => {
       // Client-side schema validation (for onSubmit mode)
-      if (resolvedSchema && validationMode === 'onSubmit') {
-        const clientErrors = validateWithSchema(resolvedSchema, data as Record<string, unknown>)
+      if (resolvedSchema && resolvedValidationMode === "onSubmit") {
+        const clientErrors = validateWithSchema(resolvedSchema, data as Record<string, unknown>);
         if (clientErrors) {
-          applyServerErrors(clientErrors)
+          applyServerErrors(clientErrors);
           setActionState({
             isSubmitting: false,
             isSubmitSuccessful: false,
             submitErrors: clientErrors,
             actionResult: null,
+            serverErrors: clientErrors,
+            lastResult: null,
             isPending: false,
-          })
-          return
+          });
+          return;
         }
       }
 
       // Plugin: onBeforeSubmit
       for (const plugin of plugins) {
         if (plugin.onBeforeSubmit) {
-          const shouldContinue = await plugin.onBeforeSubmit(data)
-          if (shouldContinue === false) return
+          const shouldContinue = await plugin.onBeforeSubmit(data);
+          if (shouldContinue === false) return;
         }
       }
 
@@ -294,20 +301,21 @@ export function useActionFormCore<
         isSubmitting: true,
         isPending: true,
         submitErrors: null,
-      }))
+        serverErrors: null,
+      }));
 
       // Apply optimistic update before the action runs
-      if (hasOptimistic && optimisticData) {
-        const optimisticResult = optimisticData(confirmedOptimisticRef.current, data)
-        setOptimistic(optimisticResult)
+      if (hasOptimistic && resolvedOptimisticData) {
+        const optimisticResult = resolvedOptimisticData(confirmedOptimisticRef.current, data);
+        setOptimistic(optimisticResult);
       }
 
-      const startTime = Date.now()
+      const startTime = Date.now();
 
       try {
-        const result = await submit(data)
+        const result = await submit(data);
 
-        const fieldErrors = errorMapper(result)
+        const fieldErrors = errorMapper(result);
 
         // Record submission for DevTools
         const record: SubmissionRecord<TResult> = {
@@ -318,14 +326,14 @@ export function useActionFormCore<
           error: null,
           duration: Date.now() - startTime,
           success: !fieldErrors || Object.keys(fieldErrors).length === 0,
-        }
-        submissionHistoryRef.current = [...submissionHistoryRef.current.slice(-49), record]
+        };
+        submissionHistoryRef.current = [...submissionHistoryRef.current.slice(-49), record];
 
         if (fieldErrors && Object.keys(fieldErrors).length > 0) {
-          applyServerErrors(fieldErrors)
+          applyServerErrors(fieldErrors);
 
           if (hasOptimistic) {
-            rollbackOptimistic()
+            rollbackOptimistic();
           }
 
           setActionState({
@@ -333,38 +341,42 @@ export function useActionFormCore<
             isSubmitSuccessful: false,
             submitErrors: fieldErrors,
             actionResult: result,
+            serverErrors: fieldErrors,
+            lastResult: result,
             isPending: false,
-          })
+          });
 
           // Plugin: onError
           for (const plugin of plugins) {
-            plugin.onError?.(result, data)
+            plugin.onError?.(result, data);
           }
 
-          onError?.(result)
+          onError?.(result);
         } else {
           // Success – update confirmed optimistic state
-          if (hasOptimistic && optimisticData) {
-            confirmedOptimisticRef.current = optimisticData(confirmedOptimisticRef.current, data)
+          if (hasOptimistic && resolvedOptimisticData) {
+            confirmedOptimisticRef.current = resolvedOptimisticData(confirmedOptimisticRef.current, data);
           }
 
           // Clear persisted data
-          if (persistKey) clearPersistedValues(persistKey)
+          if (persistKey) clearPersistedValues(persistKey);
 
           setActionState({
             isSubmitting: false,
             isSubmitSuccessful: true,
             submitErrors: null,
             actionResult: result,
+            serverErrors: null,
+            lastResult: result,
             isPending: false,
-          })
+          });
 
           // Plugin: onSuccess
           for (const plugin of plugins) {
-            plugin.onSuccess?.(result, data)
+            plugin.onSuccess?.(result, data);
           }
 
-          onSuccess?.(result)
+          onSuccess?.(result);
         }
       } catch (error) {
         // Record failed submission for DevTools
@@ -376,11 +388,11 @@ export function useActionFormCore<
           error: error instanceof Error ? error : new Error(String(error)),
           duration: Date.now() - startTime,
           success: false,
-        }
-        submissionHistoryRef.current = [...submissionHistoryRef.current.slice(-49), record]
+        };
+        submissionHistoryRef.current = [...submissionHistoryRef.current.slice(-49), record];
 
         if (hasOptimistic) {
-          rollbackOptimistic()
+          rollbackOptimistic();
         }
 
         setActionState((prev) => ({
@@ -388,16 +400,16 @@ export function useActionFormCore<
           isSubmitting: false,
           isSubmitSuccessful: false,
           isPending: false,
-        }))
+        }));
 
-        const wrappedError = error instanceof Error ? error : new Error(String(error))
+        const wrappedError = error instanceof Error ? error : new Error(String(error));
 
         // Plugin: onError
         for (const plugin of plugins) {
-          plugin.onError?.(wrappedError as TResult & Error, data)
+          plugin.onError?.(wrappedError as TResult & Error, data);
         }
 
-        onError?.(wrappedError)
+        onError?.(wrappedError);
       }
     },
     [
@@ -408,30 +420,30 @@ export function useActionFormCore<
       onError,
       persistKey,
       resolvedSchema,
-      validationMode,
+      resolvedValidationMode,
       hasOptimistic,
-      optimisticData,
+      resolvedOptimisticData,
       setOptimistic,
       rollbackOptimistic,
       plugins,
     ],
-  )
+  );
 
   // ----- handleSubmit wrapper ----------------------------------------------
 
   const handleSubmit = useCallback(
     (onValid?: (data: TFieldValues) => void | Promise<void>) => {
       return form.handleSubmit(async (data) => {
-        if (onValid) await onValid(data)
+        if (onValid) await onValid(data);
 
         // @ts-ignore – React 19 supports async transitions; React 18 ignores the promise
         startTransition(async () => {
-          await executeSubmit(data)
-        })
-      })
+          await executeSubmit(data);
+        });
+      });
     },
     [form, executeSubmit, startTransition],
-  )
+  );
 
   // ----- Compose return value ----------------------------------------------
 
@@ -452,30 +464,30 @@ export function useActionFormCore<
       isPending: isTransitioning || actionState.isPending,
     }),
     [form.formState, actionState, isTransitioning],
-  )
+  );
 
   // ----- Compose optimistic return -----------------------------------------
 
   const optimisticReturn = useMemo(() => {
-    if (!hasOptimistic) return undefined
+    if (!hasOptimistic) return undefined;
     return {
       data: optimisticState,
       isPending: isTransitioning || actionState.isPending,
       rollback: rollbackOptimistic,
-    } as OptimisticState<TOptimistic>
-  }, [hasOptimistic, optimisticState, isTransitioning, actionState.isPending, rollbackOptimistic])
+    } as OptimisticState<TOptimistic>;
+  }, [hasOptimistic, optimisticState, isTransitioning, actionState.isPending, rollbackOptimistic]);
 
   // ----- Compose control with DevTools metadata ----------------------------
 
   const enhancedControl = useMemo(() => {
     const ctrl = form.control as typeof form.control & {
-      _submissionHistory: SubmissionRecord<TResult>[]
-      _actionFormState: ActionFormState<TResult>
-    }
-    ctrl._submissionHistory = submissionHistoryRef.current
-    ctrl._actionFormState = actionState
-    return ctrl
-  }, [form.control, actionState])
+      _submissionHistory: SubmissionRecord<TResult>[];
+      _actionFormState: ActionFormState<TResult>;
+    };
+    ctrl._submissionHistory = submissionHistoryRef.current;
+    ctrl._actionFormState = actionState;
+    return ctrl;
+  }, [form.control, actionState]);
 
   return {
     ...form,
@@ -483,8 +495,10 @@ export function useActionFormCore<
     handleSubmit,
     formState: composedFormState,
     setSubmitError,
+    setServerError,
     persist,
-    clearPersistedData: clearPersisted,
+    clearPersistedData,
+    clearPersisted,
     optimistic: optimisticReturn,
-  } as UseActionFormCoreReturn<TFieldValues, TResult, TOptimistic>
+  } as UseActionFormCoreReturn<TFieldValues, TResult, TOptimistic>;
 }
diff --git a/packages/core/src/use-action-form.ts b/packages/core/src/use-action-form.ts
index 6e9c619..268e697 100644
--- a/packages/core/src/use-action-form.ts
+++ b/packages/core/src/use-action-form.ts
@@ -1,15 +1,11 @@
-'use client'
-
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { type DefaultValues, type FieldPath, type FieldValues, useForm } from 'react-hook-form'
-import type { ZodError, ZodSchema } from 'zod'
-
-import { clearPersistedValues, debounce, loadPersistedValues, savePersistedValues } from './persist'
-import {
-  hasUseOptimistic,
-  useOptimistic as useOptimisticReact19,
-  useTransition,
-} from './react-shim'
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { type DefaultValues, type FieldPath, type FieldValues, useForm } from "react-hook-form";
+import type { ZodError, ZodSchema } from "zod";
+
+import { clearPersistedValues, debounce, loadPersistedValues, savePersistedValues } from "./persist";
+import { hasUseOptimistic, useOptimistic as useOptimisticReact19, useTransition } from "./react-shim";
 import type {
   ActionFormState,
   ActionResult,
@@ -19,44 +15,38 @@ import type {
   ServerAction,
   UseActionFormOptions,
   UseActionFormReturn,
-} from './types'
-import { defaultErrorMapper, hasAttachedSchema, isFormDataAction } from './types'
+} from "./types";
+import { defaultErrorMapper, hasAttachedSchema, isFormDataAction } from "./types";
 
 // ---------------------------------------------------------------------------
 // Internal: resolve Zod schema from options or attached action
 // ---------------------------------------------------------------------------
 
-function resolveSchema<TResult>(
-  action: ServerAction<TResult>,
-  optionsSchema?: ZodSchema,
-): ZodSchema | undefined {
-  if (optionsSchema) return optionsSchema
-  if (hasAttachedSchema(action)) return action.__schema
-  return undefined
+function resolveSchema<TResult>(action: ServerAction<TResult>, optionsSchema?: ZodSchema): ZodSchema | undefined {
+  if (optionsSchema) return optionsSchema;
+  if (hasAttachedSchema(action)) return action.__schema;
+  return undefined;
 }
 
 // ---------------------------------------------------------------------------
 // Internal: client-side Zod validation helper
 // ---------------------------------------------------------------------------
 
-function validateWithSchema(
-  schema: ZodSchema,
-  values: Record<string, unknown>,
-): FieldErrorRecord | null {
-  const result = schema.safeParse(values)
-  if (result.success) return null
+function validateWithSchema(schema: ZodSchema, values: Record<string, unknown>): FieldErrorRecord | null {
+  const result = schema.safeParse(values);
+  if (result.success) return null;
 
-  const zodError = result.error as ZodError
-  const flat = zodError.flatten()
-  const errors: FieldErrorRecord = {}
+  const zodError = result.error as ZodError;
+  const flat = zodError.flatten();
+  const errors: FieldErrorRecord = {};
 
   for (const [field, messages] of Object.entries(flat.fieldErrors)) {
     if (messages && messages.length > 0) {
-      errors[field] = messages as string[]
+      errors[field] = messages as string[];
     }
   }
 
-  return Object.keys(errors).length > 0 ? errors : null
+  return Object.keys(errors).length > 0 ? errors : null;
 }
 
 // ---------------------------------------------------------------------------
@@ -64,8 +54,8 @@ function validateWithSchema(
 // ---------------------------------------------------------------------------
 
 function useOptimisticFallback<T>(initial: T): [T, (value: T) => void] {
-  const [state, setState] = useState<T>(initial)
-  return [state, setState]
+  const [state, setState] = useState<T>(initial);
+  return [state, setState];
 }
 
 // ---------------------------------------------------------------------------
@@ -115,52 +105,56 @@ export function useActionForm<
 ): UseActionFormReturn<TFieldValues, TResult, TOptimistic> {
   const {
     defaultValues: optionDefaults,
-    mode = 'onSubmit',
+    mode = "onSubmit",
     persistKey,
     errorMapper = defaultErrorMapper as ErrorMapper<TResult>,
     onSuccess,
     onError,
     persistDebounce = 300,
     schema: optionsSchema,
-    validationMode = 'onSubmit',
+    validationMode,
+    clientValidation,
     optimisticKey,
     optimisticData,
     optimisticInitial,
-  } = options
+    optimisticReducer,
+    optimisticDefault,
+  } = options;
+
+  const resolvedValidationMode = validationMode ?? clientValidation ?? "onSubmit";
+  const resolvedOptimisticData = optimisticData ?? optimisticReducer;
+  const resolvedOptimisticInitial = (optimisticInitial ?? optimisticDefault) as TOptimistic;
 
   // ----- Resolve Zod schema (explicit or auto-detected from withZod) -------
 
-  const resolvedSchema = useMemo(
-    () => resolveSchema(action, optionsSchema),
-    [action, optionsSchema],
-  )
+  const resolvedSchema = useMemo(() => resolveSchema(action, optionsSchema), [action, optionsSchema]);
 
   // ----- Resolve initial values (persisted > options) ----------------------
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: intentionally run once on mount
   const resolvedDefaults = useMemo<DefaultValues<TFieldValues> | undefined>(() => {
     if (persistKey) {
-      const persisted = loadPersistedValues<TFieldValues>(persistKey)
+      const persisted = loadPersistedValues<TFieldValues>(persistKey);
       if (persisted) {
         return {
           ...(optionDefaults as Record<string, unknown> | undefined),
           ...persisted,
-        } as DefaultValues<TFieldValues>
+        } as DefaultValues<TFieldValues>;
       }
     }
-    return optionDefaults
-  }, [])
+    return optionDefaults;
+  }, []);
 
   // ----- React Hook Form ---------------------------------------------------
 
   const form = useForm<TFieldValues>({
     defaultValues: resolvedDefaults,
     mode,
-  })
+  });
 
   // ----- useTransition (React 18 & 19) ------------------------------------
 
-  const [isTransitioning, startTransition] = useTransition()
+  const [isTransitioning, startTransition] = useTransition();
 
   // ----- Action state ------------------------------------------------------
 
@@ -169,107 +163,112 @@ export function useActionForm<
     isSubmitSuccessful: false,
     submitErrors: null,
     actionResult: null,
+    serverErrors: null,
+    lastResult: null,
     isPending: false,
-  })
+  });
 
   // Keep a ref to the latest action result so callbacks read fresh state
-  const resultRef = useRef<TResult | null>(null)
+  const resultRef = useRef<TResult | null>(null);
   // Track the previous server state for the action
-  const prevStateRef = useRef<Awaited<TResult> | null>(null)
+  const prevStateRef = useRef<Awaited<TResult> | null>(null);
 
   // ----- Optimistic UI (React 19 only) -------------------------------------
 
-  const hasOptimistic = optimisticKey != null && optimisticData != null
+  const hasOptimistic = resolvedOptimisticData != null && (optimisticKey != null || optimisticReducer != null);
 
   // We use the React 19 useOptimistic when available, otherwise a simple state fallback.
-  const useOptimisticHook =
-    hasUseOptimistic && useOptimisticReact19 ? useOptimisticReact19 : useOptimisticFallback
+  const useOptimisticHook = hasUseOptimistic && useOptimisticReact19 ? useOptimisticReact19 : useOptimisticFallback;
 
-  const [optimisticState, setOptimistic] = useOptimisticHook(optimisticInitial as TOptimistic)
+  const [optimisticState, setOptimistic] = useOptimisticHook(resolvedOptimisticInitial);
 
   // Track confirmed state for rollback
-  const confirmedOptimisticRef = useRef<TOptimistic>(optimisticInitial as TOptimistic)
+  const confirmedOptimisticRef = useRef<TOptimistic>(resolvedOptimisticInitial);
 
   const rollbackOptimistic = useCallback(() => {
-    setOptimistic(confirmedOptimisticRef.current)
-  }, [setOptimistic])
+    setOptimistic(confirmedOptimisticRef.current);
+  }, [setOptimistic]);
 
   // ----- Persistence -------------------------------------------------------
 
   const debouncedSave = useMemo(() => {
-    if (!persistKey) return null
+    if (!persistKey) return null;
     return debounce((values: TFieldValues) => {
-      savePersistedValues(persistKey, values)
-    }, persistDebounce)
-  }, [persistKey, persistDebounce])
+      savePersistedValues(persistKey, values);
+    }, persistDebounce);
+  }, [persistKey, persistDebounce]);
 
   // Watch all fields and persist on change
   useEffect(() => {
-    if (!persistKey || !debouncedSave) return
+    if (!persistKey || !debouncedSave) return;
 
     const subscription = form.watch((values) => {
-      debouncedSave(values as TFieldValues)
-    })
+      debouncedSave(values as TFieldValues);
+    });
 
-    return () => subscription.unsubscribe()
-  }, [persistKey, debouncedSave, form])
+    return () => subscription.unsubscribe();
+  }, [persistKey, debouncedSave, form]);
 
   // ----- Client-side Zod validation (onChange / onBlur) ---------------------
 
   useEffect(() => {
-    if (!resolvedSchema || validationMode === 'onSubmit') return
+    if (!resolvedSchema || resolvedValidationMode === "onSubmit") return;
 
     const subscription = form.watch((values, { name, type }) => {
-      if (!name) return
+      if (!name) return;
 
       // For onBlur mode, only validate if the event type is blur
       // (RHF watch fires on all changes, so we validate on onChange mode always)
-      if (validationMode === 'onChange' || type === 'blur') {
+      if (resolvedValidationMode === "onChange" || type === "blur") {
         // Validate the single changed field
-        const fieldResult = resolvedSchema.safeParse(values)
+        const fieldResult = resolvedSchema.safeParse(values);
         if (fieldResult.success) {
           // Clear any existing errors for this field
-          form.clearErrors(name as FieldPath<TFieldValues>)
+          form.clearErrors(name as FieldPath<TFieldValues>);
         } else {
-          const zodError = fieldResult.error as ZodError
-          const flat = zodError.flatten()
-          const fieldErrors = flat.fieldErrors[name]
+          const zodError = fieldResult.error as ZodError;
+          const flat = zodError.flatten();
+          const fieldErrors = flat.fieldErrors[name];
 
           if (fieldErrors && fieldErrors.length > 0) {
             form.setError(name as FieldPath<TFieldValues>, {
-              type: 'validation',
+              type: "validation",
               message: fieldErrors[0],
-            })
+            });
           } else {
-            form.clearErrors(name as FieldPath<TFieldValues>)
+            form.clearErrors(name as FieldPath<TFieldValues>);
           }
         }
       }
-    })
+    });
 
-    return () => subscription.unsubscribe()
-  }, [resolvedSchema, validationMode, form])
+    return () => subscription.unsubscribe();
+  }, [resolvedSchema, resolvedValidationMode, form]);
 
   // ----- Manual persist / clear --------------------------------------------
 
   const persist = useCallback(() => {
-    if (!persistKey) return
-    savePersistedValues(persistKey, form.getValues())
-  }, [persistKey, form])
+    if (!persistKey) return;
+    savePersistedValues(persistKey, form.getValues());
+  }, [persistKey, form]);
+
+  const clearPersistedData = useCallback(() => {
+    if (!persistKey) return;
+    clearPersistedValues(persistKey);
+  }, [persistKey]);
 
-  const clearPersisted = useCallback(() => {
-    if (!persistKey) return
-    clearPersistedValues(persistKey)
-  }, [persistKey])
+  const clearPersisted = clearPersistedData;
 
   // ----- Set a server error on a field -------------------------------------
 
   const setSubmitError = useCallback(
     (field: keyof TFieldValues & string, message: string) => {
-      form.setError(field as never, { type: 'server', message })
+      form.setError(field as never, { type: "server", message });
     },
     [form],
-  )
+  );
+
+  const setServerError = setSubmitError;
 
   // ----- Map server errors to RHF ------------------------------------------
 
@@ -278,37 +277,39 @@ export function useActionForm<
       for (const [field, messages] of Object.entries(errors)) {
         if (messages && messages.length > 0) {
           form.setError(field as never, {
-            type: 'server',
+            type: "server",
             message: messages[0],
-          })
+          });
         }
       }
     },
     [form],
-  )
+  );
 
   // ----- Detect action arity ------------------------------------------------
 
   /** true when the action expects (prevState, formData) — arity >= 2 */
-  const actionIsFormData = useMemo(() => isFormDataAction(action), [action])
+  const actionIsFormData = useMemo(() => isFormDataAction(action), [action]);
 
   // ----- Core submit logic (shared between formAction & handleSubmit) ------
 
   const executeAction = useCallback(
     async (data: TFieldValues | FormData, isFormDataSubmission: boolean) => {
       // Client-side schema validation (for onSubmit mode)
-      if (resolvedSchema && validationMode === 'onSubmit' && !(data instanceof FormData)) {
-        const clientErrors = validateWithSchema(resolvedSchema, data as Record<string, unknown>)
+      if (resolvedSchema && resolvedValidationMode === "onSubmit" && !(data instanceof FormData)) {
+        const clientErrors = validateWithSchema(resolvedSchema, data as Record<string, unknown>);
         if (clientErrors) {
-          applyServerErrors(clientErrors)
+          applyServerErrors(clientErrors);
           setActionState({
             isSubmitting: false,
             isSubmitSuccessful: false,
             submitErrors: clientErrors,
             actionResult: null,
+            serverErrors: clientErrors,
+            lastResult: null,
             isPending: false,
-          })
-          return
+          });
+          return;
         }
       }
 
@@ -317,78 +318,78 @@ export function useActionForm<
         isSubmitting: true,
         isPending: true,
         submitErrors: null,
-      }))
+        serverErrors: null,
+      }));
 
       // Apply optimistic update before the action runs
-      if (hasOptimistic && optimisticData && !(data instanceof FormData)) {
-        const optimisticResult = optimisticData(
-          confirmedOptimisticRef.current,
-          data as TFieldValues,
-        )
-        setOptimistic(optimisticResult)
+      if (hasOptimistic && resolvedOptimisticData && !(data instanceof FormData)) {
+        const optimisticResult = resolvedOptimisticData(confirmedOptimisticRef.current, data as TFieldValues);
+        setOptimistic(optimisticResult);
       }
 
       try {
-        let result: TResult
+        let result: TResult;
 
         if (isFormDataSubmission && data instanceof FormData) {
           if (actionIsFormData) {
-            result = await (
-              action as (prev: Awaited<TResult> | null, fd: FormData) => Promise<TResult>
-            )(prevStateRef.current, data)
+            result = await (action as (prev: Awaited<TResult> | null, fd: FormData) => Promise<TResult>)(
+              prevStateRef.current,
+              data,
+            );
           } else {
             // Convert FormData to plain object for JSON actions
-            const obj: Record<string, unknown> = {}
+            const obj: Record<string, unknown> = {};
             for (const [key, value] of data.entries()) {
               if (key in obj) {
-                const existing = obj[key]
+                const existing = obj[key];
                 if (Array.isArray(existing)) {
-                  existing.push(value)
+                  existing.push(value);
                 } else {
-                  obj[key] = [existing, value]
+                  obj[key] = [existing, value];
                 }
               } else {
-                obj[key] = value
+                obj[key] = value;
               }
             }
-            result = await (action as (d: unknown) => Promise<TResult>)(obj)
+            result = await (action as (d: unknown) => Promise<TResult>)(obj);
           }
         } else if (actionIsFormData) {
           // Build FormData from validated values for (prevState, formData) actions
-          const formData = new FormData()
+          const formData = new FormData();
           for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
             if (value instanceof File) {
-              formData.append(key, value)
+              formData.append(key, value);
             } else if (value instanceof FileList) {
               for (let i = 0; i < value.length; i++) {
-                formData.append(key, value[i] as File)
+                formData.append(key, value[i] as File);
               }
             } else if (Array.isArray(value)) {
               for (const item of value) {
-                formData.append(key, String(item))
+                formData.append(key, String(item));
               }
             } else if (value !== null && value !== undefined) {
-              formData.append(key, String(value))
+              formData.append(key, String(value));
             }
           }
-          result = await (
-            action as (prev: Awaited<TResult> | null, fd: FormData) => Promise<TResult>
-          )(prevStateRef.current, formData)
+          result = await (action as (prev: Awaited<TResult> | null, fd: FormData) => Promise<TResult>)(
+            prevStateRef.current,
+            formData,
+          );
         } else {
-          result = await (action as (d: unknown) => Promise<TResult>)(data)
+          result = await (action as (d: unknown) => Promise<TResult>)(data);
         }
 
-        resultRef.current = result
-        prevStateRef.current = result as Awaited<TResult>
+        resultRef.current = result;
+        prevStateRef.current = result as Awaited<TResult>;
 
-        const fieldErrors = errorMapper(result)
+        const fieldErrors = errorMapper(result);
 
         if (fieldErrors && Object.keys(fieldErrors).length > 0) {
-          applyServerErrors(fieldErrors)
+          applyServerErrors(fieldErrors);
 
           // Rollback optimistic on error
           if (hasOptimistic) {
-            rollbackOptimistic()
+            rollbackOptimistic();
           }
 
           setActionState({
@@ -396,34 +397,35 @@ export function useActionForm<
             isSubmitSuccessful: false,
             submitErrors: fieldErrors,
             actionResult: result,
+            serverErrors: fieldErrors,
+            lastResult: result,
             isPending: false,
-          })
-          onError?.(result)
+          });
+          onError?.(result);
         } else {
           // Success – update confirmed optimistic state
-          if (hasOptimistic && optimisticData && !(data instanceof FormData)) {
-            confirmedOptimisticRef.current = optimisticData(
-              confirmedOptimisticRef.current,
-              data as TFieldValues,
-            )
+          if (hasOptimistic && resolvedOptimisticData && !(data instanceof FormData)) {
+            confirmedOptimisticRef.current = resolvedOptimisticData(confirmedOptimisticRef.current, data as TFieldValues);
           }
 
           // Clear persisted data
-          if (persistKey) clearPersistedValues(persistKey)
+          if (persistKey) clearPersistedValues(persistKey);
 
           setActionState({
             isSubmitting: false,
             isSubmitSuccessful: true,
             submitErrors: null,
             actionResult: result,
+            serverErrors: null,
+            lastResult: result,
             isPending: false,
-          })
-          onSuccess?.(result)
+          });
+          onSuccess?.(result);
         }
       } catch (error) {
         // Rollback optimistic on throw
         if (hasOptimistic) {
-          rollbackOptimistic()
+          rollbackOptimistic();
         }
 
         setActionState((prev) => ({
@@ -431,8 +433,8 @@ export function useActionForm<
           isSubmitting: false,
           isSubmitSuccessful: false,
           isPending: false,
-        }))
-        onError?.(error instanceof Error ? error : new Error(String(error)))
+        }));
+        onError?.(error instanceof Error ? error : new Error(String(error)));
       }
     },
     [
@@ -444,13 +446,13 @@ export function useActionForm<
       onError,
       persistKey,
       resolvedSchema,
-      validationMode,
+      resolvedValidationMode,
       hasOptimistic,
-      optimisticData,
+      resolvedOptimisticData,
       setOptimistic,
       rollbackOptimistic,
     ],
-  )
+  );
 
   // ----- Form action (for Next.js <form action={…}>) -----------------------
 
@@ -458,11 +460,11 @@ export function useActionForm<
     async (formData: FormData) => {
       // @ts-ignore – React 19 supports async transitions; React 18 ignores the promise
       startTransition(async () => {
-        await executeAction(formData, true)
-      })
+        await executeAction(formData, true);
+      });
     },
     [executeAction, startTransition],
-  )
+  );
 
   // ----- handleSubmit wrapper ----------------------------------------------
 
@@ -470,16 +472,16 @@ export function useActionForm<
     (onValid?: (data: TFieldValues) => void | Promise<void>) => {
       return form.handleSubmit(async (data) => {
         // Run optional client-side callback first
-        if (onValid) await onValid(data)
+        if (onValid) await onValid(data);
 
         // @ts-ignore – React 19 supports async transitions; React 18 ignores the promise
         startTransition(async () => {
-          await executeAction(data, false)
-        })
-      })
+          await executeAction(data, false);
+        });
+      });
     },
     [form, executeAction, startTransition],
-  )
+  );
 
   // ----- Compose return value ----------------------------------------------
 
@@ -502,27 +504,29 @@ export function useActionForm<
       isPending: isTransitioning || actionState.isPending,
     }),
     [form.formState, actionState, isTransitioning],
-  )
+  );
 
   // ----- Compose optimistic return -----------------------------------------
 
   const optimisticReturn = useMemo(() => {
-    if (!hasOptimistic) return undefined
+    if (!hasOptimistic) return undefined;
     return {
       data: optimisticState,
       isPending: isTransitioning || actionState.isPending,
       rollback: rollbackOptimistic,
-    } as OptimisticState<TOptimistic>
-  }, [hasOptimistic, optimisticState, isTransitioning, actionState.isPending, rollbackOptimistic])
+    } as OptimisticState<TOptimistic>;
+  }, [hasOptimistic, optimisticState, isTransitioning, actionState.isPending, rollbackOptimistic]);
 
   return {
     ...form,
     handleSubmit,
     formState: composedFormState,
     setSubmitError,
+    setServerError,
     persist,
-    clearPersistedData: clearPersisted,
+    clearPersistedData,
+    clearPersisted,
     formAction,
     optimistic: optimisticReturn,
-  } as UseActionFormReturn<TFieldValues, TResult, TOptimistic>
+  } as UseActionFormReturn<TFieldValues, TResult, TOptimistic>;
 }
diff --git a/packages/devtools/package.json b/packages/devtools/package.json
index 893a79c..e3fdef6 100644
--- a/packages/devtools/package.json
+++ b/packages/devtools/package.json
@@ -1,7 +1,7 @@
 {
   "name": "hookform-action-devtools",
   "version": "4.0.3",
-  "description": "DevTools panel for hookform-action – inspect form state, submission history, and debug optimistic UI.",
+  "description": "DevTools panel for hookform-action typed submit flows: inspect form state, submissions, and optimistic UI behavior.",
   "keywords": ["react-hook-form", "devtools", "form", "debug", "inspector"],
   "license": "MIT",
   "author": "",
diff --git a/packages/devtools/src/FormDevTool.tsx b/packages/devtools/src/FormDevTool.tsx
index c346f3b..6078291 100644
--- a/packages/devtools/src/FormDevTool.tsx
+++ b/packages/devtools/src/FormDevTool.tsx
@@ -1,9 +1,9 @@
-'use client'
+"use client";
 
-import type { ActionFormState, SubmissionRecord } from 'hookform-action-core'
-import { type CSSProperties, useCallback, useEffect, useState } from 'react'
-import type { Control, FieldValues } from 'react-hook-form'
-import { useFormState, useWatch } from 'react-hook-form'
+import type { ActionFormState, SubmissionRecord } from "hookform-action-core";
+import { type CSSProperties, useCallback, useEffect, useState } from "react";
+import type { Control, FieldValues } from "react-hook-form";
+import { useFormState, useWatch } from "react-hook-form";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -15,21 +15,21 @@ export interface FormDevToolProps<TFieldValues extends FieldValues = FieldValues
    * Must be the enhanced control that includes `_submissionHistory` and `_actionFormState`.
    */
   control: Control<TFieldValues> & {
-    _submissionHistory?: SubmissionRecord<unknown>[]
-    _actionFormState?: ActionFormState<unknown>
-  }
+    _submissionHistory?: SubmissionRecord<unknown>[];
+    _actionFormState?: ActionFormState<unknown>;
+  };
 
   /**
    * Position of the floating panel toggle button.
    * @default 'bottom-right'
    */
-  position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'
+  position?: "bottom-left" | "bottom-right" | "top-left" | "top-right";
 
   /**
    * Initial open state.
    * @default false
    */
-  defaultOpen?: boolean
+  defaultOpen?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -37,182 +37,181 @@ export interface FormDevToolProps<TFieldValues extends FieldValues = FieldValues
 // ---------------------------------------------------------------------------
 
 const COLORS = {
-  bg: '#1a1a2e',
-  bgLight: '#16213e',
-  bgPanel: '#0f3460',
-  text: '#e2e8f0',
-  textMuted: '#94a3b8',
-  accent: '#e94560',
-  success: '#10b981',
-  error: '#ef4444',
-  warning: '#f59e0b',
-  border: '#334155',
-  badge: '#7c3aed',
-}
+  bg: "#1a1a2e",
+  bgLight: "#16213e",
+  bgPanel: "#0f3460",
+  text: "#e2e8f0",
+  textMuted: "#94a3b8",
+  accent: "#e94560",
+  success: "#10b981",
+  error: "#ef4444",
+  warning: "#f59e0b",
+  border: "#334155",
+  badge: "#7c3aed",
+};
 
 function getToggleStyles(position: string): CSSProperties {
   const base: CSSProperties = {
-    position: 'fixed',
+    position: "fixed",
     zIndex: 99999,
     width: 48,
     height: 48,
-    borderRadius: '50%',
-    border: 'none',
+    borderRadius: "50%",
+    border: "none",
     backgroundColor: COLORS.accent,
-    color: '#fff',
+    color: "#fff",
     fontSize: 20,
-    cursor: 'pointer',
-    display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'center',
-    boxShadow: '0 4px 12px rgba(0,0,0,0.3)',
-    transition: 'transform 0.2s, box-shadow 0.2s',
-  }
+    cursor: "pointer",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    boxShadow: "0 4px 12px rgba(0,0,0,0.3)",
+    transition: "transform 0.2s, box-shadow 0.2s",
+  };
 
   switch (position) {
-    case 'bottom-left':
-      return { ...base, bottom: 16, left: 16 }
-    case 'top-left':
-      return { ...base, top: 16, left: 16 }
-    case 'top-right':
-      return { ...base, top: 16, right: 16 }
+    case "bottom-left":
+      return { ...base, bottom: 16, left: 16 };
+    case "top-left":
+      return { ...base, top: 16, left: 16 };
+    case "top-right":
+      return { ...base, top: 16, right: 16 };
     default:
-      return { ...base, bottom: 16, right: 16 }
+      return { ...base, bottom: 16, right: 16 };
   }
 }
 
 function getPanelStyles(position: string): CSSProperties {
   const base: CSSProperties = {
-    position: 'fixed',
+    position: "fixed",
     zIndex: 99998,
     width: 420,
-    maxHeight: '70vh',
+    maxHeight: "70vh",
     backgroundColor: COLORS.bg,
     color: COLORS.text,
     borderRadius: 12,
-    boxShadow: '0 8px 32px rgba(0,0,0,0.4)',
-    fontFamily:
-      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
+    boxShadow: "0 8px 32px rgba(0,0,0,0.4)",
+    fontFamily: 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
     fontSize: 13,
-    overflow: 'hidden',
-    display: 'flex',
-    flexDirection: 'column',
-  }
+    overflow: "hidden",
+    display: "flex",
+    flexDirection: "column",
+  };
 
   switch (position) {
-    case 'bottom-left':
-      return { ...base, bottom: 72, left: 16 }
-    case 'top-left':
-      return { ...base, top: 72, left: 16 }
-    case 'top-right':
-      return { ...base, top: 72, right: 16 }
+    case "bottom-left":
+      return { ...base, bottom: 72, left: 16 };
+    case "top-left":
+      return { ...base, top: 72, left: 16 };
+    case "top-right":
+      return { ...base, top: 72, right: 16 };
     default:
-      return { ...base, bottom: 72, right: 16 }
+      return { ...base, bottom: 72, right: 16 };
   }
 }
 
 const headerStyle: CSSProperties = {
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'space-between',
-  padding: '12px 16px',
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "space-between",
+  padding: "12px 16px",
   backgroundColor: COLORS.bgPanel,
   borderBottom: `1px solid ${COLORS.border}`,
   fontWeight: 700,
   fontSize: 14,
-}
+};
 
 const tabBarStyle: CSSProperties = {
-  display: 'flex',
+  display: "flex",
   borderBottom: `1px solid ${COLORS.border}`,
-}
+};
 
 const tabStyle = (active: boolean): CSSProperties => ({
   flex: 1,
-  padding: '8px 12px',
-  border: 'none',
-  backgroundColor: active ? COLORS.bgLight : 'transparent',
+  padding: "8px 12px",
+  border: "none",
+  backgroundColor: active ? COLORS.bgLight : "transparent",
   color: active ? COLORS.text : COLORS.textMuted,
-  cursor: 'pointer',
+  cursor: "pointer",
   fontSize: 12,
   fontWeight: active ? 600 : 400,
-  borderBottom: active ? `2px solid ${COLORS.accent}` : '2px solid transparent',
-  fontFamily: 'inherit',
-})
+  borderBottom: active ? `2px solid ${COLORS.accent}` : "2px solid transparent",
+  fontFamily: "inherit",
+});
 
 const contentStyle: CSSProperties = {
-  overflow: 'auto',
+  overflow: "auto",
   padding: 16,
-  maxHeight: 'calc(70vh - 100px)',
-}
+  maxHeight: "calc(70vh - 100px)",
+};
 
 const sectionTitle: CSSProperties = {
   fontSize: 11,
   fontWeight: 700,
-  textTransform: 'uppercase',
+  textTransform: "uppercase",
   color: COLORS.textMuted,
   marginBottom: 8,
-  letterSpacing: '0.05em',
-}
+  letterSpacing: "0.05em",
+};
 
 const kvRow: CSSProperties = {
-  display: 'flex',
-  justifyContent: 'space-between',
-  padding: '4px 0',
+  display: "flex",
+  justifyContent: "space-between",
+  padding: "4px 0",
   borderBottom: `1px solid ${COLORS.border}`,
-}
+};
 
 const keyStyle: CSSProperties = {
   color: COLORS.textMuted,
   fontSize: 12,
-}
+};
 
 const valueStyle: CSSProperties = {
   color: COLORS.text,
   fontSize: 12,
   fontWeight: 500,
   maxWidth: 200,
-  overflow: 'hidden',
-  textOverflow: 'ellipsis',
-  whiteSpace: 'nowrap',
-}
+  overflow: "hidden",
+  textOverflow: "ellipsis",
+  whiteSpace: "nowrap",
+};
 
 const badgeStyle = (color: string): CSSProperties => ({
-  display: 'inline-block',
-  padding: '2px 8px',
+  display: "inline-block",
+  padding: "2px 8px",
   borderRadius: 9999,
   fontSize: 11,
   fontWeight: 600,
   backgroundColor: color,
-  color: '#fff',
-})
+  color: "#fff",
+});
 
 const historyItemStyle = (success: boolean): CSSProperties => ({
-  padding: '8px 12px',
+  padding: "8px 12px",
   marginBottom: 8,
   borderRadius: 8,
   backgroundColor: COLORS.bgLight,
   borderLeft: `3px solid ${success ? COLORS.success : COLORS.error}`,
-})
+});
 
 const actionBtnStyle: CSSProperties = {
-  padding: '6px 12px',
+  padding: "6px 12px",
   border: `1px solid ${COLORS.border}`,
   borderRadius: 6,
-  backgroundColor: 'transparent',
+  backgroundColor: "transparent",
   color: COLORS.text,
-  cursor: 'pointer',
+  cursor: "pointer",
   fontSize: 12,
-  fontFamily: 'inherit',
+  fontFamily: "inherit",
   marginRight: 8,
-  transition: 'background-color 0.2s',
-}
+  transition: "background-color 0.2s",
+};
 
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
 
-type Tab = 'state' | 'history' | 'actions'
+type Tab = "state" | "history" | "actions";
 
 /**
  * `<FormDevTool />` – Floating debug panel for hookform-action.
@@ -242,32 +241,32 @@ type Tab = 'state' | 'history' | 'actions'
  */
 export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
   control,
-  position = 'bottom-right',
+  position = "bottom-right",
   defaultOpen = false,
 }: FormDevToolProps<TFieldValues>) {
-  const [isOpen, setIsOpen] = useState(defaultOpen)
-  const [activeTab, setActiveTab] = useState<Tab>('state')
-  const [_refreshKey, setRefreshKey] = useState(0)
+  const [isOpen, setIsOpen] = useState(defaultOpen);
+  const [activeTab, setActiveTab] = useState<Tab>("state");
+  const [_refreshKey, setRefreshKey] = useState(0);
 
   // Force re-render to pick up submission history changes
   useEffect(() => {
-    if (!isOpen) return
-    const interval = setInterval(() => setRefreshKey((k) => k + 1), 1000)
-    return () => clearInterval(interval)
-  }, [isOpen])
+    if (!isOpen) return;
+    const interval = setInterval(() => setRefreshKey((k) => k + 1), 1000);
+    return () => clearInterval(interval);
+  }, [isOpen]);
 
   // Get RHF form state
-  const formState = useFormState({ control: control as Control<TFieldValues> })
+  const formState = useFormState({ control: control as Control<TFieldValues> });
 
   // Watch all field values
-  const watchedValues = useWatch({ control: control as Control<TFieldValues> })
+  const watchedValues = useWatch({ control: control as Control<TFieldValues> });
 
   // Get action form state from control
-  const ctrl = control as unknown as Record<string, unknown>
-  const actionFormState = ctrl?._actionFormState as ActionFormState<unknown> | undefined
-  const submissionHistory = ctrl?._submissionHistory as SubmissionRecord<unknown>[] | undefined
+  const ctrl = control as unknown as Record<string, unknown>;
+  const actionFormState = ctrl?._actionFormState as ActionFormState<unknown> | undefined;
+  const submissionHistory = ctrl?._submissionHistory as SubmissionRecord<unknown>[] | undefined;
 
-  const togglePanel = useCallback(() => setIsOpen((o) => !o), [])
+  const togglePanel = useCallback(() => setIsOpen((o) => !o), []);
 
   // ---- Render: Toggle button ----------------------------------------------
 
@@ -279,11 +278,11 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
       title="Toggle Form DevTools"
       aria-label="Toggle Form DevTools"
     >
-      {isOpen ? '✕' : '🔍'}
+      {isOpen ? "✕" : "🔍"}
     </button>
-  )
+  );
 
-  if (!isOpen) return toggleButton
+  if (!isOpen) return toggleButton;
 
   // ---- State Tab ----------------------------------------------------------
 
@@ -305,11 +304,7 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
       </div>
       <div style={kvRow}>
         <span style={keyStyle}>isSubmitSuccessful</span>
-        <span
-          style={badgeStyle(
-            actionFormState?.isSubmitSuccessful ? COLORS.success : COLORS.textMuted,
-          )}
-        >
+        <span style={badgeStyle(actionFormState?.isSubmitSuccessful ? COLORS.success : COLORS.textMuted)}>
           {String(actionFormState?.isSubmitSuccessful ?? formState.isSubmitSuccessful)}
         </span>
       </div>
@@ -319,25 +314,21 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
       </div>
       <div style={kvRow}>
         <span style={keyStyle}>isDirty</span>
-        <span style={badgeStyle(formState.isDirty ? COLORS.warning : COLORS.success)}>
-          {String(formState.isDirty)}
-        </span>
+        <span style={badgeStyle(formState.isDirty ? COLORS.warning : COLORS.success)}>{String(formState.isDirty)}</span>
       </div>
       <div style={kvRow}>
         <span style={keyStyle}>isValid</span>
-        <span style={badgeStyle(formState.isValid ? COLORS.success : COLORS.error)}>
-          {String(formState.isValid)}
-        </span>
+        <span style={badgeStyle(formState.isValid ? COLORS.success : COLORS.error)}>{String(formState.isValid)}</span>
       </div>
 
       {/* Current Values */}
       <div style={{ ...sectionTitle, marginTop: 16 }}>Current Values</div>
-      {watchedValues && typeof watchedValues === 'object' ? (
+      {watchedValues && typeof watchedValues === "object" ? (
         Object.entries(watchedValues as Record<string, unknown>).map(([key, value]) => (
           <div key={key} style={kvRow}>
             <span style={keyStyle}>{key}</span>
-            <span style={valueStyle} title={String(value ?? '')}>
-              {value === undefined ? 'undefined' : value === null ? 'null' : String(value)}
+            <span style={valueStyle} title={String(value ?? "")}>
+              {value === undefined ? "undefined" : value === null ? "null" : String(value)}
             </span>
           </div>
         ))
@@ -352,7 +343,7 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
           <div key={key} style={kvRow}>
             <span style={{ ...keyStyle, color: COLORS.error }}>{key}</span>
             <span style={{ ...valueStyle, color: COLORS.error }}>
-              {String((error as Record<string, unknown>)?.message ?? 'Error')}
+              {String((error as Record<string, unknown>)?.message ?? "Error")}
             </span>
           </div>
         ))
@@ -360,22 +351,20 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
         <div style={{ color: COLORS.success, fontSize: 12 }}>✓ No errors</div>
       )}
 
-      {/* Submit Errors (from server) */}
-      {actionFormState?.submitErrors && (
+      {/* Server Errors */}
+      {actionFormState?.serverErrors && (
         <>
           <div style={{ ...sectionTitle, marginTop: 16 }}>Server Errors</div>
-          {Object.entries(actionFormState.submitErrors).map(([key, messages]) => (
+          {Object.entries(actionFormState.serverErrors).map(([key, messages]) => (
             <div key={key} style={kvRow}>
               <span style={{ ...keyStyle, color: COLORS.error }}>{key}</span>
-              <span style={{ ...valueStyle, color: COLORS.error }}>
-                {(messages ?? []).join(', ')}
-              </span>
+              <span style={{ ...valueStyle, color: COLORS.error }}>{(messages ?? []).join(", ")}</span>
             </div>
           ))}
         </>
       )}
     </div>
-  )
+  );
 
   // ---- History Tab --------------------------------------------------------
 
@@ -385,9 +374,9 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
       {submissionHistory && submissionHistory.length > 0 ? (
         [...submissionHistory].reverse().map((record) => (
           <div key={record.id} style={historyItemStyle(record.success)}>
-            <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 4 }}>
+            <div style={{ display: "flex", justifyContent: "space-between", marginBottom: 4 }}>
               <span style={badgeStyle(record.success ? COLORS.success : COLORS.error)}>
-                {record.success ? 'SUCCESS' : 'FAILED'}
+                {record.success ? "SUCCESS" : "FAILED"}
               </span>
               <span style={{ color: COLORS.textMuted, fontSize: 11 }}>{record.duration}ms</span>
             </div>
@@ -398,7 +387,7 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
               <span style={{ color: COLORS.textMuted }}>Payload: </span>
               <span style={{ color: COLORS.text }}>
                 {JSON.stringify(record.payload).slice(0, 100)}
-                {JSON.stringify(record.payload).length > 100 ? '…' : ''}
+                {JSON.stringify(record.payload).length > 100 ? "…" : ""}
               </span>
             </div>
             {record.response != null && (
@@ -406,36 +395,34 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
                 <span style={{ color: COLORS.textMuted }}>Response: </span>
                 <span style={{ color: COLORS.text }}>
                   {String(JSON.stringify(record.response)).slice(0, 100)}
-                  {String(JSON.stringify(record.response)).length > 100 ? '…' : ''}
+                  {String(JSON.stringify(record.response)).length > 100 ? "…" : ""}
                 </span>
               </div>
             )}
-            {record.error && (
-              <div style={{ fontSize: 11, color: COLORS.error }}>Error: {record.error.message}</div>
-            )}
+            {record.error && <div style={{ fontSize: 11, color: COLORS.error }}>Error: {record.error.message}</div>}
           </div>
         ))
       ) : (
-        <div style={{ color: COLORS.textMuted, fontSize: 12, textAlign: 'center', padding: 24 }}>
+        <div style={{ color: COLORS.textMuted, fontSize: 12, textAlign: "center", padding: 24 }}>
           No submissions yet
         </div>
       )}
     </div>
-  )
+  );
 
   // ---- Actions Tab --------------------------------------------------------
 
   const actionsContent = (
     <div>
       <div style={sectionTitle}>Debug Actions</div>
-      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
+      <div style={{ display: "flex", flexWrap: "wrap", gap: 8 }}>
         <button
           type="button"
           style={actionBtnStyle}
           onClick={() => {
             // Force a simulated success by dispatching to action state
             // This is a read-only view, but we can still trigger re-renders
-            console.log('[FormDevTool] Current values:', watchedValues)
+            console.log("[FormDevTool] Current values:", watchedValues);
           }}
           title="Log current form values to console"
         >
@@ -445,10 +432,10 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
           type="button"
           style={actionBtnStyle}
           onClick={() => {
-            console.log('[FormDevTool] Form state:', {
+            console.log("[FormDevTool] Form state:", {
               ...formState,
               actionFormState,
-            })
+            });
           }}
           title="Log full form state to console"
         >
@@ -458,7 +445,7 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
           type="button"
           style={actionBtnStyle}
           onClick={() => {
-            console.log('[FormDevTool] Submission history:', submissionHistory)
+            console.log("[FormDevTool] Submission history:", submissionHistory);
           }}
           title="Log submission history to console"
         >
@@ -472,8 +459,8 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
             color: COLORS.error,
           }}
           onClick={() => {
-            console.log('[FormDevTool] Errors:', formState.errors)
-            console.log('[FormDevTool] Server errors:', actionFormState?.submitErrors)
+            console.log("[FormDevTool] Errors:", formState.errors);
+            console.log("[FormDevTool] Server errors:", actionFormState?.serverErrors);
           }}
           title="Log all errors to console"
         >
@@ -503,11 +490,11 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
         <span style={valueStyle}>
           {submissionHistory && submissionHistory.length > 0
             ? `${Math.round(submissionHistory.reduce((a, r) => a + r.duration, 0) / submissionHistory.length)}ms`
-            : 'N/A'}
+            : "N/A"}
         </span>
       </div>
     </div>
-  )
+  );
 
   // ---- Panel Layout -------------------------------------------------------
 
@@ -523,50 +510,34 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
               actionFormState?.isSubmitting
                 ? COLORS.warning
                 : actionFormState?.isSubmitSuccessful
-                  ? COLORS.success
-                  : COLORS.badge,
+                ? COLORS.success
+                : COLORS.badge,
             )}
           >
-            {actionFormState?.isSubmitting
-              ? 'Submitting'
-              : actionFormState?.isSubmitSuccessful
-                ? 'Success'
-                : 'Idle'}
+            {actionFormState?.isSubmitting ? "Submitting" : actionFormState?.isSubmitSuccessful ? "Success" : "Idle"}
           </span>
         </div>
 
         {/* Tab Bar */}
         <div style={tabBarStyle}>
-          <button
-            type="button"
-            style={tabStyle(activeTab === 'state')}
-            onClick={() => setActiveTab('state')}
-          >
+          <button type="button" style={tabStyle(activeTab === "state")} onClick={() => setActiveTab("state")}>
             📋 State
           </button>
-          <button
-            type="button"
-            style={tabStyle(activeTab === 'history')}
-            onClick={() => setActiveTab('history')}
-          >
+          <button type="button" style={tabStyle(activeTab === "history")} onClick={() => setActiveTab("history")}>
             📜 History ({submissionHistory?.length ?? 0})
           </button>
-          <button
-            type="button"
-            style={tabStyle(activeTab === 'actions')}
-            onClick={() => setActiveTab('actions')}
-          >
+          <button type="button" style={tabStyle(activeTab === "actions")} onClick={() => setActiveTab("actions")}>
             ⚡ Actions
           </button>
         </div>
 
         {/* Content */}
         <div style={contentStyle}>
-          {activeTab === 'state' && stateContent}
-          {activeTab === 'history' && historyContent}
-          {activeTab === 'actions' && actionsContent}
+          {activeTab === "state" && stateContent}
+          {activeTab === "history" && historyContent}
+          {activeTab === "actions" && actionsContent}
         </div>
       </dialog>
     </>
-  )
+  );
 }
diff --git a/packages/next/README.md b/packages/next/README.md
index 26d8213..9db93cc 100644
--- a/packages/next/README.md
+++ b/packages/next/README.md
@@ -1,6 +1,6 @@
 # ⚡ hookform-action
 
-Seamless integration between **React Hook Form** and **Next.js Server Actions** with Zod validation, automatic type inference, optimistic UI, multi-step persistence, and DevTools.
+Typed submit flows between **React Hook Form** and **Next.js Server Actions**. Write the schema. Write the action. Skip the wiring.
 
 [![npm version](https://img.shields.io/npm/v/hookform-action?style=flat-square&color=5c7cfa)](https://www.npmjs.com/package/hookform-action)
 [![npm downloads](https://img.shields.io/npm/dm/hookform-action?style=flat-square&color=748ffc)](https://www.npmjs.com/package/hookform-action)
@@ -69,17 +69,58 @@ export function LoginForm() {
 }
 ```
 
-## Features
+## What you stop writing
 
-- 🔒 **Full Type Inference** — Types inferred from your action automatically
-- ⚡ **Auto Error Mapping** — Zod `.flatten().fieldErrors` mapped to RHF fields out of the box
-- 🚀 **Optimistic UI** — Native `useOptimistic` integration with automatic rollback
-- 🔍 **Client-Side Validation** — Real-time Zod validation (`onChange`/`onBlur`/`onSubmit`)
-- 💾 **Wizard Persistence** — Multi-step form state saved to sessionStorage with debounce
-- 🧩 **Headless `<Form>`** — Optional wrapper providing FormContext to children
+- ❌ Manual `FormData` → typed object conversion
+- ❌ `.flatten().fieldErrors` → `setError()` mapping
+- ❌ Duplicate Zod passes for client-side validation
+- ❌ `useTransition` / `startTransition` wiring
+- ❌ `useOptimistic` setup and rollback logic
+- ❌ `sessionStorage` wiring for multi-step wizards
+
+## What you get
+
+- 🔒 **Full Type Inference** — Types flow from your action to every field, error, and return value
+- ⚡ **Auto Error Mapping** — Zod `fieldErrors` mapped to RHF fields automatically, server and client
+- 🚀 **Optimistic UI** — `useOptimistic` wired in one option, with automatic rollback
+- 🔍 **Client-Side Validation** — Real-time Zod validation (`onChange` / `onBlur` / `onSubmit`)
+- 💾 **Wizard Persistence** — Multi-step state persisted to sessionStorage, debounced and SSR-safe
+- 🧩 **Headless `<Form>`** — Optional context wrapper for complex form trees
 - 📦 **Tiny Bundle** — ESM + CJS, tree-shakeable, peer deps only
 - 🧪 **81+ Tests** — Vitest + React Testing Library
 
+## Mental Model
+
+`hookform-action` is the glue between **React Hook Form** and your **Next.js Server Action**, with Zod living in exactly one place.
+
+**Your schema lives once — `withZod`**
+
+`withZod(schema, handler)` validates data on the server _and_ silently attaches the schema to the returned function (`action.__schema`). `useActionForm` detects it automatically for client-side real-time validation — no need to pass the schema twice.
+
+**The hook wires the submit flow**
+
+When the user submits, `handleSubmit()` runs this pipeline:
+
+```
+handleSubmit()
+  → client Zod validation  →  server action (inside useTransition)  →  isPending = true
+  → result.errors mapped back to RHF fields
+  → onSuccess / onError fired
+```
+
+You receive the full RHF API — `register`, `watch`, `setValue`, `formState.errors` — plus `isPending` and `optimistic`.
+
+**Features are strictly opt-in**
+
+The base `useActionForm` call has no extra behavior enabled. You opt in precisely:
+
+| Feature                     | How to enable                      |
+| --------------------------- | ---------------------------------- |
+| Real-time client validation | `validationMode: 'onChange'`       |
+| Optimistic UI               | `optimisticKey` + `optimisticData` |
+| Multi-step persistence      | `persistKey`                       |
+| DevTools panel              | `<FormDevTool form={form} />`      |
+
 ## API
 
 ### `useActionForm(action, options?)`
diff --git a/packages/next/package.json b/packages/next/package.json
index 46d7f89..26e30b8 100644
--- a/packages/next/package.json
+++ b/packages/next/package.json
@@ -1,7 +1,7 @@
 {
   "name": "hookform-action",
   "version": "4.0.3",
-  "description": "Next.js adapter for hookform-action – bridges React Hook Form with Server Actions.",
+  "description": "Typed submit flows for React Hook Form + Next.js Server Actions, with Zod mapping, optimistic UI, persistence, and DevTools.",
   "keywords": ["next.js", "react-hook-form", "server-actions", "form", "validation", "typescript"],
   "license": "MIT",
   "author": "",
diff --git a/packages/standalone/README.md b/packages/standalone/README.md
index 200079b..286285a 100644
--- a/packages/standalone/README.md
+++ b/packages/standalone/README.md
@@ -1,6 +1,6 @@
 # hookform-action-standalone
 
-Standalone React adapter for **hookform-action** — use the same API without Next.js. Works with **Vite**, **Remix**, **Astro**, or any React SPA.
+Typed submit flows for **React Hook Form** in **Vite**, **Remix**, **Astro**, and any React SPA. Same API, no Server Actions required.
 
 [![npm version](https://img.shields.io/npm/v/hookform-action-standalone?style=flat-square&color=5c7cfa)](https://www.npmjs.com/package/hookform-action-standalone)
 [![npm downloads](https://img.shields.io/npm/dm/hookform-action-standalone?style=flat-square&color=748ffc)](https://www.npmjs.com/package/hookform-action-standalone)
@@ -60,6 +60,22 @@ export function LoginForm() {
 }
 ```
 
+## Mental Model
+
+`hookform-action-standalone` gives you the same `useActionForm` API as the Next.js adapter — without any framework requirement. Instead of passing a Server Action, you pass a `submit` function (fetch, Axios, tRPC, or anything async).
+
+The submit flow is identical to the Next.js adapter:
+
+```
+handleSubmit()
+  → client-side Zod validation (if schema provided)
+  → your submit function called  →  isPending = true
+  → result errors mapped back to RHF fields
+  → onSuccess / onError fired
+```
+
+All optional features — real-time validation (`validationMode`), optimistic UI (`optimisticKey`), multi-step persistence (`persistKey`) — work exactly the same as in `hookform-action`.
+
 ## API
 
 ### `useActionForm(options)`
diff --git a/packages/standalone/package.json b/packages/standalone/package.json
index f925b03..b6787ff 100644
--- a/packages/standalone/package.json
+++ b/packages/standalone/package.json
@@ -1,7 +1,7 @@
 {
   "name": "hookform-action-standalone",
   "version": "4.0.3",
-  "description": "Standalone React adapter for hookform-action – use the same API without Next.js (Vite, Remix, Astro, SPAs).",
+  "description": "Standalone typed submit flows for React Hook Form with Zod mapping, optimistic UI, persistence, and DevTools.",
   "keywords": [
     "react",
     "react-hook-form",
diff --git a/packages/standalone/src/__tests__/use-action-form.test.ts b/packages/standalone/src/__tests__/use-action-form.test.ts
index 1a29000..2b573de 100644
--- a/packages/standalone/src/__tests__/use-action-form.test.ts
+++ b/packages/standalone/src/__tests__/use-action-form.test.ts
@@ -1,6 +1,6 @@
-import { act, renderHook, waitFor } from '@testing-library/react'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { useActionForm } from '../use-action-form'
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { useActionForm } from "../use-action-form";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -9,202 +9,198 @@ import { useActionForm } from '../use-action-form'
 function createFetchSubmit() {
   return vi.fn(async (data: Record<string, unknown>) => {
     // Simulate a successful API call
-    return { success: true, data }
-  })
+    return { success: true, data };
+  });
 }
 
 function createFetchErrorSubmit() {
   return vi.fn(async (_data: Record<string, unknown>) => {
-    return { errors: { email: ['Email already exists'] } }
-  })
+    return { errors: { email: ["Email already exists"] } };
+  });
 }
 
 function createThrowingFetchSubmit() {
   return vi.fn(async (_data: Record<string, unknown>) => {
-    throw new Error('Network error')
-  })
+    throw new Error("Network error");
+  });
 }
 
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('hookform-action-standalone – useActionForm', () => {
+describe("hookform-action-standalone – useActionForm", () => {
   beforeEach(() => {
-    sessionStorage.clear()
-  })
+    sessionStorage.clear();
+  });
 
-  it('returns all expected properties', () => {
+  it("returns all expected properties", () => {
     const { result } = renderHook(() =>
       useActionForm({
         submit: createFetchSubmit(),
-        defaultValues: { email: '' },
+        defaultValues: { email: "" },
       }),
-    )
+    );
 
-    expect(result.current.register).toBeDefined()
-    expect(result.current.handleSubmit).toBeDefined()
-    expect(result.current.formState).toBeDefined()
-    expect(result.current.setSubmitError).toBeDefined()
-    expect(result.current.persist).toBeDefined()
-    expect(result.current.clearPersistedData).toBeDefined()
-  })
+    expect(result.current.register).toBeDefined();
+    expect(result.current.handleSubmit).toBeDefined();
+    expect(result.current.formState).toBeDefined();
+    expect(result.current.setServerError).toBeDefined();
+    expect(result.current.persist).toBeDefined();
+    expect(result.current.clearPersisted).toBeDefined();
+  });
 
-  it('does NOT have formAction (standalone has no Server Actions)', () => {
+  it("does NOT have formAction (standalone has no Server Actions)", () => {
     const { result } = renderHook(() =>
       useActionForm({
         submit: createFetchSubmit(),
       }),
-    )
+    );
 
-    expect((result.current as Record<string, unknown>).formAction).toBeUndefined()
-  })
+    expect((result.current as Record<string, unknown>).formAction).toBeUndefined();
+  });
 
-  it('uses defaultValues', () => {
+  it("uses defaultValues", () => {
     const { result } = renderHook(() =>
       useActionForm({
         submit: createFetchSubmit(),
-        defaultValues: { email: 'hello@world.com' },
+        defaultValues: { email: "hello@world.com" },
       }),
-    )
+    );
 
-    expect(result.current.getValues('email')).toBe('hello@world.com')
-  })
+    expect(result.current.getValues("email")).toBe("hello@world.com");
+  });
 
-  it('calls the submit function on form submit', async () => {
-    const submit = createFetchSubmit()
+  it("calls the submit function on form submit", async () => {
+    const submit = createFetchSubmit();
     const { result } = renderHook(() =>
       useActionForm({
         submit,
-        defaultValues: { email: 'test@test.com' },
+        defaultValues: { email: "test@test.com" },
       }),
-    )
+    );
 
     await act(async () => {
-      await result.current.handleSubmit()()
-    })
+      await result.current.handleSubmit()();
+    });
 
     await waitFor(() => {
-      expect(submit).toHaveBeenCalledWith({ email: 'test@test.com' })
-    })
-  })
+      expect(submit).toHaveBeenCalledWith({ email: "test@test.com" });
+    });
+  });
 
-  it('sets isSubmitSuccessful after success', async () => {
-    const submit = createFetchSubmit()
+  it("sets isSubmitSuccessful after success", async () => {
+    const submit = createFetchSubmit();
     const { result } = renderHook(() =>
       useActionForm({
         submit,
-        defaultValues: { name: 'Vite user' },
+        defaultValues: { name: "Vite user" },
       }),
-    )
+    );
 
     await act(async () => {
-      await result.current.handleSubmit()()
-    })
+      await result.current.handleSubmit()();
+    });
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(true)
-    })
-  })
+      expect(result.current.formState.isSubmitSuccessful).toBe(true);
+    });
+  });
 
-  it('maps server errors to form fields', async () => {
-    const submit = createFetchErrorSubmit()
+  it("maps server errors to form fields", async () => {
+    const submit = createFetchErrorSubmit();
     const { result } = renderHook(() =>
       useActionForm({
         submit,
-        defaultValues: { email: '' },
+        defaultValues: { email: "" },
       }),
-    )
+    );
 
     await act(async () => {
-      await result.current.handleSubmit()()
-    })
+      await result.current.handleSubmit()();
+    });
 
     await waitFor(() => {
-      expect(result.current.formState.submitErrors).toEqual({
-        email: ['Email already exists'],
-      })
-    })
-  })
-
-  it('handles thrown errors', async () => {
-    const onError = vi.fn()
+      expect(result.current.formState.serverErrors).toEqual({
+        email: ["Email already exists"],
+      });
+    });
+  });
+
+  it("handles thrown errors", async () => {
+    const onError = vi.fn();
     const { result } = renderHook(() =>
       useActionForm({
         submit: createThrowingFetchSubmit(),
-        defaultValues: { email: '' },
+        defaultValues: { email: "" },
         onError,
       }),
-    )
+    );
 
     await act(async () => {
-      await result.current.handleSubmit()()
-    })
+      await result.current.handleSubmit()();
+    });
 
     await waitFor(() => {
-      expect(onError).toHaveBeenCalled()
-    })
-  })
+      expect(onError).toHaveBeenCalled();
+    });
+  });
 
-  it('calls onSuccess callback', async () => {
-    const submit = createFetchSubmit()
-    const onSuccess = vi.fn()
+  it("calls onSuccess callback", async () => {
+    const submit = createFetchSubmit();
+    const onSuccess = vi.fn();
     const { result } = renderHook(() =>
       useActionForm({
         submit,
-        defaultValues: { email: 'test@test.com' },
+        defaultValues: { email: "test@test.com" },
         onSuccess,
       }),
-    )
+    );
 
     await act(async () => {
-      await result.current.handleSubmit()()
-    })
+      await result.current.handleSubmit()();
+    });
 
     await waitFor(() => {
-      expect(onSuccess).toHaveBeenCalled()
-    })
-  })
+      expect(onSuccess).toHaveBeenCalled();
+    });
+  });
 
-  it('supports persistKey', async () => {
-    const submit = createFetchSubmit()
+  it("supports persistKey", async () => {
+    const submit = createFetchSubmit();
     const { result } = renderHook(() =>
       useActionForm({
         submit,
-        defaultValues: { email: 'persist@test.com' },
-        persistKey: 'standalone-test',
+        defaultValues: { email: "persist@test.com" },
+        persistKey: "standalone-test",
         persistDebounce: 0,
       }),
-    )
+    );
 
     await act(async () => {
-      result.current.persist()
-    })
+      result.current.persist();
+    });
 
-    const stored = sessionStorage.getItem('standalone-test')
-    expect(stored).toBeTruthy()
-    expect(JSON.parse(stored as string).email).toBe('persist@test.com')
-  })
+    const stored = sessionStorage.getItem("standalone-test");
+    expect(stored).toBeTruthy();
+    expect(JSON.parse(stored as string).email).toBe("persist@test.com");
+  });
 
-  it('works with optimistic updates', async () => {
-    const submit = createFetchSubmit()
+  it("works with optimistic updates", async () => {
+    const submit = createFetchSubmit();
     const { result } = renderHook(() =>
       useActionForm({
         submit,
-        defaultValues: { title: 'New Todo' },
-        optimisticKey: 'todo-1',
-        optimisticData: (
-          current: Record<string, unknown>,
-          formValues: Record<string, unknown>,
-        ) => ({
+        defaultValues: { title: "New Todo" },
+        optimisticReducer: (current: Record<string, unknown>, formValues: Record<string, unknown>) => ({
           ...current,
           title: formValues.title,
         }),
-        optimisticInitial: { title: 'Old Todo' },
+        optimisticDefault: { title: "Old Todo" },
       }),
-    )
+    );
 
-    expect(result.current.optimistic).toBeDefined()
-    expect(result.current.optimistic?.data).toEqual({ title: 'Old Todo' })
-  })
-})
+    expect(result.current.optimistic).toBeDefined();
+    expect(result.current.optimistic?.data).toEqual({ title: "Old Todo" });
+  });
+});

From 7c609b147111aac05a21675af880160f911a8450 Mon Sep 17 00:00:00 2001
From: Gabriel <gabriel_paes@live.com>
Date: Mon, 9 Mar 2026 19:04:05 -0300
Subject: [PATCH 3/5] lint-fix-biome-formatting

---
 apps/docs/app/api-reference/page.tsx          |   5 +-
 .../examples/_components/example-shell.tsx    |  17 +-
 apps/docs/app/examples/catalog.ts             | 175 +++++----
 .../page.tsx                                  |   4 +-
 .../page.tsx                                  |   5 +-
 .../page.tsx                                  |   4 +-
 .../next-optimistic-list-rollback/page.tsx    |  12 +-
 .../next-optimistic-profile-update/page.tsx   |  11 +-
 .../examples/next-quickstart-login/page.tsx   |  13 +-
 .../examples/next-schema-once-signup/page.tsx |   8 +-
 .../next-wizard-onboarding-persist/page.tsx   |   9 +-
 .../optimistic/optimistic-todo-form.tsx       |  72 ++--
 .../standalone-quickstart-login/page.tsx      |   4 +-
 .../standalone-rest-error-mapper/page.tsx     |   5 +-
 .../examples/validation/validation-form.tsx   |  76 ++--
 .../app/recipes/custom-error-mapper/page.tsx  |  98 +++--
 .../app/recipes/edit-server-data/page.tsx     |  85 +++--
 apps/docs/app/recipes/field-array/page.tsx    |  82 ++--
 apps/docs/app/recipes/file-upload/page.tsx    |  82 ++--
 apps/docs/app/recipes/login-form/page.tsx     |  91 +++--
 apps/docs/app/recipes/modal-form/page.tsx     |  85 +++--
 .../app/recipes/multi-step-wizard/page.tsx    |  94 +++--
 apps/docs/app/recipes/nested-fields/page.tsx  |  87 +++--
 apps/docs/app/recipes/optimistic-ui/page.tsx  |  75 ++--
 apps/docs/app/recipes/page.tsx                |  70 ++--
 .../app/recipes/reset-after-success/page.tsx  | 105 +++--
 .../app/recipes/signup-server-errors/page.tsx |  95 +++--
 .../app/recipes/standalone-fetch/page.tsx     |  91 +++--
 apps/docs/app/submit-lifecycle/page.tsx       |  61 +--
 apps/docs/app/why/page.tsx                    |  82 ++--
 .../src/__tests__/client-validation.test.ts   | 276 +++++++-------
 .../core/src/__tests__/optimistic.test.ts     | 164 ++++----
 .../core/src/__tests__/persistence.test.ts    | 144 +++----
 .../__tests__/use-action-form-core.test.ts    | 358 ++++++++---------
 .../src/__tests__/use-action-form.test.ts     | 359 +++++++++---------
 packages/core/src/core-types.ts               | 141 +++----
 packages/core/src/types.ts                    | 129 ++++---
 packages/core/src/use-action-form-core.ts     | 268 ++++++-------
 packages/core/src/use-action-form.ts          | 297 ++++++++-------
 packages/devtools/src/FormDevTool.tsx         | 327 ++++++++--------
 .../src/__tests__/use-action-form.test.ts     | 201 +++++-----
 41 files changed, 2374 insertions(+), 1993 deletions(-)

diff --git a/apps/docs/app/api-reference/page.tsx b/apps/docs/app/api-reference/page.tsx
index eb488e1..c82c663 100644
--- a/apps/docs/app/api-reference/page.tsx
+++ b/apps/docs/app/api-reference/page.tsx
@@ -16,9 +16,8 @@ export default function ApiReferencePage() {
         </p>
         <p className="text-xs text-gray-500">
           Legacy aliases are still supported for backward compatibility (
-          <code>clientValidation</code>, <code>optimisticReducer</code>,{" "}
-          <code>serverErrors</code>, <code>lastResult</code>, <code>setServerError</code>,{" "}
-          <code>clearPersisted</code>).
+          <code>clientValidation</code>, <code>optimisticReducer</code>, <code>serverErrors</code>,{' '}
+          <code>lastResult</code>, <code>setServerError</code>, <code>clearPersisted</code>).
         </p>
       </div>
 
diff --git a/apps/docs/app/examples/_components/example-shell.tsx b/apps/docs/app/examples/_components/example-shell.tsx
index f1655d4..ec3e1a9 100644
--- a/apps/docs/app/examples/_components/example-shell.tsx
+++ b/apps/docs/app/examples/_components/example-shell.tsx
@@ -1,12 +1,12 @@
-import type { ReactNode } from "react";
+import type { ReactNode } from 'react'
 
 interface ExampleShellProps {
-  title: string;
-  subtitle: string;
-  impact: string;
-  differential: string;
-  message: string;
-  children: ReactNode;
+  title: string
+  subtitle: string
+  impact: string
+  differential: string
+  message: string
+  children: ReactNode
 }
 
 export function ExampleShell({
@@ -45,6 +45,5 @@ export function ExampleShell({
 
       {children}
     </div>
-  );
+  )
 }
-
diff --git a/apps/docs/app/examples/catalog.ts b/apps/docs/app/examples/catalog.ts
index 5054d4c..6b38df2 100644
--- a/apps/docs/app/examples/catalog.ts
+++ b/apps/docs/app/examples/catalog.ts
@@ -1,125 +1,124 @@
-export type ExampleFormat = "live" | "recipe";
-export type ExampleImpact = "Muito alto" | "Alto" | "Medio";
+export type ExampleFormat = 'live' | 'recipe'
+export type ExampleImpact = 'Muito alto' | 'Alto' | 'Medio'
 
 export interface StrategicExample {
-  order: number;
-  slug: string;
-  title: string;
-  adapter: "Next.js" | "Standalone" | "Cross" | "Devtools";
-  impact: ExampleImpact;
-  format: ExampleFormat;
-  differential: string;
-  message: string;
+  order: number
+  slug: string
+  title: string
+  adapter: 'Next.js' | 'Standalone' | 'Cross' | 'Devtools'
+  impact: ExampleImpact
+  format: ExampleFormat
+  differential: string
+  message: string
 }
 
 export const strategicExamples: StrategicExample[] = [
   {
     order: 1,
-    slug: "next-quickstart-login",
-    title: "Next Quickstart Login",
-    adapter: "Next.js",
-    impact: "Muito alto",
-    format: "live",
-    differential: "RHF + Server Action + erro mapeado sem boilerplate",
-    message: "Conecte RHF a Server Actions em minutos.",
+    slug: 'next-quickstart-login',
+    title: 'Next Quickstart Login',
+    adapter: 'Next.js',
+    impact: 'Muito alto',
+    format: 'live',
+    differential: 'RHF + Server Action + erro mapeado sem boilerplate',
+    message: 'Conecte RHF a Server Actions em minutos.',
   },
   {
     order: 2,
-    slug: "standalone-quickstart-login",
-    title: "Standalone Quickstart Login",
-    adapter: "Standalone",
-    impact: "Muito alto",
-    format: "recipe",
-    differential: "Mesma API do Next adapter, sem dependencia de framework",
-    message: "Troque para submit() e rode em Vite, Remix ou Astro.",
+    slug: 'standalone-quickstart-login',
+    title: 'Standalone Quickstart Login',
+    adapter: 'Standalone',
+    impact: 'Muito alto',
+    format: 'recipe',
+    differential: 'Mesma API do Next adapter, sem dependencia de framework',
+    message: 'Troque para submit() e rode em Vite, Remix ou Astro.',
   },
   {
     order: 3,
-    slug: "migration-rhf-manual-to-hookform-action",
-    title: "Migration Manual Wiring -> hookform-action",
-    adapter: "Cross",
-    impact: "Muito alto",
-    format: "recipe",
-    differential: "Antes/depois da DX em codigo real",
-    message: "Menos estados manuais, menos glue code, menos bugs.",
+    slug: 'migration-rhf-manual-to-hookform-action',
+    title: 'Migration Manual Wiring -> hookform-action',
+    adapter: 'Cross',
+    impact: 'Muito alto',
+    format: 'recipe',
+    differential: 'Antes/depois da DX em codigo real',
+    message: 'Menos estados manuais, menos glue code, menos bugs.',
   },
   {
     order: 4,
-    slug: "next-schema-once-signup",
-    title: "Next Schema Once Signup",
-    adapter: "Next.js",
-    impact: "Alto",
-    format: "live",
-    differential: "withZod + inferencia de tipos + validacao client/server",
-    message: "Schema vive uma vez e tipa todo o fluxo.",
+    slug: 'next-schema-once-signup',
+    title: 'Next Schema Once Signup',
+    adapter: 'Next.js',
+    impact: 'Alto',
+    format: 'live',
+    differential: 'withZod + inferencia de tipos + validacao client/server',
+    message: 'Schema vive uma vez e tipa todo o fluxo.',
   },
   {
     order: 5,
-    slug: "standalone-rest-error-mapper",
-    title: "Standalone REST Error Mapper",
-    adapter: "Standalone",
-    impact: "Alto",
-    format: "recipe",
-    differential: "Mapeia contratos de erro legados sem refatorar backend",
-    message: "Adapte APIs reais sem retrabalho massivo.",
+    slug: 'standalone-rest-error-mapper',
+    title: 'Standalone REST Error Mapper',
+    adapter: 'Standalone',
+    impact: 'Alto',
+    format: 'recipe',
+    differential: 'Mapeia contratos de erro legados sem refatorar backend',
+    message: 'Adapte APIs reais sem retrabalho massivo.',
   },
   {
     order: 6,
-    slug: "next-optimistic-profile-update",
-    title: "Next Optimistic Profile Update",
-    adapter: "Next.js",
-    impact: "Alto",
-    format: "recipe",
-    differential: "Optimistic UI com rollback nativo em poucas linhas",
-    message: "Entrega UX instantanea com seguranca de estado.",
+    slug: 'next-optimistic-profile-update',
+    title: 'Next Optimistic Profile Update',
+    adapter: 'Next.js',
+    impact: 'Alto',
+    format: 'recipe',
+    differential: 'Optimistic UI com rollback nativo em poucas linhas',
+    message: 'Entrega UX instantanea com seguranca de estado.',
   },
   {
     order: 7,
-    slug: "next-wizard-onboarding-persist",
-    title: "Next Wizard Onboarding Persist",
-    adapter: "Next.js",
-    impact: "Alto",
-    format: "live",
-    differential: "Persistencia de wizard com persistKey e limpeza automatica",
-    message: "Usuario nao perde progresso ao navegar ou atualizar.",
+    slug: 'next-wizard-onboarding-persist',
+    title: 'Next Wizard Onboarding Persist',
+    adapter: 'Next.js',
+    impact: 'Alto',
+    format: 'live',
+    differential: 'Persistencia de wizard com persistKey e limpeza automatica',
+    message: 'Usuario nao perde progresso ao navegar ou atualizar.',
   },
   {
     order: 8,
-    slug: "devtools-debug-submission-history",
-    title: "Devtools Debug Submission History",
-    adapter: "Devtools",
-    impact: "Medio",
-    format: "recipe",
-    differential: "Inspecao de estado e historico de submissions em runtime",
-    message: "Debug de form deixa de ser tentativa e erro.",
+    slug: 'devtools-debug-submission-history',
+    title: 'Devtools Debug Submission History',
+    adapter: 'Devtools',
+    impact: 'Medio',
+    format: 'recipe',
+    differential: 'Inspecao de estado e historico de submissions em runtime',
+    message: 'Debug de form deixa de ser tentativa e erro.',
   },
   {
     order: 9,
-    slug: "cross-adapter-parity-next-vs-standalone",
-    title: "Cross Adapter Parity Next vs Standalone",
-    adapter: "Cross",
-    impact: "Medio",
-    format: "recipe",
-    differential: "Portabilidade comprovada com diff minimo",
-    message: "Evite lock-in de framework sem abrir mao de DX.",
+    slug: 'cross-adapter-parity-next-vs-standalone',
+    title: 'Cross Adapter Parity Next vs Standalone',
+    adapter: 'Cross',
+    impact: 'Medio',
+    format: 'recipe',
+    differential: 'Portabilidade comprovada com diff minimo',
+    message: 'Evite lock-in de framework sem abrir mao de DX.',
   },
   {
     order: 10,
-    slug: "next-optimistic-list-rollback",
-    title: "Next Optimistic List Rollback",
-    adapter: "Next.js",
-    impact: "Medio",
-    format: "live",
-    differential: "Caso avancado de optimistic para lista com falha simulada",
-    message: "Mostra robustez em cenarios de producao.",
+    slug: 'next-optimistic-list-rollback',
+    title: 'Next Optimistic List Rollback',
+    adapter: 'Next.js',
+    impact: 'Medio',
+    format: 'live',
+    differential: 'Caso avancado de optimistic para lista com falha simulada',
+    message: 'Mostra robustez em cenarios de producao.',
   },
-];
+]
 
 export const topAdoptionSlugs = new Set([
-  "next-quickstart-login",
-  "standalone-quickstart-login",
-  "migration-rhf-manual-to-hookform-action",
-  "next-schema-once-signup",
-  "next-wizard-onboarding-persist",
-]);
-
+  'next-quickstart-login',
+  'standalone-quickstart-login',
+  'migration-rhf-manual-to-hookform-action',
+  'next-schema-once-signup',
+  'next-wizard-onboarding-persist',
+])
diff --git a/apps/docs/app/examples/cross-adapter-parity-next-vs-standalone/page.tsx b/apps/docs/app/examples/cross-adapter-parity-next-vs-standalone/page.tsx
index 43f8a69..9865246 100644
--- a/apps/docs/app/examples/cross-adapter-parity-next-vs-standalone/page.tsx
+++ b/apps/docs/app/examples/cross-adapter-parity-next-vs-standalone/page.tsx
@@ -1,4 +1,4 @@
-import { ExampleShell } from "../_components/example-shell";
+import { ExampleShell } from '../_components/example-shell'
 
 export default function CrossAdapterParityPage() {
   return (
@@ -36,5 +36,5 @@ const form = useActionForm({
         </div>
       </div>
     </ExampleShell>
-  );
+  )
 }
diff --git a/apps/docs/app/examples/devtools-debug-submission-history/page.tsx b/apps/docs/app/examples/devtools-debug-submission-history/page.tsx
index 84464c1..33faa4a 100644
--- a/apps/docs/app/examples/devtools-debug-submission-history/page.tsx
+++ b/apps/docs/app/examples/devtools-debug-submission-history/page.tsx
@@ -1,4 +1,4 @@
-import { ExampleShell } from "../_components/example-shell";
+import { ExampleShell } from '../_components/example-shell'
 
 export default function DevtoolsDebugSubmissionHistoryPage() {
   return (
@@ -36,6 +36,5 @@ function App() {
         Strategic point: teams adopt faster when debugging behavior is visible and repeatable.
       </p>
     </ExampleShell>
-  );
+  )
 }
-
diff --git a/apps/docs/app/examples/migration-rhf-manual-to-hookform-action/page.tsx b/apps/docs/app/examples/migration-rhf-manual-to-hookform-action/page.tsx
index b4f7abb..9cd4a0a 100644
--- a/apps/docs/app/examples/migration-rhf-manual-to-hookform-action/page.tsx
+++ b/apps/docs/app/examples/migration-rhf-manual-to-hookform-action/page.tsx
@@ -1,4 +1,4 @@
-import { ExampleShell } from "../_components/example-shell";
+import { ExampleShell } from '../_components/example-shell'
 
 export default function MigrationManualToHookformActionPage() {
   return (
@@ -50,5 +50,5 @@ return (
         </div>
       </div>
     </ExampleShell>
-  );
+  )
 }
diff --git a/apps/docs/app/examples/next-optimistic-list-rollback/page.tsx b/apps/docs/app/examples/next-optimistic-list-rollback/page.tsx
index a35ee31..220bf06 100644
--- a/apps/docs/app/examples/next-optimistic-list-rollback/page.tsx
+++ b/apps/docs/app/examples/next-optimistic-list-rollback/page.tsx
@@ -1,7 +1,7 @@
-import { ExampleShell } from "../_components/example-shell";
-import { OptimisticTodoForm } from "../optimistic/optimistic-todo-form";
+import { ExampleShell } from '../_components/example-shell'
+import { OptimisticTodoForm } from '../optimistic/optimistic-todo-form'
 
-export const dynamic = "force-dynamic";
+export const dynamic = 'force-dynamic'
 
 export default function NextOptimisticListRollbackPage() {
   return (
@@ -17,9 +17,9 @@ export default function NextOptimisticListRollbackPage() {
       </div>
 
       <p className="text-sm text-gray-500">
-        Tip: submit a todo containing <code className="text-gray-300">fail</code> to trigger rollback.
+        Tip: submit a todo containing <code className="text-gray-300">fail</code> to trigger
+        rollback.
       </p>
     </ExampleShell>
-  );
+  )
 }
-
diff --git a/apps/docs/app/examples/next-optimistic-profile-update/page.tsx b/apps/docs/app/examples/next-optimistic-profile-update/page.tsx
index 2577302..8b2e079 100644
--- a/apps/docs/app/examples/next-optimistic-profile-update/page.tsx
+++ b/apps/docs/app/examples/next-optimistic-profile-update/page.tsx
@@ -1,4 +1,4 @@
-import { ExampleShell } from "../_components/example-shell";
+import { ExampleShell } from '../_components/example-shell'
 
 export default function NextOptimisticProfileUpdatePage() {
   return (
@@ -35,12 +35,15 @@ return (
       </div>
 
       <p className="text-sm text-gray-500">
-        Want a live list scenario? Open{" "}
-        <a className="text-brand-300 hover:text-brand-200" href="/examples/next-optimistic-list-rollback">
+        Want a live list scenario? Open{' '}
+        <a
+          className="text-brand-300 hover:text-brand-200"
+          href="/examples/next-optimistic-list-rollback"
+        >
           Next Optimistic List Rollback
         </a>
         .
       </p>
     </ExampleShell>
-  );
+  )
 }
diff --git a/apps/docs/app/examples/next-quickstart-login/page.tsx b/apps/docs/app/examples/next-quickstart-login/page.tsx
index c070b31..b9c9f03 100644
--- a/apps/docs/app/examples/next-quickstart-login/page.tsx
+++ b/apps/docs/app/examples/next-quickstart-login/page.tsx
@@ -1,7 +1,7 @@
-import { LoginForm } from "../login/login-form";
-import { ExampleShell } from "../_components/example-shell";
+import { ExampleShell } from '../_components/example-shell'
+import { LoginForm } from '../login/login-form'
 
-export const dynamic = "force-dynamic";
+export const dynamic = 'force-dynamic'
 
 export default function NextQuickstartLoginPage() {
   return (
@@ -18,8 +18,8 @@ export default function NextQuickstartLoginPage() {
 
       <h2 className="text-xl font-semibold mb-3">Why this sells the library</h2>
       <p className="text-gray-400 mb-6">
-        This is the shortest path from install to success. It proves pending state, server validation,
-        and field-level error mapping in one place.
+        This is the shortest path from install to success. It proves pending state, server
+        validation, and field-level error mapping in one place.
       </p>
 
       <div className="code-block text-gray-300">
@@ -34,6 +34,5 @@ export default function NextQuickstartLoginPage() {
 </form>`}</pre>
       </div>
     </ExampleShell>
-  );
+  )
 }
-
diff --git a/apps/docs/app/examples/next-schema-once-signup/page.tsx b/apps/docs/app/examples/next-schema-once-signup/page.tsx
index f3f82f3..02f58fa 100644
--- a/apps/docs/app/examples/next-schema-once-signup/page.tsx
+++ b/apps/docs/app/examples/next-schema-once-signup/page.tsx
@@ -1,7 +1,7 @@
-import { ExampleShell } from "../_components/example-shell";
-import { ValidationForm } from "../validation/validation-form";
+import { ExampleShell } from '../_components/example-shell'
+import { ValidationForm } from '../validation/validation-form'
 
-export const dynamic = "force-dynamic";
+export const dynamic = 'force-dynamic'
 
 export default function NextSchemaOnceSignupPage() {
   return (
@@ -28,5 +28,5 @@ const form = useActionForm(signupAction, {
 });`}</pre>
       </div>
     </ExampleShell>
-  );
+  )
 }
diff --git a/apps/docs/app/examples/next-wizard-onboarding-persist/page.tsx b/apps/docs/app/examples/next-wizard-onboarding-persist/page.tsx
index fc0f529..67dffd3 100644
--- a/apps/docs/app/examples/next-wizard-onboarding-persist/page.tsx
+++ b/apps/docs/app/examples/next-wizard-onboarding-persist/page.tsx
@@ -1,7 +1,7 @@
-import { ExampleShell } from "../_components/example-shell";
-import { WizardForm } from "../wizard/wizard-form";
+import { ExampleShell } from '../_components/example-shell'
+import { WizardForm } from '../wizard/wizard-form'
 
-export const dynamic = "force-dynamic";
+export const dynamic = 'force-dynamic'
 
 export default function NextWizardOnboardingPersistPage() {
   return (
@@ -32,6 +32,5 @@ export default function NextWizardOnboardingPersistPage() {
 });`}</pre>
       </div>
     </ExampleShell>
-  );
+  )
 }
-
diff --git a/apps/docs/app/examples/optimistic/optimistic-todo-form.tsx b/apps/docs/app/examples/optimistic/optimistic-todo-form.tsx
index 7d149d8..664c5a7 100644
--- a/apps/docs/app/examples/optimistic/optimistic-todo-form.tsx
+++ b/apps/docs/app/examples/optimistic/optimistic-todo-form.tsx
@@ -1,20 +1,20 @@
-"use client";
+'use client'
 
-import { useActionForm } from "hookform-action";
-import { type Todo, addTodoAction } from "./actions";
+import { useActionForm } from 'hookform-action'
+import { type Todo, addTodoAction } from './actions'
 
 const initialTodos: Todo[] = [
-  { id: "1", text: "Read hookform-action docs", done: true },
-  { id: "2", text: "Upgrade to React 19", done: false },
-  { id: "3", text: "Add optimistic UI to my app", done: false },
-];
+  { id: '1', text: 'Read hookform-action docs', done: true },
+  { id: '2', text: 'Upgrade to React 19', done: false },
+  { id: '3', text: 'Add optimistic UI to my app', done: false },
+]
 
 type AddTodoResult = {
-  todos: Todo[];
+  todos: Todo[]
   errors?: {
-    text?: string[];
-  };
-};
+    text?: string[]
+  }
+}
 
 export function OptimisticTodoForm() {
   const {
@@ -24,16 +24,16 @@ export function OptimisticTodoForm() {
     formState: { errors, isPending, actionResult },
     optimistic,
   } = useActionForm<{ text: string }, AddTodoResult, Todo[]>(addTodoAction, {
-    defaultValues: { text: "" },
+    defaultValues: { text: '' },
     optimisticInitial: initialTodos,
     optimisticData: (current: Todo[], values) => [
       ...current,
       { id: `temp-${Date.now()}`, text: values.text, done: false },
     ],
-  });
+  })
 
-  const confirmedTodos = actionResult?.todos ?? initialTodos;
-  const todos = optimistic?.isPending ? optimistic.data ?? confirmedTodos : confirmedTodos;
+  const confirmedTodos = actionResult?.todos ?? initialTodos
+  const todos = optimistic?.isPending ? (optimistic.data ?? confirmedTodos) : confirmedTodos
 
   return (
     <div className="space-y-6">
@@ -42,20 +42,24 @@ export function OptimisticTodoForm() {
           <div
             key={todo.id}
             className={`flex items-center gap-3 px-4 py-3 rounded-lg border transition-all ${
-              todo.id.startsWith("temp-")
-                ? "border-brand-500/50 bg-brand-500/10 animate-pulse"
-                : "border-gray-700 bg-gray-900/50"
+              todo.id.startsWith('temp-')
+                ? 'border-brand-500/50 bg-brand-500/10 animate-pulse'
+                : 'border-gray-700 bg-gray-900/50'
             }`}
           >
-            <span className={`text-lg ${todo.done ? "opacity-50" : ""}`}>{todo.done ? "✅" : "⬜"}</span>
+            <span className={`text-lg ${todo.done ? 'opacity-50' : ''}`}>
+              {todo.done ? '✅' : '⬜'}
+            </span>
             <span
-              className={`flex-1 ${todo.done ? "line-through text-gray-500" : "text-gray-200"} ${
-                todo.id.startsWith("temp-") ? "text-brand-300 italic" : ""
+              className={`flex-1 ${todo.done ? 'line-through text-gray-500' : 'text-gray-200'} ${
+                todo.id.startsWith('temp-') ? 'text-brand-300 italic' : ''
               }`}
             >
               {todo.text}
             </span>
-            {todo.id.startsWith("temp-") && <span className="text-xs text-brand-400 font-medium">saving...</span>}
+            {todo.id.startsWith('temp-') && (
+              <span className="text-xs text-brand-400 font-medium">saving...</span>
+            )}
           </div>
         ))}
       </div>
@@ -63,8 +67,20 @@ export function OptimisticTodoForm() {
       {optimistic?.isPending && (
         <div className="text-xs text-brand-400 flex items-center gap-2">
           <svg className="animate-spin h-3 w-3" viewBox="0 0 24 24" aria-hidden="true">
-            <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" fill="none" />
-            <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
+            <circle
+              className="opacity-25"
+              cx="12"
+              cy="12"
+              r="10"
+              stroke="currentColor"
+              strokeWidth="4"
+              fill="none"
+            />
+            <path
+              className="opacity-75"
+              fill="currentColor"
+              d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
+            />
           </svg>
           Syncing with server...
         </div>
@@ -72,7 +88,7 @@ export function OptimisticTodoForm() {
 
       <form
         onSubmit={handleSubmit(() => {
-          reset({ text: "" });
+          reset({ text: '' })
         })}
         className="flex gap-3"
       >
@@ -80,7 +96,7 @@ export function OptimisticTodoForm() {
           <input
             placeholder="Add a new todo..."
             className="w-full px-4 py-2.5 bg-gray-900 border border-gray-700 rounded-lg text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-brand-500 focus:border-transparent transition-colors"
-            {...register("text")}
+            {...register('text')}
           />
           {errors.text && <p className="mt-1 text-sm text-red-400">{errors.text.message}</p>}
         </div>
@@ -89,9 +105,9 @@ export function OptimisticTodoForm() {
           disabled={isPending}
           className="px-6 py-2.5 bg-brand-600 hover:bg-brand-500 disabled:bg-gray-700 disabled:cursor-not-allowed text-white rounded-lg font-medium transition-colors whitespace-nowrap"
         >
-          {isPending ? "Adding..." : "Add Todo"}
+          {isPending ? 'Adding...' : 'Add Todo'}
         </button>
       </form>
     </div>
-  );
+  )
 }
diff --git a/apps/docs/app/examples/standalone-quickstart-login/page.tsx b/apps/docs/app/examples/standalone-quickstart-login/page.tsx
index b3dbd62..afc1dd1 100644
--- a/apps/docs/app/examples/standalone-quickstart-login/page.tsx
+++ b/apps/docs/app/examples/standalone-quickstart-login/page.tsx
@@ -1,4 +1,4 @@
-import { ExampleShell } from "../_components/example-shell";
+import { ExampleShell } from '../_components/example-shell'
 
 export default function StandaloneQuickstartLoginPage() {
   return (
@@ -52,5 +52,5 @@ export function LoginForm() {
         Strategic point: this removes framework lock-in objections during evaluation.
       </p>
     </ExampleShell>
-  );
+  )
 }
diff --git a/apps/docs/app/examples/standalone-rest-error-mapper/page.tsx b/apps/docs/app/examples/standalone-rest-error-mapper/page.tsx
index fb008fd..714215f 100644
--- a/apps/docs/app/examples/standalone-rest-error-mapper/page.tsx
+++ b/apps/docs/app/examples/standalone-rest-error-mapper/page.tsx
@@ -1,4 +1,4 @@
-import { ExampleShell } from "../_components/example-shell";
+import { ExampleShell } from '../_components/example-shell'
 
 export default function StandaloneRestErrorMapperPage() {
   return (
@@ -35,6 +35,5 @@ const form = useActionForm({
         Strategic point: this removes one of the most common adoption blockers in enterprise apps.
       </p>
     </ExampleShell>
-  );
+  )
 }
-
diff --git a/apps/docs/app/examples/validation/validation-form.tsx b/apps/docs/app/examples/validation/validation-form.tsx
index 8eb5e84..c7ed005 100644
--- a/apps/docs/app/examples/validation/validation-form.tsx
+++ b/apps/docs/app/examples/validation/validation-form.tsx
@@ -1,8 +1,8 @@
-"use client";
+'use client'
 
-import { useActionForm } from "hookform-action";
-import { signupAction } from "./actions";
-import { signupSchema } from "./schema";
+import { useActionForm } from 'hookform-action'
+import { signupAction } from './actions'
+import { signupSchema } from './schema'
 
 export function ValidationForm() {
   const {
@@ -10,11 +10,11 @@ export function ValidationForm() {
     handleSubmit,
     formState: { errors, isPending, isSubmitSuccessful },
   } = useActionForm(signupAction, {
-    defaultValues: { username: "", email: "", password: "" },
+    defaultValues: { username: '', email: '', password: '' },
     // Pass the schema for client-side validation on every change
     schema: signupSchema,
-    validationMode: "onChange",
-  });
+    validationMode: 'onChange',
+  })
 
   if (isSubmitSuccessful) {
     return (
@@ -24,7 +24,7 @@ export function ValidationForm() {
           Client-side validation passed, then the server action ran successfully.
         </p>
       </div>
-    );
+    )
   }
 
   return (
@@ -38,13 +38,19 @@ export function ValidationForm() {
           type="text"
           placeholder="my_username"
           className={`w-full px-4 py-2.5 bg-gray-900 border rounded-lg text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:border-transparent transition-colors ${
-            errors.username ? "border-red-500 focus:ring-red-500" : "border-gray-700 focus:ring-brand-500"
+            errors.username
+              ? 'border-red-500 focus:ring-red-500'
+              : 'border-gray-700 focus:ring-brand-500'
           }`}
-          {...register("username")}
+          {...register('username')}
         />
-        {errors.username && <p className="mt-1.5 text-sm text-red-400">{errors.username.message}</p>}
+        {errors.username && (
+          <p className="mt-1.5 text-sm text-red-400">{errors.username.message}</p>
+        )}
         {!errors.username && (
-          <p className="mt-1.5 text-xs text-gray-500">3–20 characters, letters, numbers, underscores</p>
+          <p className="mt-1.5 text-xs text-gray-500">
+            3–20 characters, letters, numbers, underscores
+          </p>
         )}
       </div>
 
@@ -57,9 +63,11 @@ export function ValidationForm() {
           type="email"
           placeholder="you@example.com"
           className={`w-full px-4 py-2.5 bg-gray-900 border rounded-lg text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:border-transparent transition-colors ${
-            errors.email ? "border-red-500 focus:ring-red-500" : "border-gray-700 focus:ring-brand-500"
+            errors.email
+              ? 'border-red-500 focus:ring-red-500'
+              : 'border-gray-700 focus:ring-brand-500'
           }`}
-          {...register("email")}
+          {...register('email')}
         />
         {errors.email && <p className="mt-1.5 text-sm text-red-400">{errors.email.message}</p>}
       </div>
@@ -73,12 +81,18 @@ export function ValidationForm() {
           type="password"
           placeholder="••••••••"
           className={`w-full px-4 py-2.5 bg-gray-900 border rounded-lg text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:border-transparent transition-colors ${
-            errors.password ? "border-red-500 focus:ring-red-500" : "border-gray-700 focus:ring-brand-500"
+            errors.password
+              ? 'border-red-500 focus:ring-red-500'
+              : 'border-gray-700 focus:ring-brand-500'
           }`}
-          {...register("password")}
+          {...register('password')}
         />
-        {errors.password && <p className="mt-1.5 text-sm text-red-400">{errors.password.message}</p>}
-        {!errors.password && <p className="mt-1.5 text-xs text-gray-500">8+ characters, one uppercase, one number</p>}
+        {errors.password && (
+          <p className="mt-1.5 text-sm text-red-400">{errors.password.message}</p>
+        )}
+        {!errors.password && (
+          <p className="mt-1.5 text-xs text-gray-500">8+ characters, one uppercase, one number</p>
+        )}
       </div>
 
       <button
@@ -89,21 +103,33 @@ export function ValidationForm() {
         {isPending ? (
           <span className="inline-flex items-center gap-2">
             <svg className="animate-spin h-4 w-4" viewBox="0 0 24 24" aria-hidden="true">
-              <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" fill="none" />
-              <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
+              <circle
+                className="opacity-25"
+                cx="12"
+                cy="12"
+                r="10"
+                stroke="currentColor"
+                strokeWidth="4"
+                fill="none"
+              />
+              <path
+                className="opacity-75"
+                fill="currentColor"
+                d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
+              />
             </svg>
             Creating account...
           </span>
         ) : (
-          "Create Account"
+          'Create Account'
         )}
       </button>
 
       <p className="text-xs text-gray-500 text-center">
-        Try <code className="text-gray-400">admin</code> as username or{" "}
-        <code className="text-gray-400">taken@example.com</code> as email to see server-side errors (after client
-        validation passes).
+        Try <code className="text-gray-400">admin</code> as username or{' '}
+        <code className="text-gray-400">taken@example.com</code> as email to see server-side errors
+        (after client validation passes).
       </p>
     </form>
-  );
+  )
 }
diff --git a/apps/docs/app/recipes/custom-error-mapper/page.tsx b/apps/docs/app/recipes/custom-error-mapper/page.tsx
index c897afc..d06855c 100644
--- a/apps/docs/app/recipes/custom-error-mapper/page.tsx
+++ b/apps/docs/app/recipes/custom-error-mapper/page.tsx
@@ -16,9 +16,9 @@ export default function CustomErrorMapperPage() {
         </div>
         <h1 className="text-3xl font-bold mb-3">Custom Error Mapper</h1>
         <p className="text-lg text-gray-400">
-          When your API returns errors in a format different from the default{" "}
-          <code>{`{ errors: { field: string[] } }`}</code>, use a custom <code>errorMapper</code> to translate them into
-          React Hook Form field errors automatically.
+          When your API returns errors in a format different from the default{' '}
+          <code>{'{ errors: { field: string[] } }'}</code>, use a custom <code>errorMapper</code> to
+          translate them into React Hook Form field errors automatically.
         </p>
       </div>
 
@@ -26,15 +26,17 @@ export default function CustomErrorMapperPage() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-3">Why it matters</h2>
         <p className="text-gray-400 leading-relaxed">
-          APIs designed before this library existed — Laravel backends, Rails APIs, external REST services, tRPC
-          procedures — rarely return errors in the <code>{`{ errors: { field: string[] } }`}</code> format that{" "}
-          <code>defaultErrorMapper</code> expects. Without a custom mapper, the hook cannot automatically set field
-          errors and you end up writing manual <code>setSubmitError</code> calls all over your form components.
+          APIs designed before this library existed — Laravel backends, Rails APIs, external REST
+          services, tRPC procedures — rarely return errors in the{' '}
+          <code>{'{ errors: { field: string[] } }'}</code> format that{' '}
+          <code>defaultErrorMapper</code> expects. Without a custom mapper, the hook cannot
+          automatically set field errors and you end up writing manual <code>setSubmitError</code>{' '}
+          calls all over your form components.
         </p>
         <p className="text-gray-400 leading-relaxed mt-3">
-          The <code>errorMapper</code> option is a pure function defined once per form (or shared across forms hitting
-          the same API). It receives the raw action result and returns a <code>FieldErrorRecord</code> that the hook
-          applies to the correct fields automatically.
+          The <code>errorMapper</code> option is a pure function defined once per form (or shared
+          across forms hitting the same API). It receives the raw action result and returns a{' '}
+          <code>FieldErrorRecord</code> that the hook applies to the correct fields automatically.
         </p>
       </section>
 
@@ -55,8 +57,8 @@ export default function CustomErrorMapperPage() {
   }
 }`}</pre>
             <p className="text-sm text-gray-500 mt-2">
-              (Laravel-style — the <code>errors</code> values are arrays of strings, which happens to match the default
-              format. The next example shows a stricter mismatch.)
+              (Laravel-style — the <code>errors</code> values are arrays of strings, which happens
+              to match the default format. The next example shows a stricter mismatch.)
             </p>
           </div>
         </div>
@@ -88,7 +90,9 @@ export function RegistrationForm() {
         <div className="mb-5">
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4 mb-4">
             <p className="text-sm text-gray-400 mb-2">
-              <span className="text-gray-200 font-medium">A non-standard API (object-per-error format):</span>
+              <span className="text-gray-200 font-medium">
+                A non-standard API (object-per-error format):
+              </span>
             </p>
             <pre className="text-gray-300 text-sm">{`{
   "fieldErrors": {
@@ -211,34 +215,39 @@ export function RegistrationForm() {
         <h2 className="text-xl font-bold mb-4">Key Concepts</h2>
         <div className="space-y-3">
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
-            <code className="text-brand-400">errorMapper: (result) =&gt; FieldErrorRecord | null</code>
+            <code className="text-brand-400">
+              errorMapper: (result) =&gt; FieldErrorRecord | null
+            </code>
             <p className="text-gray-400 text-sm mt-1">
-              A pure function that receives the raw action result (typed as <code>TResult</code>) and returns a{" "}
-              <code>FieldErrorRecord</code> — a <code>Record&lt;string, string[] | undefined&gt;</code>. Return{" "}
-              <code>null</code> or <code>undefined</code> when there are no errors. The hook calls <code>setError</code>{" "}
+              A pure function that receives the raw action result (typed as <code>TResult</code>)
+              and returns a <code>FieldErrorRecord</code> — a{' '}
+              <code>Record&lt;string, string[] | undefined&gt;</code>. Return <code>null</code> or{' '}
+              <code>undefined</code> when there are no errors. The hook calls <code>setError</code>{' '}
               on each field automatically.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">Define mapper outside the component</code>
             <p className="text-gray-400 text-sm mt-1">
-              The <code>errorMapper</code> is compared by reference between renders. An inline arrow function creates a
-              new reference every time, causing the hook to re-run unnecessarily. Define it at module scope or wrap with{" "}
-              <code>useCallback</code>.
+              The <code>errorMapper</code> is compared by reference between renders. An inline arrow
+              function creates a new reference every time, causing the hook to re-run unnecessarily.
+              Define it at module scope or wrap with <code>useCallback</code>.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">Global errors via actionResult</code>
             <p className="text-gray-400 text-sm mt-1">
-              Errors that cannot be mapped to a specific field (e.g. &quot;service unavailable&quot;) should be read
-              from <code>formState.actionResult</code> and rendered separately — not through the field error system.
+              Errors that cannot be mapped to a specific field (e.g. &quot;service
+              unavailable&quot;) should be read from <code>formState.actionResult</code> and
+              rendered separately — not through the field error system.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">Composing with defaultErrorMapper</code>
             <p className="text-gray-400 text-sm mt-1">
-              You can import and call <code>defaultErrorMapper</code> inside your custom mapper as a fallback for fields
-              that already match the default format, and only override the fields that don&apos;t.
+              You can import and call <code>defaultErrorMapper</code> inside your custom mapper as a
+              fallback for fields that already match the default format, and only override the
+              fields that don&apos;t.
             </p>
           </div>
         </div>
@@ -252,12 +261,13 @@ export function RegistrationForm() {
             <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
             <div>
               <p className="text-sm font-medium text-gray-200">
-                Returning an empty object <code>{`{}`}</code> instead of <code>null</code>
+                Returning an empty object <code>{'{}'}</code> instead of <code>null</code>
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                The hook checks if the returned object is truthy and has keys. An empty object <code>{`{}`}</code> is
-                truthy, but all its field lookups return <code>undefined</code>. Return <code>null</code> or{" "}
-                <code>undefined</code> explicitly when there are no errors to map.
+                The hook checks if the returned object is truthy and has keys. An empty object{' '}
+                <code>{'{}'}</code> is truthy, but all its field lookups return{' '}
+                <code>undefined</code>. Return <code>null</code> or <code>undefined</code>{' '}
+                explicitly when there are no errors to map.
               </p>
             </div>
           </li>
@@ -268,19 +278,22 @@ export function RegistrationForm() {
                 Inline arrow function as <code>errorMapper</code>
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                <code>{"errorMapper: (r) => ..."}</code> creates a new function on every render. Since the hook uses it
-                as a dependency, this can cause performance issues. Always define the mapper at module scope.
+                <code>{'errorMapper: (r) => ...'}</code> creates a new function on every render.
+                Since the hook uses it as a dependency, this can cause performance issues. Always
+                define the mapper at module scope.
               </p>
             </div>
           </li>
           <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
             <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
             <div>
-              <p className="text-sm font-medium text-gray-200">Mapper receives the result even on success</p>
+              <p className="text-sm font-medium text-gray-200">
+                Mapper receives the result even on success
+              </p>
               <p className="text-sm text-gray-400 mt-1">
-                <code>errorMapper</code> is called after every action invocation, including successful ones. Always add
-                a guard (e.g. check for the presence of an error key) and return <code>null</code> for success
-                responses.
+                <code>errorMapper</code> is called after every action invocation, including
+                successful ones. Always add a guard (e.g. check for the presence of an error key)
+                and return <code>null</code> for success responses.
               </p>
             </div>
           </li>
@@ -291,17 +304,26 @@ export function RegistrationForm() {
       <section className="border-t border-gray-800 pt-8">
         <h2 className="text-lg font-semibold mb-4">Related</h2>
         <div className="flex flex-wrap gap-4 text-sm">
-          <a href="/recipes/signup-server-errors" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/signup-server-errors"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Sign Up with Server Errors
           </a>
-          <a href="/recipes/standalone-fetch" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/standalone-fetch"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Standalone — Fetch &amp; Custom APIs
           </a>
-          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/api-reference"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → API Reference
           </a>
         </div>
       </section>
     </div>
-  );
+  )
 }
diff --git a/apps/docs/app/recipes/edit-server-data/page.tsx b/apps/docs/app/recipes/edit-server-data/page.tsx
index 8c4e50f..fccf614 100644
--- a/apps/docs/app/recipes/edit-server-data/page.tsx
+++ b/apps/docs/app/recipes/edit-server-data/page.tsx
@@ -16,8 +16,8 @@ export default function EditServerDataPage() {
         </div>
         <h1 className="text-3xl font-bold mb-3">Edit Form with Server-Loaded Data</h1>
         <p className="text-lg text-gray-400">
-          Pre-populate a form from a Server Component, track which fields the user actually changed, and revalidate the
-          page data after a successful save.
+          Pre-populate a form from a Server Component, track which fields the user actually changed,
+          and revalidate the page data after a successful save.
         </p>
       </div>
 
@@ -25,15 +25,16 @@ export default function EditServerDataPage() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-3">Why it matters</h2>
         <p className="text-gray-400 leading-relaxed">
-          Edit forms are the second most common form type after login. They require loading data from the server and
-          using it as <code>defaultValues</code> — but there&apos;s a fundamental tension: Server Components can fetch
-          data asynchronously, while <code>useActionForm</code> lives in a Client Component. Getting the data handoff
-          right prevents stale defaults and unintended dirty-field detection.
+          Edit forms are the second most common form type after login. They require loading data
+          from the server and using it as <code>defaultValues</code> — but there&apos;s a
+          fundamental tension: Server Components can fetch data asynchronously, while{' '}
+          <code>useActionForm</code> lives in a Client Component. Getting the data handoff right
+          prevents stale defaults and unintended dirty-field detection.
         </p>
         <p className="text-gray-400 leading-relaxed mt-3">
-          This recipe shows the canonical Server → Client pattern, how to use <code>isDirty</code> to show the save
-          button only when something changed, and how to use <code>router.refresh()</code> to revalidate without a full
-          page reload.
+          This recipe shows the canonical Server → Client pattern, how to use <code>isDirty</code>{' '}
+          to show the save button only when something changed, and how to use{' '}
+          <code>router.refresh()</code> to revalidate without a full page reload.
         </p>
       </section>
 
@@ -173,33 +174,36 @@ export function EditProfileForm({ defaultValues }: EditProfileFormProps) {
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">Server Component → Client Component data handoff</code>
             <p className="text-gray-400 text-sm mt-1">
-              Fetch data in an async Server Component, then pass it as a plain prop to the Client Component. The Client
-              Component receives it as a stable object and uses it as <code>defaultValues</code>. This avoids the{" "}
-              <code>useEffect</code> fetch anti-pattern and leverages Next.js caching.
+              Fetch data in an async Server Component, then pass it as a plain prop to the Client
+              Component. The Client Component receives it as a stable object and uses it as{' '}
+              <code>defaultValues</code>. This avoids the <code>useEffect</code> fetch anti-pattern
+              and leverages Next.js caching.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">isDirty / dirtyFields</code>
             <p className="text-gray-400 text-sm mt-1">
-              <code>isDirty</code> is <code>true</code> when at least one field differs from its{" "}
-              <code>defaultValue</code>. <code>dirtyFields</code> is a record of which specific fields changed. Use them
-              to disable the save button when nothing has been modified and to show per-field change indicators.
+              <code>isDirty</code> is <code>true</code> when at least one field differs from its{' '}
+              <code>defaultValue</code>. <code>dirtyFields</code> is a record of which specific
+              fields changed. Use them to disable the save button when nothing has been modified and
+              to show per-field change indicators.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">router.refresh()</code>
             <p className="text-gray-400 text-sm mt-1">
-              Re-executes all Server Components on the current route without a full navigation. The Server Component
-              re-fetches the updated data and passes it as new props to the Client Component. Call it in{" "}
-              <code>onSuccess</code> after a successful save.
+              Re-executes all Server Components on the current route without a full navigation. The
+              Server Component re-fetches the updated data and passes it as new props to the Client
+              Component. Call it in <code>onSuccess</code> after a successful save.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">reset(newValues) after save</code>
             <p className="text-gray-400 text-sm mt-1">
-              After a successful edit, call <code>reset(result.data)</code> or <code>reset(defaultValues)</code> to
-              update the RHF baseline. This clears <code>isDirty</code> so the save button correctly disables again
-              without a full remount.
+              After a successful edit, call <code>reset(result.data)</code> or{' '}
+              <code>reset(defaultValues)</code> to update the RHF baseline. This clears{' '}
+              <code>isDirty</code> so the save button correctly disables again without a full
+              remount.
             </p>
           </div>
         </div>
@@ -216,9 +220,9 @@ export function EditProfileForm({ defaultValues }: EditProfileFormProps) {
                 Unstable <code>defaultValues</code> causing unintended resets
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                If <code>defaultValues</code> is an inline object literal created on every render, RHF may re-initialise
-                and clear user edits. Always pass a stable reference — either from a Server Component prop, a{" "}
-                <code>useMemo</code>, or a fetched query result.
+                If <code>defaultValues</code> is an inline object literal created on every render,
+                RHF may re-initialise and clear user edits. Always pass a stable reference — either
+                from a Server Component prop, a <code>useMemo</code>, or a fetched query result.
               </p>
             </div>
           </li>
@@ -229,9 +233,9 @@ export function EditProfileForm({ defaultValues }: EditProfileFormProps) {
                 <code>isSubmitSuccessful</code> stays <code>true</code> after save
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                For edit forms you usually want the user to stay on the page and keep editing. Avoid gating the form
-                behind <code>isSubmitSuccessful</code> — it will hide the form after the first save. Use{" "}
-                <code>onSuccess</code> for side effects only.
+                For edit forms you usually want the user to stay on the page and keep editing. Avoid
+                gating the form behind <code>isSubmitSuccessful</code> — it will hide the form after
+                the first save. Use <code>onSuccess</code> for side effects only.
               </p>
             </div>
           </li>
@@ -242,8 +246,9 @@ export function EditProfileForm({ defaultValues }: EditProfileFormProps) {
                 Forgetting <code>reset()</code> after a successful save
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                Without <code>reset()</code>, <code>isDirty</code> stays <code>true</code> even though the changes were
-                saved. The save button remains enabled and the user may accidentally re-submit.
+                Without <code>reset()</code>, <code>isDirty</code> stays <code>true</code> even
+                though the changes were saved. The save button remains enabled and the user may
+                accidentally re-submit.
               </p>
             </div>
           </li>
@@ -254,20 +259,32 @@ export function EditProfileForm({ defaultValues }: EditProfileFormProps) {
       <section className="border-t border-gray-800 pt-8">
         <h2 className="text-lg font-semibold mb-4">Related</h2>
         <div className="flex flex-wrap gap-4 text-sm">
-          <a href="/recipes/reset-after-success" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/reset-after-success"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Reset After Success
           </a>
-          <a href="/recipes/modal-form" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/modal-form"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Modal / Dialog Form
           </a>
-          <a href="/recipes/signup-server-errors" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/signup-server-errors"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Sign Up with Server Errors
           </a>
-          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/api-reference"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → API Reference
           </a>
         </div>
       </section>
     </div>
-  );
+  )
 }
diff --git a/apps/docs/app/recipes/field-array/page.tsx b/apps/docs/app/recipes/field-array/page.tsx
index ec138ca..28ad77c 100644
--- a/apps/docs/app/recipes/field-array/page.tsx
+++ b/apps/docs/app/recipes/field-array/page.tsx
@@ -16,8 +16,8 @@ export default function FieldArrayPage() {
         </div>
         <h1 className="text-3xl font-bold mb-3">Dynamic Fields with useFieldArray</h1>
         <p className="text-lg text-gray-400">
-          Add and remove array items at runtime, validate each row independently, and submit the full typed array to
-          your server action.
+          Add and remove array items at runtime, validate each row independently, and submit the
+          full typed array to your server action.
         </p>
       </div>
 
@@ -25,15 +25,16 @@ export default function FieldArrayPage() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-3">Why it matters</h2>
         <p className="text-gray-400 leading-relaxed">
-          Dynamic lists — invoice line items, contact addresses, team members, skill tags — are one of the most common
-          patterns in real-world forms. React Hook Form&apos;s <code>useFieldArray</code> is the standard solution, but
-          integrating it with <code>useActionForm</code> has nuances: the <code>control</code> object must come from the
-          hook, arrays don&apos;t play well with <code>FormData</code> actions, and per-item error paths have a specific
-          shape.
+          Dynamic lists — invoice line items, contact addresses, team members, skill tags — are one
+          of the most common patterns in real-world forms. React Hook Form&apos;s{' '}
+          <code>useFieldArray</code> is the standard solution, but integrating it with{' '}
+          <code>useActionForm</code> has nuances: the <code>control</code> object must come from the
+          hook, arrays don&apos;t play well with <code>FormData</code> actions, and per-item error
+          paths have a specific shape.
         </p>
         <p className="text-gray-400 leading-relaxed mt-3">
-          This recipe shows a complete address list form with add, remove, per-field errors, and a <code>withZod</code>{" "}
-          server action that receives and validates the full typed array.
+          This recipe shows a complete address list form with add, remove, per-field errors, and a{' '}
+          <code>withZod</code> server action that receives and validates the full typed array.
         </p>
       </section>
 
@@ -207,32 +208,34 @@ export function AddressForm() {
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">useFieldArray requires control</code>
             <p className="text-gray-400 text-sm mt-1">
-              <code>useFieldArray</code> is from <code>react-hook-form</code> (not this library). It needs the{" "}
-              <code>control</code> object from <code>useActionForm</code>. You cannot use it with the standalone{" "}
-              <code>register</code> spread pattern.
+              <code>useFieldArray</code> is from <code>react-hook-form</code> (not this library). It
+              needs the <code>control</code> object from <code>useActionForm</code>. You cannot use
+              it with the standalone <code>register</code> spread pattern.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">field.id as key (not index)</code>
             <p className="text-gray-400 text-sm mt-1">
-              <code>useFieldArray</code> generates stable IDs for each row. Always use <code>field.id</code> as the
-              React <code>key</code>, not the array index. Index-based keys cause incorrect animations and state
-              mismatches when rows are removed.
+              <code>useFieldArray</code> generates stable IDs for each row. Always use{' '}
+              <code>field.id</code> as the React <code>key</code>, not the array index. Index-based
+              keys cause incorrect animations and state mismatches when rows are removed.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
-            <code className="text-brand-400">{`register(\`name.\${index}.field\`)`} — dot notation</code>
+            <code className="text-brand-400">
+              {'register(`name.${index}.field`)'} — dot notation
+            </code>
             <p className="text-gray-400 text-sm mt-1">
-              Use template literal dot-notation to register nested array fields. RHF will collect them into a properly
-              structured array in <code>getValues()</code> and on submit.
+              Use template literal dot-notation to register nested array fields. RHF will collect
+              them into a properly structured array in <code>getValues()</code> and on submit.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">Use withZod (JSON action), not FormData</code>
             <p className="text-gray-400 text-sm mt-1">
-              FormData doesn&apos;t natively support nested arrays. Always use <code>withZod</code> (which sends JSON)
-              for forms with <code>useFieldArray</code>. If you must use a FormData action, serialize the array manually
-              with <code>JSON.stringify</code>.
+              FormData doesn&apos;t natively support nested arrays. Always use <code>withZod</code>{' '}
+              (which sends JSON) for forms with <code>useFieldArray</code>. If you must use a
+              FormData action, serialize the array manually with <code>JSON.stringify</code>.
             </p>
           </div>
         </div>
@@ -249,8 +252,9 @@ export function AddressForm() {
                 Using the array index as <code>key</code>
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                When you remove item at index 1 from [0, 1, 2], React reuses the DOM node for the new index 1
-                (previously index 2). Input values get mixed up. Always use <code>field.id</code>.
+                When you remove item at index 1 from [0, 1, 2], React reuses the DOM node for the
+                new index 1 (previously index 2). Input values get mixed up. Always use{' '}
+                <code>field.id</code>.
               </p>
             </div>
           </li>
@@ -259,19 +263,22 @@ export function AddressForm() {
             <div>
               <p className="text-sm font-medium text-gray-200">Per-item errors path typo</p>
               <p className="text-sm text-gray-400 mt-1">
-                The errors path is <code>errors.addresses?.[index]?.street?.message</code> — note the optional chaining
-                at each level. Missing any level causes a runtime error when there are no errors.
+                The errors path is <code>errors.addresses?.[index]?.street?.message</code> — note
+                the optional chaining at each level. Missing any level causes a runtime error when
+                there are no errors.
               </p>
             </div>
           </li>
           <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
             <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
             <div>
-              <p className="text-sm font-medium text-gray-200">EMPTY_ADDRESS defined inside the component</p>
+              <p className="text-sm font-medium text-gray-200">
+                EMPTY_ADDRESS defined inside the component
+              </p>
               <p className="text-sm text-gray-400 mt-1">
-                Define the empty item template outside the component (or with <code>useCallback</code> /{" "}
-                <code>useMemo</code>). An inline object creates a new reference on every render and can cause unexpected{" "}
-                <code>append</code> behaviour.
+                Define the empty item template outside the component (or with{' '}
+                <code>useCallback</code> / <code>useMemo</code>). An inline object creates a new
+                reference on every render and can cause unexpected <code>append</code> behaviour.
               </p>
             </div>
           </li>
@@ -282,10 +289,16 @@ export function AddressForm() {
       <section className="border-t border-gray-800 pt-8">
         <h2 className="text-lg font-semibold mb-4">Related</h2>
         <div className="flex flex-wrap gap-4 text-sm">
-          <a href="/recipes/nested-fields" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/nested-fields"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Nested Fields &amp; Sub-components
           </a>
-          <a href="/recipes/signup-server-errors" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/signup-server-errors"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Sign Up with Server Errors
           </a>
           <a
@@ -296,11 +309,14 @@ export function AddressForm() {
           >
             → RHF useFieldArray docs ↗
           </a>
-          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/api-reference"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → API Reference
           </a>
         </div>
       </section>
     </div>
-  );
+  )
 }
diff --git a/apps/docs/app/recipes/file-upload/page.tsx b/apps/docs/app/recipes/file-upload/page.tsx
index d7a097b..7fb12e5 100644
--- a/apps/docs/app/recipes/file-upload/page.tsx
+++ b/apps/docs/app/recipes/file-upload/page.tsx
@@ -16,8 +16,8 @@ export default function FileUploadPage() {
         </div>
         <h1 className="text-3xl font-bold mb-3">File Upload</h1>
         <p className="text-lg text-gray-400">
-          File uploads break the default JSON action model. This recipe shows how to use a FormData action, validate
-          file type and size, show a preview, and surface a loading indicator.
+          File uploads break the default JSON action model. This recipe shows how to use a FormData
+          action, validate file type and size, show a preview, and surface a loading indicator.
         </p>
       </div>
 
@@ -25,16 +25,17 @@ export default function FileUploadPage() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-3">Why it matters</h2>
         <p className="text-gray-400 leading-relaxed">
-          File uploads are fundamentally different from text-field submissions. Files must travel over the wire as{" "}
-          <code>multipart/form-data</code>, not JSON. That means you need a <code>FormDataServerAction</code> instead of
-          the <code>withZod</code> JSON wrapper. Validation also shifts: instead of a Zod schema on an object, you
-          inspect the <code>File</code> object&apos;s <code>size</code>, <code>type</code>, and <code>name</code> on the
-          server.
+          File uploads are fundamentally different from text-field submissions. Files must travel
+          over the wire as <code>multipart/form-data</code>, not JSON. That means you need a{' '}
+          <code>FormDataServerAction</code> instead of the <code>withZod</code> JSON wrapper.
+          Validation also shifts: instead of a Zod schema on an object, you inspect the{' '}
+          <code>File</code> object&apos;s <code>size</code>, <code>type</code>, and{' '}
+          <code>name</code> on the server.
         </p>
         <p className="text-gray-400 leading-relaxed mt-3">
-          Client-side validation (type/size checks before upload) is implemented with a custom <code>schema</code> using
-          Zod&apos;s <code>.refine()</code>. This recipe covers the full pattern: action, form, preview, and a graceful
-          loading state.
+          Client-side validation (type/size checks before upload) is implemented with a custom{' '}
+          <code>schema</code> using Zod&apos;s <code>.refine()</code>. This recipe covers the full
+          pattern: action, form, preview, and a graceful loading state.
         </p>
       </section>
 
@@ -213,33 +214,36 @@ export function AvatarUploadForm() {
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">FormDataServerAction (arity 2)</code>
             <p className="text-gray-400 text-sm mt-1">
-              File uploads require the <code>(prevState, formData) =&gt; Promise</code> signature. The hook detects this
-              automatically (by checking the function&apos;s <code>length</code>) and sends the data as{" "}
-              <code>multipart/form-data</code> instead of JSON.
+              File uploads require the <code>(prevState, formData) =&gt; Promise</code> signature.
+              The hook detects this automatically (by checking the function&apos;s{' '}
+              <code>length</code>) and sends the data as <code>multipart/form-data</code> instead of
+              JSON.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">z.custom&lt;FileList&gt;().refine()</code>
             <p className="text-gray-400 text-sm mt-1">
-              Zod does not have a built-in file type. Use <code>z.custom&lt;FileList&gt;()</code> with{" "}
-              <code>.refine()</code> for client-side validation. Avoid <code>z.instanceof(File)</code> — it fails in SSR
-              environments where <code>File</code> is not defined.
+              Zod does not have a built-in file type. Use <code>z.custom&lt;FileList&gt;()</code>{' '}
+              with <code>.refine()</code> for client-side validation. Avoid{' '}
+              <code>z.instanceof(File)</code> — it fails in SSR environments where <code>File</code>{' '}
+              is not defined.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">URL.createObjectURL + cleanup</code>
             <p className="text-gray-400 text-sm mt-1">
-              Use <code>URL.createObjectURL</code> for instant image previews. Always call{" "}
-              <code>URL.revokeObjectURL</code> when the preview is no longer needed to prevent memory leaks. Store the
-              URL in a <code>useRef</code> to access it across renders.
+              Use <code>URL.createObjectURL</code> for instant image previews. Always call{' '}
+              <code>URL.revokeObjectURL</code> when the preview is no longer needed to prevent
+              memory leaks. Store the URL in a <code>useRef</code> to access it across renders.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">Next.js Server Action file size limit</code>
             <p className="text-gray-400 text-sm mt-1">
-              Next.js Server Actions have a default body size limit of 1 MB. For larger files, configure{" "}
-              <code>experimental.serverActionsBodySizeLimit</code> in <code>next.config.mjs</code>, or upload directly
-              to your storage provider from the client (signed URL pattern).
+              Next.js Server Actions have a default body size limit of 1 MB. For larger files,
+              configure <code>experimental.serverActionsBodySizeLimit</code> in{' '}
+              <code>next.config.mjs</code>, or upload directly to your storage provider from the
+              client (signed URL pattern).
             </p>
           </div>
         </div>
@@ -256,8 +260,9 @@ export function AvatarUploadForm() {
                 Using <code>withZod</code> for file uploads
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                <code>withZod</code> serialises data as JSON. Files cannot be serialised to JSON — you will receive an
-                empty object. Always use the raw FormData action signature for file uploads.
+                <code>withZod</code> serialises data as JSON. Files cannot be serialised to JSON —
+                you will receive an empty object. Always use the raw FormData action signature for
+                file uploads.
               </p>
             </div>
           </li>
@@ -268,9 +273,9 @@ export function AvatarUploadForm() {
                 Using <code>setValue</code> for file inputs
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                Browser security prevents programmatically setting file input values. Use <code>register</code> normally
-                and listen to <code>onChange</code> for the preview logic. Do not try to control the file input&apos;s
-                value via <code>setValue</code>.
+                Browser security prevents programmatically setting file input values. Use{' '}
+                <code>register</code> normally and listen to <code>onChange</code> for the preview
+                logic. Do not try to control the file input&apos;s value via <code>setValue</code>.
               </p>
             </div>
           </li>
@@ -279,9 +284,9 @@ export function AvatarUploadForm() {
             <div>
               <p className="text-sm font-medium text-gray-200">Forgetting to revoke object URLs</p>
               <p className="text-sm text-gray-400 mt-1">
-                Every <code>URL.createObjectURL</code> call holds a reference to the file in memory. Revoke it in{" "}
-                <code>onSuccess</code> or in a <code>useEffect</code> cleanup to avoid memory leaks in long-running
-                sessions.
+                Every <code>URL.createObjectURL</code> call holds a reference to the file in memory.
+                Revoke it in <code>onSuccess</code> or in a <code>useEffect</code> cleanup to avoid
+                memory leaks in long-running sessions.
               </p>
             </div>
           </li>
@@ -292,17 +297,26 @@ export function AvatarUploadForm() {
       <section className="border-t border-gray-800 pt-8">
         <h2 className="text-lg font-semibold mb-4">Related</h2>
         <div className="flex flex-wrap gap-4 text-sm">
-          <a href="/recipes/signup-server-errors" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/signup-server-errors"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Sign Up with Server Errors
           </a>
-          <a href="/recipes/custom-error-mapper" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/custom-error-mapper"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Custom Error Mapper
           </a>
-          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/api-reference"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → API Reference
           </a>
         </div>
       </section>
     </div>
-  );
+  )
 }
diff --git a/apps/docs/app/recipes/login-form/page.tsx b/apps/docs/app/recipes/login-form/page.tsx
index 2d6daeb..8c1ea1a 100644
--- a/apps/docs/app/recipes/login-form/page.tsx
+++ b/apps/docs/app/recipes/login-form/page.tsx
@@ -18,8 +18,8 @@ export default function LoginFormRecipePage() {
         </div>
         <h1 className="text-3xl font-bold mb-3">Login Form</h1>
         <p className="text-lg text-gray-400">
-          The foundation pattern. Learn how <code>withZod</code>, <code>useActionForm</code>, and error display all fit
-          together before moving to more complex recipes.
+          The foundation pattern. Learn how <code>withZod</code>, <code>useActionForm</code>, and
+          error display all fit together before moving to more complex recipes.
         </p>
         <a
           href="/examples/login"
@@ -33,15 +33,16 @@ export default function LoginFormRecipePage() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-3">Why it matters</h2>
         <p className="text-gray-400 leading-relaxed">
-          The login form is the first form every developer builds with this library. It establishes the core mental
-          model: a typed server action wrapped with <code>withZod</code>, a client component calling{" "}
-          <code>useActionForm</code>, and a clean pattern for displaying both client-side validation errors and
-          server-side errors on the same fields.
+          The login form is the first form every developer builds with this library. It establishes
+          the core mental model: a typed server action wrapped with <code>withZod</code>, a client
+          component calling <code>useActionForm</code>, and a clean pattern for displaying both
+          client-side validation errors and server-side errors on the same fields.
         </p>
         <p className="text-gray-400 leading-relaxed mt-3">
-          Getting this right means understanding the difference between <code>isSubmitting</code> and{" "}
-          <code>isPending</code>, knowing that <code>withZod</code> auto-attaches the schema for client-side inference,
-          and handling the two typical success flows — redirect or in-place success state.
+          Getting this right means understanding the difference between <code>isSubmitting</code>{' '}
+          and <code>isPending</code>, knowing that <code>withZod</code> auto-attaches the schema for
+          client-side inference, and handling the two typical success flows — redirect or in-place
+          success state.
         </p>
       </section>
 
@@ -124,10 +125,10 @@ export function LoginForm() {
 
         <div className="bg-blue-500/5 border border-blue-500/20 rounded-lg p-4 text-sm text-gray-400">
           <span className="text-blue-400 font-medium">Next.js redirect variant: </span>
-          call <code>redirect(&apos;/dashboard&apos;)</code> from <code>next/navigation</code> inside{" "}
-          <code>withZod</code>. The hook treats the thrown redirect as a successful submission —{" "}
-          <code>isSubmitSuccessful</code> will be <code>true</code>, but the page will navigate away before you can
-          render a success state.
+          call <code>redirect(&apos;/dashboard&apos;)</code> from <code>next/navigation</code>{' '}
+          inside <code>withZod</code>. The hook treats the thrown redirect as a successful
+          submission — <code>isSubmitSuccessful</code> will be <code>true</code>, but the page will
+          navigate away before you can render a success state.
         </div>
       </section>
 
@@ -138,33 +139,36 @@ export function LoginForm() {
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">withZod(schema, handler)</code>
             <p className="text-gray-400 text-sm mt-1">
-              Wraps the server action and attaches the Zod schema as <code>action.__schema</code>.{" "}
-              <code>useActionForm</code> reads it automatically for client-side validation. On validation failure,
-              returns <code>{`{ errors: { field: string[] } }`}</code> without ever calling the handler.
+              Wraps the server action and attaches the Zod schema as <code>action.__schema</code>.{' '}
+              <code>useActionForm</code> reads it automatically for client-side validation. On
+              validation failure, returns <code>{'{ errors: { field: string[] } }'}</code> without
+              ever calling the handler.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">isPending vs isSubmitting</code>
             <p className="text-gray-400 text-sm mt-1">
-              <code>isPending</code> reflects React&apos;s <code>useTransition</code> — it stays <code>true</code> for
-              the full async round-trip to the server. Use it to disable the submit button. <code>isSubmitting</code> is
-              the synchronous RHF snapshot and may not cover the full window in Next.js transitions.
+              <code>isPending</code> reflects React&apos;s <code>useTransition</code> — it stays{' '}
+              <code>true</code> for the full async round-trip to the server. Use it to disable the
+              submit button. <code>isSubmitting</code> is the synchronous RHF snapshot and may not
+              cover the full window in Next.js transitions.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">handleSubmit()</code>
             <p className="text-gray-400 text-sm mt-1">
-              Called with no arguments to get the submit handler: <code>{"<form onSubmit={handleSubmit()}>"}</code>.
-              Optionally pass an <code>onValid</code> callback that runs with typed data before the action is called:{" "}
-              <code>{"handleSubmit((data) => console.log(data))"}</code>.
+              Called with no arguments to get the submit handler:{' '}
+              <code>{'<form onSubmit={handleSubmit()}>'}</code>. Optionally pass an{' '}
+              <code>onValid</code> callback that runs with typed data before the action is called:{' '}
+              <code>{'handleSubmit((data) => console.log(data))'}</code>.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">defaultValues</code>
             <p className="text-gray-400 text-sm mt-1">
-              Always provide <code>defaultValues</code>. Without them, RHF initialises fields as <code>undefined</code>,
-              which causes React&apos;s uncontrolled-to-controlled warning when the user starts typing, and breaks
-              dirty-field tracking.
+              Always provide <code>defaultValues</code>. Without them, RHF initialises fields as{' '}
+              <code>undefined</code>, which causes React&apos;s uncontrolled-to-controlled warning
+              when the user starts typing, and breaks dirty-field tracking.
             </p>
           </div>
         </div>
@@ -181,8 +185,9 @@ export function LoginForm() {
                 Using <code>isSubmitting</code> to disable the button
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                Use <code>isPending</code> instead. In Next.js the action runs inside a transition, and{" "}
-                <code>isSubmitting</code> may revert to <code>false</code> before the server response arrives.
+                Use <code>isPending</code> instead. In Next.js the action runs inside a transition,
+                and <code>isSubmitting</code> may revert to <code>false</code> before the server
+                response arrives.
               </p>
             </div>
           </li>
@@ -193,8 +198,8 @@ export function LoginForm() {
                 Calling <code>redirect()</code> and also returning <code>success: true</code>
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                <code>redirect()</code> throws internally — the return statement is unreachable. Choose one: either
-                redirect or return a result. Doing both is dead code.
+                <code>redirect()</code> throws internally — the return statement is unreachable.
+                Choose one: either redirect or return a result. Doing both is dead code.
               </p>
             </div>
           </li>
@@ -202,11 +207,11 @@ export function LoginForm() {
             <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
             <div>
               <p className="text-sm font-medium text-gray-200">
-                Returning errors outside the <code>{`{ errors: { field: string[] } }`}</code> shape
+                Returning errors outside the <code>{'{ errors: { field: string[] } }'}</code> shape
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                The default <code>errorMapper</code> only recognises that exact shape. If your action returns a
-                different format, use a custom <code>errorMapper</code> — see{" "}
+                The default <code>errorMapper</code> only recognises that exact shape. If your
+                action returns a different format, use a custom <code>errorMapper</code> — see{' '}
                 <a href="/recipes/custom-error-mapper" className="text-brand-400 hover:underline">
                   Recipe #11
                 </a>
@@ -221,20 +226,32 @@ export function LoginForm() {
       <section className="border-t border-gray-800 pt-8">
         <h2 className="text-lg font-semibold mb-4">Related</h2>
         <div className="flex flex-wrap gap-4 text-sm">
-          <a href="/recipes/signup-server-errors" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/signup-server-errors"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Sign Up with Server Errors
           </a>
-          <a href="/recipes/reset-after-success" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/reset-after-success"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Reset After Success
           </a>
-          <a href="/examples/login" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/examples/login"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Live Example
           </a>
-          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/api-reference"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → API Reference
           </a>
         </div>
       </section>
     </div>
-  );
+  )
 }
diff --git a/apps/docs/app/recipes/modal-form/page.tsx b/apps/docs/app/recipes/modal-form/page.tsx
index f800245..d1c2bf4 100644
--- a/apps/docs/app/recipes/modal-form/page.tsx
+++ b/apps/docs/app/recipes/modal-form/page.tsx
@@ -16,8 +16,9 @@ export default function ModalFormPage() {
         </div>
         <h1 className="text-3xl font-bold mb-3">Modal / Dialog Form</h1>
         <p className="text-lg text-gray-400">
-          Forms inside modals have a different lifecycle — they must reset when opened, close on success, and handle
-          focus correctly. This recipe covers the canonical pattern and Shadcn/ui Dialog integration.
+          Forms inside modals have a different lifecycle — they must reset when opened, close on
+          success, and handle focus correctly. This recipe covers the canonical pattern and
+          Shadcn/ui Dialog integration.
         </p>
       </div>
 
@@ -25,16 +26,17 @@ export default function ModalFormPage() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-3">Why it matters</h2>
         <p className="text-gray-400 leading-relaxed">
-          A form inside a modal behaves differently from a page-level form. If the modal does not unmount when closed,
-          the form keeps its state — including errors from the last submission. When the user opens it again, they see
-          stale data. When they close it after a success, they may briefly see an empty form before the animation
-          completes.
+          A form inside a modal behaves differently from a page-level form. If the modal does not
+          unmount when closed, the form keeps its state — including errors from the last submission.
+          When the user opens it again, they see stale data. When they close it after a success,
+          they may briefly see an empty form before the animation completes.
         </p>
         <p className="text-gray-400 leading-relaxed mt-3">
-          This recipe solves these issues with two patterns: the{" "}
-          <strong className="text-gray-200">useEffect reset</strong> pattern (for modals that stay mounted) and the{" "}
-          <strong className="text-gray-200">key remount</strong> pattern (the nuclear option that guarantees a fresh
-          form). It also shows Shadcn/ui <code>Dialog</code> integration.
+          This recipe solves these issues with two patterns: the{' '}
+          <strong className="text-gray-200">useEffect reset</strong> pattern (for modals that stay
+          mounted) and the <strong className="text-gray-200">key remount</strong> pattern (the
+          nuclear option that guarantees a fresh form). It also shows Shadcn/ui <code>Dialog</code>{' '}
+          integration.
         </p>
       </section>
 
@@ -42,8 +44,8 @@ export default function ModalFormPage() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-2">Pattern 1 — useEffect reset (stays mounted)</h2>
         <p className="text-gray-400 text-sm mb-5">
-          Best for modals that are conditionally rendered but not unmounted on close (e.g. animated with CSS opacity).
-          Reset the form when the modal opens and close it on success.
+          Best for modals that are conditionally rendered but not unmounted on close (e.g. animated
+          with CSS opacity). Reset the form when the modal opens and close it on success.
         </p>
 
         <div className="mb-5">
@@ -157,9 +159,9 @@ export function CreateItemModal({ isOpen, onClose }: CreateItemModalProps) {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-2">Pattern 2 — key remount (unmount on close)</h2>
         <p className="text-gray-400 text-sm mb-5">
-          The simplest approach: unmount and remount the form component on every open by passing a <code>key</code> that
-          changes. React destroys and recreates the component, giving you a guaranteed fresh state. Best for modals
-          where no CSS animation is needed.
+          The simplest approach: unmount and remount the form component on every open by passing a{' '}
+          <code>key</code> that changes. React destroys and recreates the component, giving you a
+          guaranteed fresh state. Best for modals where no CSS animation is needed.
         </p>
 
         <div className="mb-5">
@@ -202,8 +204,9 @@ export function ItemList() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-2">Shadcn/ui Dialog integration</h2>
         <p className="text-gray-400 text-sm mb-5">
-          Shadcn&apos;s <code>Dialog</code> keeps content mounted by default. Use the <code>useEffect</code> reset
-          pattern and wire <code>onOpenChange</code> to close the modal.
+          Shadcn&apos;s <code>Dialog</code> keeps content mounted by default. Use the{' '}
+          <code>useEffect</code> reset pattern and wire <code>onOpenChange</code> to close the
+          modal.
         </p>
 
         <div className="mb-5">
@@ -291,22 +294,24 @@ export function CreateItemDialog({ open, onOpenChange }: CreateItemDialogProps)
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">reset() in useEffect on open</code>
             <p className="text-gray-400 text-sm mt-1">
-              When the modal opens, reset the form to clear any state from the previous session. This is essential for
-              modals that stay mounted between opens (e.g. animated with CSS).
+              When the modal opens, reset the form to clear any state from the previous session.
+              This is essential for modals that stay mounted between opens (e.g. animated with CSS).
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">setTimeout before reset on close</code>
             <p className="text-gray-400 text-sm mt-1">
-              If you call <code>reset()</code> synchronously in <code>onSuccess</code> before closing the modal, the
-              user briefly sees an empty form during the close animation. A small delay prevents the flash.
+              If you call <code>reset()</code> synchronously in <code>onSuccess</code> before
+              closing the modal, the user briefly sees an empty form during the close animation. A
+              small delay prevents the flash.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">autoFocus on first field</code>
             <p className="text-gray-400 text-sm mt-1">
-              Always add <code>autoFocus</code> to the first input in the modal for accessibility. Screen reader users
-              and keyboard users expect focus to move to the dialog content when it opens.
+              Always add <code>autoFocus</code> to the first input in the modal for accessibility.
+              Screen reader users and keyboard users expect focus to move to the dialog content when
+              it opens.
             </p>
           </div>
         </div>
@@ -319,11 +324,14 @@ export function CreateItemDialog({ open, onOpenChange }: CreateItemDialogProps)
           <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
             <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
             <div>
-              <p className="text-sm font-medium text-gray-200">Hiding the modal with CSS instead of unmounting</p>
+              <p className="text-sm font-medium text-gray-200">
+                Hiding the modal with CSS instead of unmounting
+              </p>
               <p className="text-sm text-gray-400 mt-1">
-                If you use <code>display: none</code> or <code>visibility: hidden</code> to hide the modal, the form
-                component stays mounted and retains all its state. The user will see stale errors and values on the next
-                open. Always pair this approach with an explicit <code>useEffect</code> reset.
+                If you use <code>display: none</code> or <code>visibility: hidden</code> to hide the
+                modal, the form component stays mounted and retains all its state. The user will see
+                stale errors and values on the next open. Always pair this approach with an explicit{' '}
+                <code>useEffect</code> reset.
               </p>
             </div>
           </li>
@@ -334,9 +342,9 @@ export function CreateItemDialog({ open, onOpenChange }: CreateItemDialogProps)
                 Using <code>isSubmitSuccessful</code> to close the modal
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                <code>isSubmitSuccessful</code> does not give you access to the action result. Prefer{" "}
-                <code>onSuccess</code>, which receives the full typed result and is a cleaner place to trigger{" "}
-                <code>onClose()</code>.
+                <code>isSubmitSuccessful</code> does not give you access to the action result.
+                Prefer <code>onSuccess</code>, which receives the full typed result and is a cleaner
+                place to trigger <code>onClose()</code>.
               </p>
             </div>
           </li>
@@ -347,17 +355,26 @@ export function CreateItemDialog({ open, onOpenChange }: CreateItemDialogProps)
       <section className="border-t border-gray-800 pt-8">
         <h2 className="text-lg font-semibold mb-4">Related</h2>
         <div className="flex flex-wrap gap-4 text-sm">
-          <a href="/recipes/reset-after-success" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/reset-after-success"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Reset After Success
           </a>
-          <a href="/recipes/edit-server-data" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/edit-server-data"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Edit Form with Server Data
           </a>
-          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/api-reference"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → API Reference
           </a>
         </div>
       </section>
     </div>
-  );
+  )
 }
diff --git a/apps/docs/app/recipes/multi-step-wizard/page.tsx b/apps/docs/app/recipes/multi-step-wizard/page.tsx
index 5f2bc31..796f7fa 100644
--- a/apps/docs/app/recipes/multi-step-wizard/page.tsx
+++ b/apps/docs/app/recipes/multi-step-wizard/page.tsx
@@ -17,8 +17,8 @@ export default function MultiStepWizardPage() {
         </div>
         <h1 className="text-3xl font-bold mb-3">Multi-Step Wizard</h1>
         <p className="text-lg text-gray-400">
-          Per-step validation, sessionStorage-backed progress, and safe cleanup on final submit — the most complete
-          demonstration of what makes this library different.
+          Per-step validation, sessionStorage-backed progress, and safe cleanup on final submit —
+          the most complete demonstration of what makes this library different.
         </p>
         <a
           href="/examples/wizard"
@@ -32,15 +32,16 @@ export default function MultiStepWizardPage() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-3">Why it matters</h2>
         <p className="text-gray-400 leading-relaxed">
-          Multi-step wizards are notoriously painful to implement: you need to validate only the current step&apos;s
-          fields before advancing, persist progress so the user can close the tab and come back, and cleanly submit all
-          steps&apos; data in a single action at the end.
+          Multi-step wizards are notoriously painful to implement: you need to validate only the
+          current step&apos;s fields before advancing, persist progress so the user can close the
+          tab and come back, and cleanly submit all steps&apos; data in a single action at the end.
         </p>
         <p className="text-gray-400 leading-relaxed mt-3">
           <code>hookform-action</code> solves this with a single hook instance spanning all steps.
-          <code>trigger(fields)</code> validates a subset of fields without submitting. <code>persistKey</code>{" "}
-          automatically serialises form state to <code>sessionStorage</code> on every change. And{" "}
-          <code>clearPersistedData()</code> removes the draft cleanly on success. No external state manager needed.
+          <code>trigger(fields)</code> validates a subset of fields without submitting.{' '}
+          <code>persistKey</code> automatically serialises form state to <code>sessionStorage</code>{' '}
+          on every change. And <code>clearPersistedData()</code> removes the draft cleanly on
+          success. No external state manager needed.
         </p>
       </section>
 
@@ -241,33 +242,36 @@ export function OnboardingWizard() {
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">trigger(fields)</code>
             <p className="text-gray-400 text-sm mt-1">
-              Runs client-side validation on a specific subset of fields and returns <code>true</code> if all pass. Pass
-              only the fields of the current step to avoid surfacing errors from future steps prematurely. Calling{" "}
-              <code>trigger()</code> with no arguments validates everything — avoid this between steps.
+              Runs client-side validation on a specific subset of fields and returns{' '}
+              <code>true</code> if all pass. Pass only the fields of the current step to avoid
+              surfacing errors from future steps prematurely. Calling <code>trigger()</code> with no
+              arguments validates everything — avoid this between steps.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">persistKey + persistDebounce</code>
             <p className="text-gray-400 text-sm mt-1">
-              <code>persistKey</code> enables automatic <code>sessionStorage</code> persistence. The form state is saved
-              under this key on every change (debounced by <code>persistDebounce</code> ms, default 300) and restored on
-              mount. The user can close the browser and return to find their progress intact.
+              <code>persistKey</code> enables automatic <code>sessionStorage</code> persistence. The
+              form state is saved under this key on every change (debounced by{' '}
+              <code>persistDebounce</code> ms, default 300) and restored on mount. The user can
+              close the browser and return to find their progress intact.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">clearPersistedData()</code>
             <p className="text-gray-400 text-sm mt-1">
-              Manually removes the persisted state for this form&apos;s <code>persistKey</code>. Always call it in{" "}
-              <code>onSuccess</code> after wizard completion — otherwise the next user to open the form (or the current
-              user if they start again) will see the completed wizard&apos;s data pre-filled.
+              Manually removes the persisted state for this form&apos;s <code>persistKey</code>.
+              Always call it in <code>onSuccess</code> after wizard completion — otherwise the next
+              user to open the form (or the current user if they start again) will see the completed
+              wizard&apos;s data pre-filled.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">Single hook instance across all steps</code>
             <p className="text-gray-400 text-sm mt-1">
-              All fields are registered in one <code>useActionForm</code> call. The active step is controlled by plain{" "}
-              <code>useState</code>. This means the entire form state is consistent at all times, and the final submit
-              sends all fields in one action call.
+              All fields are registered in one <code>useActionForm</code> call. The active step is
+              controlled by plain <code>useState</code>. This means the entire form state is
+              consistent at all times, and the final submit sends all fields in one action call.
             </p>
           </div>
         </div>
@@ -284,8 +288,9 @@ export function OnboardingWizard() {
                 Calling <code>trigger()</code> without arguments between steps
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                This validates all fields — including ones in future steps the user has not seen yet — and shows errors
-                prematurely. Always pass the explicit list of fields for the current step.
+                This validates all fields — including ones in future steps the user has not seen yet
+                — and shows errors prematurely. Always pass the explicit list of fields for the
+                current step.
               </p>
             </div>
           </li>
@@ -296,8 +301,9 @@ export function OnboardingWizard() {
                 Using <code>isSubmitSuccessful</code> to advance between steps
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                <code>isSubmitSuccessful</code> only becomes <code>true</code> after the final action call succeeds. Use
-                it exclusively as the guard for the completion screen. Step navigation is purely local state.
+                <code>isSubmitSuccessful</code> only becomes <code>true</code> after the final
+                action call succeeds. Use it exclusively as the guard for the completion screen.
+                Step navigation is purely local state.
               </p>
             </div>
           </li>
@@ -308,20 +314,24 @@ export function OnboardingWizard() {
                 Forgetting <code>clearPersistedData()</code> after submission
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                The persistence happens automatically on every change. After success, the persisted data is not removed
-                automatically — you must call <code>clearPersistedData()</code> in <code>onSuccess</code>, or the next
-                visit to the form will restore the completed wizard.
+                The persistence happens automatically on every change. After success, the persisted
+                data is not removed automatically — you must call <code>clearPersistedData()</code>{' '}
+                in <code>onSuccess</code>, or the next visit to the form will restore the completed
+                wizard.
               </p>
             </div>
           </li>
           <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
             <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
             <div>
-              <p className="text-sm font-medium text-gray-200">The current step is not persisted by default</p>
+              <p className="text-sm font-medium text-gray-200">
+                The current step is not persisted by default
+              </p>
               <p className="text-sm text-gray-400 mt-1">
-                <code>persistKey</code> saves field values, not the step index. If the user returns after a refresh, the
-                form starts at step 0 with the field values intact. To also persist the step, store it in{" "}
-                <code>sessionStorage</code> alongside the form, or include a hidden <code>currentStep</code> field.
+                <code>persistKey</code> saves field values, not the step index. If the user returns
+                after a refresh, the form starts at step 0 with the field values intact. To also
+                persist the step, store it in <code>sessionStorage</code> alongside the form, or
+                include a hidden <code>currentStep</code> field.
               </p>
             </div>
           </li>
@@ -332,20 +342,32 @@ export function OnboardingWizard() {
       <section className="border-t border-gray-800 pt-8">
         <h2 className="text-lg font-semibold mb-4">Related</h2>
         <div className="flex flex-wrap gap-4 text-sm">
-          <a href="/recipes/reset-after-success" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/reset-after-success"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Reset After Success
           </a>
-          <a href="/recipes/signup-server-errors" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/signup-server-errors"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Sign Up with Server Errors
           </a>
-          <a href="/examples/wizard" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/examples/wizard"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Live Wizard Example
           </a>
-          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/api-reference"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → API Reference
           </a>
         </div>
       </section>
     </div>
-  );
+  )
 }
diff --git a/apps/docs/app/recipes/nested-fields/page.tsx b/apps/docs/app/recipes/nested-fields/page.tsx
index fea46a1..262312e 100644
--- a/apps/docs/app/recipes/nested-fields/page.tsx
+++ b/apps/docs/app/recipes/nested-fields/page.tsx
@@ -16,8 +16,9 @@ export default function NestedFieldsPage() {
         </div>
         <h1 className="text-3xl font-bold mb-3">Nested Fields &amp; Sub-components</h1>
         <p className="text-lg text-gray-400">
-          Compose large forms from smaller, focused components using <code>useFormContext</code> — without passing{" "}
-          <code>register</code>, <code>errors</code>, or <code>control</code> as props through every level.
+          Compose large forms from smaller, focused components using <code>useFormContext</code> —
+          without passing <code>register</code>, <code>errors</code>, or <code>control</code> as
+          props through every level.
         </p>
       </div>
 
@@ -25,15 +26,16 @@ export default function NestedFieldsPage() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-3">Why it matters</h2>
         <p className="text-gray-400 leading-relaxed">
-          Large forms — checkout, onboarding, profile settings — are easier to maintain when split into focused
-          sub-components. But React Hook Form&apos;s <code>register</code>, <code>control</code>, and{" "}
-          <code>formState</code> normally need to be prop-drilled down the tree, which creates tight coupling and
-          verbose component signatures.
+          Large forms — checkout, onboarding, profile settings — are easier to maintain when split
+          into focused sub-components. But React Hook Form&apos;s <code>register</code>,{' '}
+          <code>control</code>, and <code>formState</code> normally need to be prop-drilled down the
+          tree, which creates tight coupling and verbose component signatures.
         </p>
         <p className="text-gray-400 leading-relaxed mt-3">
-          The <code>{"<Form>"}</code> component from <code>hookform-action</code> wraps its children in React Hook
-          Form&apos;s <code>FormProvider</code> automatically. Any component inside the tree can call{" "}
-          <code>useFormContext()</code> to access the full RHF API without any prop passing.
+          The <code>{'<Form>'}</code> component from <code>hookform-action</code> wraps its children
+          in React Hook Form&apos;s <code>FormProvider</code> automatically. Any component inside
+          the tree can call <code>useFormContext()</code> to access the full RHF API without any
+          prop passing.
         </p>
       </section>
 
@@ -235,33 +237,37 @@ export function ShippingSection() {
         <h2 className="text-xl font-bold mb-4">Key Concepts</h2>
         <div className="space-y-3">
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
-            <code className="text-brand-400">{`<Form form={form}>`} — automatic FormProvider</code>
+            <code className="text-brand-400">{'<Form form={form}>'} — automatic FormProvider</code>
             <p className="text-gray-400 text-sm mt-1">
-              The <code>{"<Form>"}</code> component from <code>hookform-action</code> wraps children in RHF&apos;s{" "}
-              <code>FormProvider</code> automatically. You do not need to add <code>FormProvider</code> yourself. All
-              sub-components in the tree can call <code>useFormContext()</code>.
+              The <code>{'<Form>'}</code> component from <code>hookform-action</code> wraps children
+              in RHF&apos;s <code>FormProvider</code> automatically. You do not need to add{' '}
+              <code>FormProvider</code> yourself. All sub-components in the tree can call{' '}
+              <code>useFormContext()</code>.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">useFormContext&lt;TFieldValues&gt;()</code>
             <p className="text-gray-400 text-sm mt-1">
-              Pass the form&apos;s type parameter to get typed access to <code>register</code>, <code>errors</code>, and{" "}
-              <code>control</code>. Without the generic, you get <code>FieldValues</code> (essentially <code>any</code>
+              Pass the form&apos;s type parameter to get typed access to <code>register</code>,{' '}
+              <code>errors</code>, and <code>control</code>. Without the generic, you get{' '}
+              <code>FieldValues</code> (essentially <code>any</code>
               ).
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">Dot-notation for nested paths</code>
             <p className="text-gray-400 text-sm mt-1">
-              Register deeply nested fields with dot notation: <code>register(&apos;customer.name&apos;)</code>. RHF
-              will collect these into a properly structured object. The Zod schema&apos;s shape must match exactly.
+              Register deeply nested fields with dot notation:{' '}
+              <code>register(&apos;customer.name&apos;)</code>. RHF will collect these into a
+              properly structured object. The Zod schema&apos;s shape must match exactly.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">control in sub-components</code>
             <p className="text-gray-400 text-sm mt-1">
-              <code>control</code> is needed for <code>Controller</code> and <code>useFieldArray</code> inside
-              sub-components. Get it from <code>useFormContext()</code> — not passed as a prop from the parent.
+              <code>control</code> is needed for <code>Controller</code> and{' '}
+              <code>useFieldArray</code> inside sub-components. Get it from{' '}
+              <code>useFormContext()</code> — not passed as a prop from the parent.
             </p>
           </div>
         </div>
@@ -278,9 +284,9 @@ export function ShippingSection() {
                 Double-wrapping with <code>FormProvider</code>
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                <code>{"<Form>"}</code> already includes a <code>FormProvider</code>. Adding another one around it
-                creates nested contexts and causes <code>useFormContext()</code> to read from the innermost (empty)
-                provider.
+                <code>{'<Form>'}</code> already includes a <code>FormProvider</code>. Adding another
+                one around it creates nested contexts and causes <code>useFormContext()</code> to
+                read from the innermost (empty) provider.
               </p>
             </div>
           </li>
@@ -288,23 +294,27 @@ export function ShippingSection() {
             <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
             <div>
               <p className="text-sm font-medium text-gray-200">
-                Sub-components using <code>useFormContext</code> outside <code>{"<Form>"}</code>
+                Sub-components using <code>useFormContext</code> outside <code>{'<Form>'}</code>
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                If a sub-component is rendered outside the <code>{"<Form>"}</code> tree (e.g. in a portal, a story, or a
-                test), <code>useFormContext()</code> will return <code>undefined</code> and throw. Wrap test cases in a
-                mock <code>FormProvider</code>.
+                If a sub-component is rendered outside the <code>{'<Form>'}</code> tree (e.g. in a
+                portal, a story, or a test), <code>useFormContext()</code> will return{' '}
+                <code>undefined</code> and throw. Wrap test cases in a mock{' '}
+                <code>FormProvider</code>.
               </p>
             </div>
           </li>
           <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
             <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
             <div>
-              <p className="text-sm font-medium text-gray-200">Mismatched dot-notation path and schema shape</p>
+              <p className="text-sm font-medium text-gray-200">
+                Mismatched dot-notation path and schema shape
+              </p>
               <p className="text-sm text-gray-400 mt-1">
-                If you register <code>customer.name</code> but the Zod schema expects <code>customerName</code> (flat),
-                the field will not validate correctly and the error path will not match. Keep the schema and the{" "}
-                <code>register</code> paths in sync.
+                If you register <code>customer.name</code> but the Zod schema expects{' '}
+                <code>customerName</code> (flat), the field will not validate correctly and the
+                error path will not match. Keep the schema and the <code>register</code> paths in
+                sync.
               </p>
             </div>
           </li>
@@ -315,10 +325,16 @@ export function ShippingSection() {
       <section className="border-t border-gray-800 pt-8">
         <h2 className="text-lg font-semibold mb-4">Related</h2>
         <div className="flex flex-wrap gap-4 text-sm">
-          <a href="/recipes/field-array" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/field-array"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Dynamic Fields with useFieldArray
           </a>
-          <a href="/recipes/multi-step-wizard" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/multi-step-wizard"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Multi-Step Wizard
           </a>
           <a
@@ -329,11 +345,14 @@ export function ShippingSection() {
           >
             → RHF useFormContext docs ↗
           </a>
-          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/api-reference"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → API Reference
           </a>
         </div>
       </section>
     </div>
-  );
+  )
 }
diff --git a/apps/docs/app/recipes/optimistic-ui/page.tsx b/apps/docs/app/recipes/optimistic-ui/page.tsx
index 8b138a9..2057d2c 100644
--- a/apps/docs/app/recipes/optimistic-ui/page.tsx
+++ b/apps/docs/app/recipes/optimistic-ui/page.tsx
@@ -17,8 +17,8 @@ export default function OptimisticUIPage() {
         </div>
         <h1 className="text-3xl font-bold mb-3">Optimistic UI Updates</h1>
         <p className="text-lg text-gray-400">
-          Show the result of a submission instantly — before the server responds — and roll back automatically if
-          something goes wrong.
+          Show the result of a submission instantly — before the server responds — and roll back
+          automatically if something goes wrong.
         </p>
         <a
           href="/examples/optimistic"
@@ -32,15 +32,15 @@ export default function OptimisticUIPage() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-3">Why it matters</h2>
         <p className="text-gray-400 leading-relaxed">
-          Optimistic UI is the difference between a form that feels fast and one that feels slow. Instead of waiting
-          500ms for the server to respond before updating the list, you project the expected result immediately and
-          confirm (or roll back) once the server replies.
+          Optimistic UI is the difference between a form that feels fast and one that feels slow.
+          Instead of waiting 500ms for the server to respond before updating the list, you project
+          the expected result immediately and confirm (or roll back) once the server replies.
         </p>
         <p className="text-gray-400 leading-relaxed mt-3">
-          <code>hookform-action</code> implements this via React&apos;s <code>useOptimistic</code> (React 19) with a
-          fallback for React 18. You provide an <code>optimisticData</code> reducer that produces the projected state
-          from the current data and the form values. The hook handles the transition, confirmation, and rollback
-          automatically.
+          <code>hookform-action</code> implements this via React&apos;s <code>useOptimistic</code>{' '}
+          (React 19) with a fallback for React 18. You provide an <code>optimisticData</code>{' '}
+          reducer that produces the projected state from the current data and the form values. The
+          hook handles the transition, confirmation, and rollback automatically.
         </p>
       </section>
 
@@ -186,32 +186,34 @@ export function TodoForm() {
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">optimisticData (reducer)</code>
             <p className="text-gray-400 text-sm mt-1">
-              A pure function <code>(currentData, formValues) =&gt; newData</code> that computes the projected state. It
-              runs synchronously on submit — before the server responds. Keep it fast and side-effect-free.
+              A pure function <code>(currentData, formValues) =&gt; newData</code> that computes the
+              projected state. It runs synchronously on submit — before the server responds. Keep it
+              fast and side-effect-free.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">optimistic.data vs actionResult</code>
             <p className="text-gray-400 text-sm mt-1">
-              <code>optimistic.data</code> is the projected state (may contain temporary items with fake IDs).{" "}
-              <code>actionResult</code> is the confirmed state returned by the server. Use the pattern shown above:
-              prefer <code>optimistic.data</code> while <code>optimistic.isPending</code> is true, then switch to{" "}
-              <code>actionResult</code>.
+              <code>optimistic.data</code> is the projected state (may contain temporary items with
+              fake IDs). <code>actionResult</code> is the confirmed state returned by the server.
+              Use the pattern shown above: prefer <code>optimistic.data</code> while{' '}
+              <code>optimistic.isPending</code> is true, then switch to <code>actionResult</code>.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">Automatic rollback on error</code>
             <p className="text-gray-400 text-sm mt-1">
-              When the action throws, the hook automatically reverts <code>optimistic.data</code> to the last confirmed
-              state. You can also trigger a manual rollback via <code>optimistic.rollback()</code> for
-              business-logic-driven reversals.
+              When the action throws, the hook automatically reverts <code>optimistic.data</code> to
+              the last confirmed state. You can also trigger a manual rollback via{' '}
+              <code>optimistic.rollback()</code> for business-logic-driven reversals.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">React 18 / React 19 compatibility</code>
             <p className="text-gray-400 text-sm mt-1">
-              On React 19 the hook uses the native <code>useOptimistic</code> API. On React 18 it uses a local state
-              fallback. The behaviour is identical — you don&apos;t need to change any code when upgrading React.
+              On React 19 the hook uses the native <code>useOptimistic</code> API. On React 18 it
+              uses a local state fallback. The behaviour is identical — you don&apos;t need to
+              change any code when upgrading React.
             </p>
           </div>
         </div>
@@ -228,9 +230,9 @@ export function TodoForm() {
                 Rendering <code>optimistic.data</code> after the action resolves
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                After the action succeeds, <code>optimistic.data</code> still contains the projected state with
-                temporary IDs. Always switch to <code>actionResult</code> once <code>optimistic.isPending</code> is{" "}
-                <code>false</code>.
+                After the action succeeds, <code>optimistic.data</code> still contains the projected
+                state with temporary IDs. Always switch to <code>actionResult</code> once{' '}
+                <code>optimistic.isPending</code> is <code>false</code>.
               </p>
             </div>
           </li>
@@ -241,8 +243,9 @@ export function TodoForm() {
                 Inline object literal for <code>optimisticInitial</code>
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                Define <code>optimisticInitial</code> outside the component or use <code>useMemo</code>. An inline array
-                literal creates a new reference on every render and resets the optimistic state unexpectedly.
+                Define <code>optimisticInitial</code> outside the component or use{' '}
+                <code>useMemo</code>. An inline array literal creates a new reference on every
+                render and resets the optimistic state unexpectedly.
               </p>
             </div>
           </li>
@@ -253,8 +256,9 @@ export function TodoForm() {
                 Forgetting <code>reset()</code> in <code>onSuccess</code>
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                After a successful add, the text input stays filled. Call <code>reset()</code> in <code>onSuccess</code>{" "}
-                to clear the input so the user can type the next item immediately.
+                After a successful add, the text input stays filled. Call <code>reset()</code> in{' '}
+                <code>onSuccess</code> to clear the input so the user can type the next item
+                immediately.
               </p>
             </div>
           </li>
@@ -265,17 +269,26 @@ export function TodoForm() {
       <section className="border-t border-gray-800 pt-8">
         <h2 className="text-lg font-semibold mb-4">Related</h2>
         <div className="flex flex-wrap gap-4 text-sm">
-          <a href="/recipes/reset-after-success" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/reset-after-success"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Reset After Success
           </a>
-          <a href="/examples/optimistic" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/examples/optimistic"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Live Optimistic Example
           </a>
-          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/api-reference"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → API Reference
           </a>
         </div>
       </section>
     </div>
-  );
+  )
 }
diff --git a/apps/docs/app/recipes/page.tsx b/apps/docs/app/recipes/page.tsx
index d81f799..13e81dd 100644
--- a/apps/docs/app/recipes/page.tsx
+++ b/apps/docs/app/recipes/page.tsx
@@ -13,8 +13,9 @@ export default function RecipesPage() {
         </div>
         <h1 className="text-3xl font-bold mb-4">Recipes &amp; Common Patterns</h1>
         <p className="text-lg text-gray-400 max-w-2xl">
-          Complete, copy-paste patterns for the most common <code>hookform-action</code> use cases. Each recipe includes
-          a working server action, a typed client component, key concepts, and pitfalls to avoid.
+          Complete, copy-paste patterns for the most common <code>hookform-action</code> use cases.
+          Each recipe includes a working server action, a typed client component, key concepts, and
+          pitfalls to avoid.
         </p>
       </div>
 
@@ -37,10 +38,12 @@ export default function RecipesPage() {
             <div className="flex items-center gap-2 mb-2">
               <span className="text-xs text-gray-500 font-mono">#1</span>
             </div>
-            <h3 className="font-semibold text-white group-hover:text-brand-400 transition-colors mb-1">Login Form</h3>
+            <h3 className="font-semibold text-white group-hover:text-brand-400 transition-colors mb-1">
+              Login Form
+            </h3>
             <p className="text-sm text-gray-400">
-              The foundation pattern: <code>withZod</code> action, <code>useActionForm</code>, <code>isPending</code>,
-              and error display.
+              The foundation pattern: <code>withZod</code> action, <code>useActionForm</code>,{' '}
+              <code>isPending</code>, and error display.
             </p>
           </a>
 
@@ -70,7 +73,7 @@ export default function RecipesPage() {
               Reset After Success
             </h3>
             <p className="text-sm text-gray-400">
-              Three canonical patterns: redirect, in-place reset with <code>onSuccess</code>, and{" "}
+              Three canonical patterns: redirect, in-place reset with <code>onSuccess</code>, and{' '}
               <code>isSubmitSuccessful</code> guard.
             </p>
           </a>
@@ -102,8 +105,8 @@ export default function RecipesPage() {
               Multi-Step Wizard
             </h3>
             <p className="text-sm text-gray-400">
-              Per-step validation with <code>trigger()</code>, sessionStorage persistence with <code>persistKey</code>,
-              and safe progress clearing on submit.
+              Per-step validation with <code>trigger()</code>, sessionStorage persistence with{' '}
+              <code>persistKey</code>, and safe progress clearing on submit.
             </p>
           </a>
         </div>
@@ -117,7 +120,9 @@ export default function RecipesPage() {
             Tier 2 · Common
           </span>
         </div>
-        <p className="text-gray-500 text-sm mb-6">Patterns you will reach for often as your app grows.</p>
+        <p className="text-gray-500 text-sm mb-6">
+          Patterns you will reach for often as your app grows.
+        </p>
         <div className="grid sm:grid-cols-2 gap-4">
           <a
             href="/recipes/optimistic-ui"
@@ -127,9 +132,12 @@ export default function RecipesPage() {
               <span className="text-xs text-gray-500 font-mono">#6</span>
               <span className="text-xs text-cyan-400 font-medium">⚡ Advanced feature</span>
             </div>
-            <h3 className="font-semibold text-white group-hover:text-cyan-400 transition-colors mb-1">Optimistic UI</h3>
+            <h3 className="font-semibold text-white group-hover:text-cyan-400 transition-colors mb-1">
+              Optimistic UI
+            </h3>
             <p className="text-sm text-gray-400">
-              Instant feedback with <code>optimisticData</code>, temporary IDs, and automatic rollback on error.
+              Instant feedback with <code>optimisticData</code>, temporary IDs, and automatic
+              rollback on error.
             </p>
           </a>
 
@@ -144,7 +152,8 @@ export default function RecipesPage() {
               Modal / Dialog Form
             </h3>
             <p className="text-sm text-gray-400">
-              Form lifecycle inside a modal: reset on open, close on success, and Shadcn/ui Dialog integration.
+              Form lifecycle inside a modal: reset on open, close on success, and Shadcn/ui Dialog
+              integration.
             </p>
           </a>
 
@@ -159,8 +168,8 @@ export default function RecipesPage() {
               Dynamic Fields with useFieldArray
             </h3>
             <p className="text-sm text-gray-400">
-              Add and remove array items, validate each row, and submit a typed array to the server action using{" "}
-              <code>useFieldArray</code> from React Hook Form.
+              Add and remove array items, validate each row, and submit a typed array to the server
+              action using <code>useFieldArray</code> from React Hook Form.
             </p>
           </a>
         </div>
@@ -174,7 +183,9 @@ export default function RecipesPage() {
             Tier 3 · Specialized
           </span>
         </div>
-        <p className="text-gray-500 text-sm mb-6">Edge cases, ecosystem integrations, and power-user patterns.</p>
+        <p className="text-gray-500 text-sm mb-6">
+          Edge cases, ecosystem integrations, and power-user patterns.
+        </p>
         <div className="grid sm:grid-cols-2 gap-4">
           <a
             href="/recipes/file-upload"
@@ -183,10 +194,12 @@ export default function RecipesPage() {
             <div className="flex items-center gap-2 mb-2">
               <span className="text-xs text-gray-500 font-mono">#9</span>
             </div>
-            <h3 className="font-semibold text-white group-hover:text-brand-400 transition-colors mb-1">File Upload</h3>
+            <h3 className="font-semibold text-white group-hover:text-brand-400 transition-colors mb-1">
+              File Upload
+            </h3>
             <p className="text-sm text-gray-400">
-              FormData actions, file type and size validation, image preview, and <code>isPending</code> progress
-              indicator.
+              FormData actions, file type and size validation, image preview, and{' '}
+              <code>isPending</code> progress indicator.
             </p>
           </a>
 
@@ -201,7 +214,8 @@ export default function RecipesPage() {
               Nested Fields &amp; Sub-components
             </h3>
             <p className="text-sm text-gray-400">
-              Compose large forms from smaller components using <code>useFormContext</code> without prop drilling.
+              Compose large forms from smaller components using <code>useFormContext</code> without
+              prop drilling.
             </p>
           </a>
 
@@ -216,7 +230,8 @@ export default function RecipesPage() {
               Custom Error Mapper
             </h3>
             <p className="text-sm text-gray-400">
-              Translate non-standard API error shapes (Laravel, Rails, REST) to React Hook Form field errors.
+              Translate non-standard API error shapes (Laravel, Rails, REST) to React Hook Form
+              field errors.
             </p>
           </a>
 
@@ -232,8 +247,8 @@ export default function RecipesPage() {
               Standalone — Vite, Remix &amp; APIs
             </h3>
             <p className="text-sm text-gray-400">
-              Use <code>hookform-action-standalone</code> with <code>fetch</code> or <code>axios</code> outside of
-              Next.js.
+              Use <code>hookform-action-standalone</code> with <code>fetch</code> or{' '}
+              <code>axios</code> outside of Next.js.
             </p>
           </a>
         </div>
@@ -241,13 +256,16 @@ export default function RecipesPage() {
 
       <div className="border-t border-gray-800 pt-8 text-sm text-gray-500">
         <p>
-          All recipes use real, working code with full TypeScript types. Each pattern maps directly to a capability of
-          the <code>hookform-action</code> API.{" "}
-          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+          All recipes use real, working code with full TypeScript types. Each pattern maps directly
+          to a capability of the <code>hookform-action</code> API.{' '}
+          <a
+            href="/api-reference"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             Read the API reference →
           </a>
         </p>
       </div>
     </div>
-  );
+  )
 }
diff --git a/apps/docs/app/recipes/reset-after-success/page.tsx b/apps/docs/app/recipes/reset-after-success/page.tsx
index 0ff180d..4f73436 100644
--- a/apps/docs/app/recipes/reset-after-success/page.tsx
+++ b/apps/docs/app/recipes/reset-after-success/page.tsx
@@ -16,8 +16,8 @@ export default function ResetAfterSuccessPage() {
         </div>
         <h1 className="text-3xl font-bold mb-3">Reset After Success</h1>
         <p className="text-lg text-gray-400">
-          Three canonical patterns for post-submission UX: redirect, in-place reset with a toast, and showing a success
-          state. Choosing the wrong one leads to subtle bugs.
+          Three canonical patterns for post-submission UX: redirect, in-place reset with a toast,
+          and showing a success state. Choosing the wrong one leads to subtle bugs.
         </p>
       </div>
 
@@ -25,14 +25,15 @@ export default function ResetAfterSuccessPage() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-3">Why it matters</h2>
         <p className="text-gray-400 leading-relaxed">
-          &quot;The form doesn&apos;t clear after I submit&quot; is one of the most common issues raised by developers
-          new to the library. The reason is that <code>isSubmitSuccessful</code> stays <code>true</code> indefinitely,
-          and <code>reset()</code> needs to be called explicitly. These are intentional RHF behaviours — but they need
-          to be wired correctly.
+          &quot;The form doesn&apos;t clear after I submit&quot; is one of the most common issues
+          raised by developers new to the library. The reason is that{' '}
+          <code>isSubmitSuccessful</code> stays <code>true</code> indefinitely, and{' '}
+          <code>reset()</code> needs to be called explicitly. These are intentional RHF behaviours —
+          but they need to be wired correctly.
         </p>
         <p className="text-gray-400 leading-relaxed mt-3">
-          There are three distinct patterns depending on your UX goal. Pick the right one and you avoid ghost states,
-          stale data, and infinite success screens.
+          There are three distinct patterns depending on your UX goal. Pick the right one and you
+          avoid ghost states, stale data, and infinite success screens.
         </p>
       </section>
 
@@ -40,8 +41,9 @@ export default function ResetAfterSuccessPage() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-2">Pattern 1 — Redirect after submit</h2>
         <p className="text-gray-400 text-sm mb-5">
-          Best for create-and-navigate flows: create a post, place an order, complete onboarding. The server calls{" "}
-          <code>redirect()</code> and the page navigates away — no client-side reset needed.
+          Best for create-and-navigate flows: create a post, place an order, complete onboarding.
+          The server calls <code>redirect()</code> and the page navigates away — no client-side
+          reset needed.
         </p>
 
         <div className="mb-5">
@@ -64,8 +66,9 @@ export const createPostAction = withZod(postSchema, async (data) => {
 
         <div className="bg-blue-500/5 border border-blue-500/20 rounded-lg p-4 text-sm text-gray-400">
           <span className="text-blue-400 font-medium">Note: </span>
-          After <code>redirect()</code> the hook sets <code>isSubmitSuccessful = true</code>, but the page navigates
-          away immediately so this state is never rendered. You do not need to handle it on the client.
+          After <code>redirect()</code> the hook sets <code>isSubmitSuccessful = true</code>, but
+          the page navigates away immediately so this state is never rendered. You do not need to
+          handle it on the client.
         </div>
       </section>
 
@@ -73,8 +76,9 @@ export const createPostAction = withZod(postSchema, async (data) => {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-2">Pattern 2 — In-place reset with onSuccess</h2>
         <p className="text-gray-400 text-sm mb-5">
-          Best for forms that stay on the same page after submission: comment boxes, subscription forms, quick-add
-          widgets. Use <code>onSuccess</code> to call <code>reset()</code> and optionally show a toast.
+          Best for forms that stay on the same page after submission: comment boxes, subscription
+          forms, quick-add widgets. Use <code>onSuccess</code> to call <code>reset()</code> and
+          optionally show a toast.
         </p>
 
         <div className="mb-5">
@@ -134,8 +138,8 @@ export function CommentForm() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-2">Pattern 3 — isSubmitSuccessful guard</h2>
         <p className="text-gray-400 text-sm mb-5">
-          Best for single-use forms where you want to replace the form with a success message: contact forms, RSVP
-          forms, one-time redemptions.
+          Best for single-use forms where you want to replace the form with a success message:
+          contact forms, RSVP forms, one-time redemptions.
         </p>
 
         <div className="mb-5">
@@ -188,9 +192,9 @@ export function ContactForm() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-2">Bonus — Clearing persistence after wizard submit</h2>
         <p className="text-gray-400 text-sm mb-5">
-          When using <code>persistKey</code>, always call <code>clearPersistedData()</code> in <code>onSuccess</code> to
-          remove the saved draft from <code>sessionStorage</code>. Otherwise the user will see stale data if they open
-          the form again.
+          When using <code>persistKey</code>, always call <code>clearPersistedData()</code> in{' '}
+          <code>onSuccess</code> to remove the saved draft from <code>sessionStorage</code>.
+          Otherwise the user will see stale data if they open the form again.
         </p>
 
         <div className="code-block text-gray-300">
@@ -212,24 +216,26 @@ export function ContactForm() {
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">reset()</code>
             <p className="text-gray-400 text-sm mt-1">
-              Resets all fields to <code>defaultValues</code>, clears all errors, and resets RHF state (
-              <code>isDirty</code>, <code>isSubmitSuccessful</code>, etc.). <code>reset(newValues)</code> additionally
-              updates the stored default values — useful after editing a record.
+              Resets all fields to <code>defaultValues</code>, clears all errors, and resets RHF
+              state (<code>isDirty</code>, <code>isSubmitSuccessful</code>, etc.).{' '}
+              <code>reset(newValues)</code> additionally updates the stored default values — useful
+              after editing a record.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">isSubmitSuccessful</code>
             <p className="text-gray-400 text-sm mt-1">
-              Becomes <code>true</code> after a successful action call (no field errors returned) and stays{" "}
-              <code>true</code> until <code>reset()</code> is called or the component unmounts. This is intentional —
-              use it as the guard for your success UI.
+              Becomes <code>true</code> after a successful action call (no field errors returned)
+              and stays <code>true</code> until <code>reset()</code> is called or the component
+              unmounts. This is intentional — use it as the guard for your success UI.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">onSuccess callback</code>
             <p className="text-gray-400 text-sm mt-1">
-              Receives the full action result and fires only when the action succeeds (no field errors). The best place
-              to call <code>reset()</code>, show a toast, or trigger a router navigation.
+              Receives the full action result and fires only when the action succeeds (no field
+              errors). The best place to call <code>reset()</code>, show a toast, or trigger a
+              router navigation.
             </p>
           </div>
         </div>
@@ -243,22 +249,25 @@ export function ContactForm() {
             <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
             <div>
               <p className="text-sm font-medium text-gray-200">
-                Calling <code>reset()</code> in a <code>useEffect</code> watching <code>isSubmitSuccessful</code>
+                Calling <code>reset()</code> in a <code>useEffect</code> watching{' '}
+                <code>isSubmitSuccessful</code>
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                This creates a double-render cycle. Prefer <code>onSuccess</code> — it fires synchronously after the
-                action resolves, before any re-render.
+                This creates a double-render cycle. Prefer <code>onSuccess</code> — it fires
+                synchronously after the action resolves, before any re-render.
               </p>
             </div>
           </li>
           <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
             <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
             <div>
-              <p className="text-sm font-medium text-gray-200">Resetting inside a modal — flash of empty form</p>
+              <p className="text-sm font-medium text-gray-200">
+                Resetting inside a modal — flash of empty form
+              </p>
               <p className="text-sm text-gray-400 mt-1">
-                If you <code>reset()</code> and then close the modal in <code>onSuccess</code>, the form briefly shows
-                empty before the modal animation completes. Prefer resetting in the <code>onClose</code> handler
-                instead, or use a <code>key</code> prop to remount.
+                If you <code>reset()</code> and then close the modal in <code>onSuccess</code>, the
+                form briefly shows empty before the modal animation completes. Prefer resetting in
+                the <code>onClose</code> handler instead, or use a <code>key</code> prop to remount.
               </p>
             </div>
           </li>
@@ -269,9 +278,9 @@ export function ContactForm() {
                 <code>reset()</code> without arguments on an edit form
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                If <code>defaultValues</code> came from the server and the user just saved new data, calling{" "}
-                <code>reset()</code> reverts to the old server data. Use <code>reset(result.data)</code> to update the
-                baseline after a successful edit.
+                If <code>defaultValues</code> came from the server and the user just saved new data,
+                calling <code>reset()</code> reverts to the old server data. Use{' '}
+                <code>reset(result.data)</code> to update the baseline after a successful edit.
               </p>
             </div>
           </li>
@@ -282,20 +291,32 @@ export function ContactForm() {
       <section className="border-t border-gray-800 pt-8">
         <h2 className="text-lg font-semibold mb-4">Related</h2>
         <div className="flex flex-wrap gap-4 text-sm">
-          <a href="/recipes/login-form" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/login-form"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Login Form
           </a>
-          <a href="/recipes/modal-form" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/modal-form"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Modal / Dialog Form
           </a>
-          <a href="/recipes/multi-step-wizard" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/multi-step-wizard"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Multi-Step Wizard
           </a>
-          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/api-reference"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → API Reference
           </a>
         </div>
       </section>
     </div>
-  );
+  )
 }
diff --git a/apps/docs/app/recipes/signup-server-errors/page.tsx b/apps/docs/app/recipes/signup-server-errors/page.tsx
index 017898a..bc33e86 100644
--- a/apps/docs/app/recipes/signup-server-errors/page.tsx
+++ b/apps/docs/app/recipes/signup-server-errors/page.tsx
@@ -16,8 +16,8 @@ export default function SignupServerErrorsPage() {
         </div>
         <h1 className="text-3xl font-bold mb-3">Sign Up with Server Validation Errors</h1>
         <p className="text-lg text-gray-400">
-          How to return business-logic errors from a server action — duplicate email, taken username, and more — and
-          have them appear on the correct fields automatically.
+          How to return business-logic errors from a server action — duplicate email, taken
+          username, and more — and have them appear on the correct fields automatically.
         </p>
       </div>
 
@@ -25,16 +25,17 @@ export default function SignupServerErrorsPage() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-3">Why it matters</h2>
         <p className="text-gray-400 leading-relaxed">
-          The login form teaches the happy path. This recipe teaches what actually happens in production: the user
-          submits valid data, but the server rejects it because the email is already registered or the username is
-          taken. These are business-logic errors that Zod&apos;s schema can&apos;t know about.
+          The login form teaches the happy path. This recipe teaches what actually happens in
+          production: the user submits valid data, but the server rejects it because the email is
+          already registered or the username is taken. These are business-logic errors that
+          Zod&apos;s schema can&apos;t know about.
         </p>
         <p className="text-gray-400 leading-relaxed mt-3">
-          <code>hookform-action</code> has a built-in contract for this: return{" "}
-          <code>{`{ errors: { field: string[] } }`}</code> from the action and the hook maps it directly to the
-          corresponding React Hook Form fields — no extra wiring needed. This recipe also shows{" "}
-          <code>setSubmitError</code> for errors set outside the action, and the <code>onError</code> callback for side
-          effects like toasts.
+          <code>hookform-action</code> has a built-in contract for this: return{' '}
+          <code>{'{ errors: { field: string[] } }'}</code> from the action and the hook maps it
+          directly to the corresponding React Hook Form fields — no extra wiring needed. This recipe
+          also shows <code>setSubmitError</code> for errors set outside the action, and the{' '}
+          <code>onError</code> callback for side effects like toasts.
         </p>
       </section>
 
@@ -182,34 +183,36 @@ setSubmitError('email', 'This email was flagged as invalid by our provider')`}</
         <h2 className="text-xl font-bold mb-4">Key Concepts</h2>
         <div className="space-y-3">
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
-            <code className="text-brand-400">{`{ errors: { field: string[] } }`}</code>
+            <code className="text-brand-400">{'{ errors: { field: string[] } }'}</code>
             <p className="text-gray-400 text-sm mt-1">
-              The default error contract. Return this shape from any action and <code>defaultErrorMapper</code>{" "}
-              automatically sets the corresponding RHF field errors. The key is the field name, the value is an array of
-              message strings (only the first message is shown by RHF by default).
+              The default error contract. Return this shape from any action and{' '}
+              <code>defaultErrorMapper</code> automatically sets the corresponding RHF field errors.
+              The key is the field name, the value is an array of message strings (only the first
+              message is shown by RHF by default).
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">formState.actionResult</code>
             <p className="text-gray-400 text-sm mt-1">
-              The raw return value of the last action call, preserved with full type safety via{" "}
-              <code>InferActionResult&lt;typeof action&gt;</code>. Use it to surface global messages or access non-error
-              data from the response.
+              The raw return value of the last action call, preserved with full type safety via{' '}
+              <code>InferActionResult&lt;typeof action&gt;</code>. Use it to surface global messages
+              or access non-error data from the response.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">setSubmitError(field, message)</code>
             <p className="text-gray-400 text-sm mt-1">
-              Programmatically sets a field error as if it came from the server. Useful for client-side checks that
-              happen outside the normal submit flow, such as async email-availability lookups on blur.
+              Programmatically sets a field error as if it came from the server. Useful for
+              client-side checks that happen outside the normal submit flow, such as async
+              email-availability lookups on blur.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">onError callback</code>
             <p className="text-gray-400 text-sm mt-1">
-              Fires when the action returns field errors <em>or</em> throws an exception. Use it for side effects —
-              toast notifications, error logging, analytics — without polluting the action or the component&apos;s
-              render logic.
+              Fires when the action returns field errors <em>or</em> throws an exception. Use it for
+              side effects — toast notifications, error logging, analytics — without polluting the
+              action or the component&apos;s render logic.
             </p>
           </div>
         </div>
@@ -222,22 +225,27 @@ setSubmitError('email', 'This email was flagged as invalid by our provider')`}</
           <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
             <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
             <div>
-              <p className="text-sm font-medium text-gray-200">Server errors don&apos;t clear when the user retypes</p>
+              <p className="text-sm font-medium text-gray-200">
+                Server errors don&apos;t clear when the user retypes
+              </p>
               <p className="text-sm text-gray-400 mt-1">
-                This is intentional RHF behaviour. A server error set via the error mapper persists until the next
-                submit (or until you call <code>clearErrors(field)</code> manually). To clear on input, use{" "}
-                <code>validationMode: &apos;onChange&apos;</code> with a client-side schema.
+                This is intentional RHF behaviour. A server error set via the error mapper persists
+                until the next submit (or until you call <code>clearErrors(field)</code> manually).
+                To clear on input, use <code>validationMode: &apos;onChange&apos;</code> with a
+                client-side schema.
               </p>
             </div>
           </li>
           <li className="flex gap-3 bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4">
             <span className="text-yellow-400 shrink-0 mt-0.5">⚠</span>
             <div>
-              <p className="text-sm font-medium text-gray-200">Distinguishing field errors from global errors</p>
+              <p className="text-sm font-medium text-gray-200">
+                Distinguishing field errors from global errors
+              </p>
               <p className="text-sm text-gray-400 mt-1">
-                The <code>errors</code> object only contains field-level errors from RHF. To display a global error
-                message (e.g. &quot;Service unavailable&quot;), read it from <code>actionResult</code> and render it
-                separately outside the field markup.
+                The <code>errors</code> object only contains field-level errors from RHF. To display
+                a global error message (e.g. &quot;Service unavailable&quot;), read it from{' '}
+                <code>actionResult</code> and render it separately outside the field markup.
               </p>
             </div>
           </li>
@@ -248,8 +256,9 @@ setSubmitError('email', 'This email was flagged as invalid by our provider')`}</
                 <code>withZod</code> already returns field errors — don&apos;t double-validate
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                If the schema fails, <code>withZod</code> short-circuits and returns <code>{`{ errors }`}</code> before
-                your handler runs. Do not call <code>schema.safeParse</code> again inside the handler.
+                If the schema fails, <code>withZod</code> short-circuits and returns{' '}
+                <code>{'{ errors }'}</code> before your handler runs. Do not call{' '}
+                <code>schema.safeParse</code> again inside the handler.
               </p>
             </div>
           </li>
@@ -260,20 +269,32 @@ setSubmitError('email', 'This email was flagged as invalid by our provider')`}</
       <section className="border-t border-gray-800 pt-8">
         <h2 className="text-lg font-semibold mb-4">Related</h2>
         <div className="flex flex-wrap gap-4 text-sm">
-          <a href="/recipes/login-form" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/login-form"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Login Form
           </a>
-          <a href="/recipes/custom-error-mapper" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/custom-error-mapper"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Custom Error Mapper
           </a>
-          <a href="/examples/validation" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/examples/validation"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Live Validation Example
           </a>
-          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/api-reference"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → API Reference
           </a>
         </div>
       </section>
     </div>
-  );
+  )
 }
diff --git a/apps/docs/app/recipes/standalone-fetch/page.tsx b/apps/docs/app/recipes/standalone-fetch/page.tsx
index afb7011..901394f 100644
--- a/apps/docs/app/recipes/standalone-fetch/page.tsx
+++ b/apps/docs/app/recipes/standalone-fetch/page.tsx
@@ -17,8 +17,9 @@ export default function StandaloneFetchPage() {
         </div>
         <h1 className="text-3xl font-bold mb-3">Standalone — Vite, Remix &amp; Custom APIs</h1>
         <p className="text-lg text-gray-400">
-          Use <code>hookform-action-standalone</code> with any async function — <code>fetch</code>, <code>axios</code>,
-          tRPC, or a custom client — in apps that don&apos;t use Next.js Server Actions.
+          Use <code>hookform-action-standalone</code> with any async function — <code>fetch</code>,{' '}
+          <code>axios</code>, tRPC, or a custom client — in apps that don&apos;t use Next.js Server
+          Actions.
         </p>
         <a
           href="/standalone"
@@ -32,14 +33,15 @@ export default function StandaloneFetchPage() {
       <section className="mb-12">
         <h2 className="text-xl font-bold mb-3">Why it matters</h2>
         <p className="text-gray-400 leading-relaxed">
-          Not every React app uses Next.js or Server Actions. Vite SPAs, Remix apps, Astro islands, and React Native
-          projects all need the same ergonomics — typed validation, automatic error mapping, optimistic UI — but with a
-          plain async function as the submit handler.
+          Not every React app uses Next.js or Server Actions. Vite SPAs, Remix apps, Astro islands,
+          and React Native projects all need the same ergonomics — typed validation, automatic error
+          mapping, optimistic UI — but with a plain async function as the submit handler.
         </p>
         <p className="text-gray-400 leading-relaxed mt-3">
-          The standalone adapter exposes exactly the same hook API. The only difference is: instead of passing a Server
-          Action as the first argument, you pass an options object with a <code>submit</code> function. Everything else
-          — <code>schema</code>, <code>optimisticData</code>, <code>persistKey</code>, <code>onSuccess</code>,{" "}
+          The standalone adapter exposes exactly the same hook API. The only difference is: instead
+          of passing a Server Action as the first argument, you pass an options object with a{' '}
+          <code>submit</code> function. Everything else — <code>schema</code>,{' '}
+          <code>optimisticData</code>, <code>persistKey</code>, <code>onSuccess</code>,{' '}
           <code>errorMapper</code> — works identically.
         </p>
       </section>
@@ -193,8 +195,12 @@ export async function loginApi(data: { email: string; password: string }) {
             <thead>
               <tr className="border-b border-gray-800">
                 <th className="text-left py-2 pr-4 text-gray-400 font-medium">Feature</th>
-                <th className="text-left py-2 pr-4 text-brand-400 font-medium">hookform-action (Next.js)</th>
-                <th className="text-left py-2 text-emerald-400 font-medium">hookform-action-standalone</th>
+                <th className="text-left py-2 pr-4 text-brand-400 font-medium">
+                  hookform-action (Next.js)
+                </th>
+                <th className="text-left py-2 text-emerald-400 font-medium">
+                  hookform-action-standalone
+                </th>
               </tr>
             </thead>
             <tbody className="text-gray-400">
@@ -206,7 +212,9 @@ export async function loginApi(data: { email: string; password: string }) {
               <tr className="border-b border-gray-800/50">
                 <td className="py-2 pr-4 font-mono text-xs">Hook signature</td>
                 <td className="py-2 pr-4 font-mono text-xs">useActionForm(action, options?)</td>
-                <td className="py-2 font-mono text-xs">useActionForm(&#123; submit, ...options &#125;)</td>
+                <td className="py-2 font-mono text-xs">
+                  useActionForm(&#123; submit, ...options &#125;)
+                </td>
               </tr>
               <tr className="border-b border-gray-800/50">
                 <td className="py-2 pr-4 font-mono text-xs">formAction</td>
@@ -245,25 +253,28 @@ export async function loginApi(data: { email: string; password: string }) {
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">submit: async (data) =&gt; TResult</code>
             <p className="text-gray-400 text-sm mt-1">
-              Any async function that receives the validated form data and returns a result. It can call{" "}
-              <code>fetch</code>, <code>axios</code>, a tRPC procedure, a GraphQL mutation, or any other async
-              operation. If it throws, the hook catches it and fires <code>onError</code>.
+              Any async function that receives the validated form data and returns a result. It can
+              call <code>fetch</code>, <code>axios</code>, a tRPC procedure, a GraphQL mutation, or
+              any other async operation. If it throws, the hook catches it and fires{' '}
+              <code>onError</code>.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">Structured errors vs thrown errors</code>
             <p className="text-gray-400 text-sm mt-1">
-              For HTTP 4xx errors, return a structured result (with <code>errors</code>) instead of throwing. This
-              allows the <code>errorMapper</code> to set field errors correctly. Only throw for unexpected errors (5xx,
-              network failures) — those trigger <code>onError</code> with an <code>Error</code> instance.
+              For HTTP 4xx errors, return a structured result (with <code>errors</code>) instead of
+              throwing. This allows the <code>errorMapper</code> to set field errors correctly. Only
+              throw for unexpected errors (5xx, network failures) — those trigger{' '}
+              <code>onError</code> with an <code>Error</code> instance.
             </p>
           </div>
           <div className="bg-gray-900 border border-gray-800 rounded-lg p-4">
             <code className="text-brand-400">withZod is not used server-side in standalone</code>
             <p className="text-gray-400 text-sm mt-1">
-              <code>withZod</code> is a wrapper for Next.js Server Actions. In standalone mode, pass the schema via the{" "}
-              <code>schema</code> option for client-side validation only. Server-side validation must be implemented
-              inside your <code>submit</code> function or API handler.
+              <code>withZod</code> is a wrapper for Next.js Server Actions. In standalone mode, pass
+              the schema via the <code>schema</code> option for client-side validation only.
+              Server-side validation must be implemented inside your <code>submit</code> function or
+              API handler.
             </p>
           </div>
         </div>
@@ -278,9 +289,9 @@ export async function loginApi(data: { email: string; password: string }) {
             <div>
               <p className="text-sm font-medium text-gray-200">Throwing on HTTP 4xx errors</p>
               <p className="text-sm text-gray-400 mt-1">
-                If your fetch wrapper throws on 4xx, the hook receives an <code>Error</code> — not a structured result.
-                The <code>errorMapper</code> won&apos;t fire for thrown errors. Return a structured object instead so
-                field errors can be set automatically.
+                If your fetch wrapper throws on 4xx, the hook receives an <code>Error</code> — not a
+                structured result. The <code>errorMapper</code> won&apos;t fire for thrown errors.
+                Return a structured object instead so field errors can be set automatically.
               </p>
             </div>
           </li>
@@ -291,9 +302,9 @@ export async function loginApi(data: { email: string; password: string }) {
                 No <code>formAction</code> in standalone
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                The standalone adapter does not expose <code>formAction</code> — there is no support for the{" "}
-                <code>{"<form action={...}>"}</code> pattern without JavaScript. Progressive enhancement requires the
-                Next.js adapter.
+                The standalone adapter does not expose <code>formAction</code> — there is no support
+                for the <code>{'<form action={...}>'}</code> pattern without JavaScript. Progressive
+                enhancement requires the Next.js adapter.
               </p>
             </div>
           </li>
@@ -304,9 +315,9 @@ export async function loginApi(data: { email: string; password: string }) {
                 Inline <code>submit</code> function
               </p>
               <p className="text-sm text-gray-400 mt-1">
-                Defining <code>submit</code> as an inline arrow function inside the component creates a new reference on
-                every render. Extract it to module scope or wrap with <code>useCallback</code> to avoid re-initialising
-                the hook.
+                Defining <code>submit</code> as an inline arrow function inside the component
+                creates a new reference on every render. Extract it to module scope or wrap with{' '}
+                <code>useCallback</code> to avoid re-initialising the hook.
               </p>
             </div>
           </li>
@@ -317,20 +328,32 @@ export async function loginApi(data: { email: string; password: string }) {
       <section className="border-t border-gray-800 pt-8">
         <h2 className="text-lg font-semibold mb-4">Related</h2>
         <div className="flex flex-wrap gap-4 text-sm">
-          <a href="/standalone" className="text-emerald-400 hover:text-emerald-300 transition-colors">
+          <a
+            href="/standalone"
+            className="text-emerald-400 hover:text-emerald-300 transition-colors"
+          >
             → Standalone Guide
           </a>
-          <a href="/recipes/custom-error-mapper" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/custom-error-mapper"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Custom Error Mapper
           </a>
-          <a href="/recipes/login-form" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/recipes/login-form"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → Login Form (Next.js)
           </a>
-          <a href="/api-reference" className="text-brand-400 hover:text-brand-300 transition-colors">
+          <a
+            href="/api-reference"
+            className="text-brand-400 hover:text-brand-300 transition-colors"
+          >
             → API Reference
           </a>
         </div>
       </section>
     </div>
-  );
+  )
 }
diff --git a/apps/docs/app/submit-lifecycle/page.tsx b/apps/docs/app/submit-lifecycle/page.tsx
index 0f6b017..6c9244a 100644
--- a/apps/docs/app/submit-lifecycle/page.tsx
+++ b/apps/docs/app/submit-lifecycle/page.tsx
@@ -9,9 +9,8 @@ export default function SubmitLifecyclePage() {
 
       <h1 className="text-3xl font-bold mb-3">Submit Lifecycle</h1>
       <p className="text-gray-400 max-w-3xl mb-10">
-        A practical mental model for <code>isSubmitting</code>, <code>isPending</code>,{" "}
-        <code>isSubmitSuccessful</code>, <code>submitErrors</code>, and{" "}
-        <code>actionResult</code>.
+        A practical mental model for <code>isSubmitting</code>, <code>isPending</code>,{' '}
+        <code>isSubmitSuccessful</code>, <code>submitErrors</code>, and <code>actionResult</code>.
       </p>
 
       {/* 1. Simple explanation */}
@@ -25,25 +24,25 @@ export default function SubmitLifecyclePage() {
             <span className="font-medium text-gray-200">Idle</span>: no request in flight.
           </li>
           <li>
-            <span className="font-medium text-gray-200">Submit starts</span>:{" "}
-            <code>isSubmitting = true</code>, <code>isPending = true</code>,{" "}
+            <span className="font-medium text-gray-200">Submit starts</span>:{' '}
+            <code>isSubmitting = true</code>, <code>isPending = true</code>,{' '}
             <code>submitErrors = null</code>.
           </li>
           <li>
-            <span className="font-medium text-gray-200">Success</span>:{" "}
-            <code>isPending = false</code>, <code>isSubmitting = false</code>,{" "}
-            <code>isSubmitSuccessful = true</code>, <code>submitErrors = null</code>,{" "}
+            <span className="font-medium text-gray-200">Success</span>:{' '}
+            <code>isPending = false</code>, <code>isSubmitting = false</code>,{' '}
+            <code>isSubmitSuccessful = true</code>, <code>submitErrors = null</code>,{' '}
             <code>actionResult = result</code>.
           </li>
           <li>
-            <span className="font-medium text-gray-200">Field error result</span>:{" "}
-            <code>isPending = false</code>, <code>isSubmitting = false</code>,{" "}
-            <code>isSubmitSuccessful = false</code>, <code>submitErrors = ...</code>,{" "}
+            <span className="font-medium text-gray-200">Field error result</span>:{' '}
+            <code>isPending = false</code>, <code>isSubmitting = false</code>,{' '}
+            <code>isSubmitSuccessful = false</code>, <code>submitErrors = ...</code>,{' '}
             <code>actionResult = result</code>.
           </li>
           <li>
-            <span className="font-medium text-gray-200">Thrown error (network/exception)</span>:{" "}
-            <code>isPending = false</code>, <code>isSubmitting = false</code>,{" "}
+            <span className="font-medium text-gray-200">Thrown error (network/exception)</span>:{' '}
+            <code>isPending = false</code>, <code>isSubmitting = false</code>,{' '}
             <code>isSubmitSuccessful = false</code>. Handle this path in <code>onError</code>.
           </li>
         </ol>
@@ -75,9 +74,7 @@ export default function SubmitLifecyclePage() {
               </tr>
               <tr className="border-b border-gray-800/50 bg-brand-500/5">
                 <td className="py-3 pr-4 font-mono text-brand-300">formState.isPending</td>
-                <td className="py-3 pr-4 text-gray-400">
-                  Transition + request pending window.
-                </td>
+                <td className="py-3 pr-4 text-gray-400">Transition + request pending window.</td>
                 <td className="py-3 pr-4 text-gray-400">
                   Derived from <code>useTransition</code> plus internal pending state.
                 </td>
@@ -97,9 +94,7 @@ export default function SubmitLifecyclePage() {
               </tr>
               <tr className="border-b border-gray-800/50">
                 <td className="py-3 pr-4 font-mono text-brand-300">formState.submitErrors</td>
-                <td className="py-3 pr-4 text-gray-400">
-                  Structured field-level error record.
-                </td>
+                <td className="py-3 pr-4 text-gray-400">Structured field-level error record.</td>
                 <td className="py-3 pr-4 text-gray-400">
                   Set on client/server validation errors, cleared at new submit start.
                 </td>
@@ -107,7 +102,9 @@ export default function SubmitLifecyclePage() {
               </tr>
               <tr className="border-b border-gray-800/50">
                 <td className="py-3 pr-4 font-mono text-brand-300">formState.actionResult</td>
-                <td className="py-3 pr-4 text-gray-400">Full result object from last completed action response.</td>
+                <td className="py-3 pr-4 text-gray-400">
+                  Full result object from last completed action response.
+                </td>
                 <td className="py-3 pr-4 text-gray-400">
                   Updated on success and field-error responses.
                 </td>
@@ -171,14 +168,15 @@ const confirmedData =
             Using <code>isSubmitting</code> for button lock/loading. Prefer <code>isPending</code>.
           </li>
           <li className="bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4 text-sm text-gray-300">
-            Treating <code>actionResult</code> as automatic success. It can also hold an error-shaped result.
+            Treating <code>actionResult</code> as automatic success. It can also hold an
+            error-shaped result.
           </li>
           <li className="bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4 text-sm text-gray-300">
-            Running success side-effects only with <code>isSubmitSuccessful</code>. Gate with{" "}
+            Running success side-effects only with <code>isSubmitSuccessful</code>. Gate with{' '}
             <code>!isPending</code> too.
           </li>
           <li className="bg-yellow-500/5 border border-yellow-500/20 rounded-lg p-4 text-sm text-gray-300">
-            Expecting <code>submitErrors</code> for thrown exceptions. Thrown errors belong to{" "}
+            Expecting <code>submitErrors</code> for thrown exceptions. Thrown errors belong to{' '}
             <code>onError</code>.
           </li>
         </ul>
@@ -203,7 +201,8 @@ const confirmedData =
           <div className="bg-gray-900/50 border border-gray-800 rounded-lg p-4">
             <p className="font-semibold text-gray-200 mb-2">Validation Errors Snippet</p>
             <p className="text-gray-400">
-              Show <code>submitErrors</code> for field-level API errors and keep RHF <code>errors</code> in sync.
+              Show <code>submitErrors</code> for field-level API errors and keep RHF{' '}
+              <code>errors</code> in sync.
             </p>
           </div>
           <div className="bg-gray-900/50 border border-gray-800 rounded-lg p-4">
@@ -216,12 +215,16 @@ const confirmedData =
       </section>
 
       <section className="border-t border-gray-800 pt-8">
-        <h2 className="text-xl font-bold mb-3 text-brand-400">How this maps to RHF + transitions + Server Actions</h2>
+        <h2 className="text-xl font-bold mb-3 text-brand-400">
+          How this maps to RHF + transitions + Server Actions
+        </h2>
         <p className="text-gray-400 leading-relaxed">
-          RHF still owns base form mechanics (<code>register</code>, <code>errors</code>, touched/dirty state).
-          hookform-action wraps submit execution, runs inside <code>startTransition</code>, then composes the final
-          form state (`isPending = transitionPending || internalPending`). In Next.js mode, the adapter also bridges{" "}
-          <code>FormData</code>/<code>prevState</code> signatures before passing control to the same core lifecycle.
+          RHF still owns base form mechanics (<code>register</code>, <code>errors</code>,
+          touched/dirty state). hookform-action wraps submit execution, runs inside{' '}
+          <code>startTransition</code>, then composes the final form state (`isPending =
+          transitionPending || internalPending`). In Next.js mode, the adapter also bridges{' '}
+          <code>FormData</code>/<code>prevState</code> signatures before passing control to the same
+          core lifecycle.
         </p>
       </section>
     </div>
diff --git a/apps/docs/app/why/page.tsx b/apps/docs/app/why/page.tsx
index 16a0b58..5c82c53 100644
--- a/apps/docs/app/why/page.tsx
+++ b/apps/docs/app/why/page.tsx
@@ -9,7 +9,7 @@ export default function WhyPage() {
 
       <h1 className="text-4xl font-extrabold mb-4">Manual setup vs hookform-action</h1>
       <p className="text-gray-400 text-lg mb-16 max-w-2xl">
-        A concrete comparison of wiring React Hook Form with Server Actions by hand, versus using{" "}
+        A concrete comparison of wiring React Hook Form with Server Actions by hand, versus using{' '}
         <code>hookform-action</code> as the integration layer.
       </p>
 
@@ -46,13 +46,15 @@ export default function WhyPage() {
                   Call <code>setError()</code> for each field after parsing the action result
                 </td>
                 <td className="py-3.5 text-gray-300">
-                  Automatic via <code>defaultErrorMapper</code> — override with <code>errorMapper</code> when needed
+                  Automatic via <code>defaultErrorMapper</code> — override with{' '}
+                  <code>errorMapper</code> when needed
                 </td>
               </tr>
               <tr>
                 <td className="py-3.5 pr-6 font-medium">Client-side validation</td>
                 <td className="py-3.5 pr-6 text-gray-400">
-                  Pass <code>resolver</code> to <code>useForm</code> and keep schema in sync with server
+                  Pass <code>resolver</code> to <code>useForm</code> and keep schema in sync with
+                  server
                 </td>
                 <td className="py-3.5 text-gray-300">
                   Set <code>validationMode</code> — schema auto-detected from <code>withZod</code>
@@ -61,7 +63,8 @@ export default function WhyPage() {
               <tr>
                 <td className="py-3.5 pr-6 font-medium">Pending / loading state</td>
                 <td className="py-3.5 pr-6 text-gray-400">
-                  <code>useTransition</code> + <code>useState</code> wiring around <code>startTransition</code>
+                  <code>useTransition</code> + <code>useState</code> wiring around{' '}
+                  <code>startTransition</code>
                 </td>
                 <td className="py-3.5 text-gray-300">
                   <code>formState.isPending</code> backed by <code>useTransition</code> internally
@@ -130,30 +133,35 @@ export default function WhyPage() {
                 Pass <code>zodResolver(schema)</code> to <code>useForm</code>
               </li>
               <li>
-                In the Server Action: call <code>schema.safeParse(data)</code>, format <code>fieldErrors</code>, return
-                them
+                In the Server Action: call <code>schema.safeParse(data)</code>, format{' '}
+                <code>fieldErrors</code>, return them
               </li>
               <li>
-                In the component: inspect action result, loop over errors, call <code>setError(field, …)</code> for each
+                In the component: inspect action result, loop over errors, call{' '}
+                <code>setError(field, …)</code> for each
               </li>
               <li>
                 Wire <code>useTransition</code> around the action call to get <code>isPending</code>
               </li>
               <li>
-                If you need optimistic UI: add <code>useOptimistic</code>, compute next state, pass to{" "}
-                <code>startTransition</code>, handle rollback
+                If you need optimistic UI: add <code>useOptimistic</code>, compute next state, pass
+                to <code>startTransition</code>, handle rollback
               </li>
               <li>
-                If you need persistence: write a <code>useEffect</code> to save/restore from <code>sessionStorage</code>
-                , debounce it, clear on unmount
+                If you need persistence: write a <code>useEffect</code> to save/restore from{' '}
+                <code>sessionStorage</code>, debounce it, clear on unmount
               </li>
             </ol>
-            <p className="mt-4 text-xs text-red-400/70">Each new form repeats steps 3–7 from scratch.</p>
+            <p className="mt-4 text-xs text-red-400/70">
+              Each new form repeats steps 3–7 from scratch.
+            </p>
           </div>
 
           {/* hookform-action */}
           <div className="border border-brand-700/40 bg-brand-950/10 rounded-xl p-6">
-            <h3 className="text-base font-semibold text-brand-400 mb-4">hookform-action — steps per form</h3>
+            <h3 className="text-base font-semibold text-brand-400 mb-4">
+              hookform-action — steps per form
+            </h3>
             <ol className="space-y-3 text-sm text-gray-300 list-decimal list-inside marker:text-brand-600">
               <li>
                 Wrap server action with <code>withZod(schema, handler)</code>
@@ -162,12 +170,12 @@ export default function WhyPage() {
                 Call <code>useActionForm(action, options)</code> in the component
               </li>
               <li>
-                Use <code>register</code>, <code>handleSubmit()</code>, and <code>formState.errors</code> as you
-                normally would with RHF
+                Use <code>register</code>, <code>handleSubmit()</code>, and{' '}
+                <code>formState.errors</code> as you normally would with RHF
               </li>
             </ol>
             <p className="mt-4 text-xs text-brand-400/70">
-              Steps 4–7 from the manual list become opt-in options: <code>validationMode</code>,{" "}
+              Steps 4–7 from the manual list become opt-in options: <code>validationMode</code>,{' '}
               <code>optimisticData</code>, <code>persistKey</code>.
             </p>
           </div>
@@ -189,7 +197,9 @@ export default function WhyPage() {
         </h3>
         <div className="grid sm:grid-cols-2 gap-4 mb-10">
           <div>
-            <p className="text-xs text-red-400 font-medium mb-2 uppercase tracking-widest">Manual</p>
+            <p className="text-xs text-red-400 font-medium mb-2 uppercase tracking-widest">
+              Manual
+            </p>
             <div className="code-block text-gray-300 text-xs leading-relaxed">
               <pre>{`// actions.ts
 'use server'
@@ -221,7 +231,9 @@ export async function loginAction(data: unknown) {
             </div>
           </div>
           <div>
-            <p className="text-xs text-brand-400 font-medium mb-2 uppercase tracking-widest">hookform-action</p>
+            <p className="text-xs text-brand-400 font-medium mb-2 uppercase tracking-widest">
+              hookform-action
+            </p>
             <div className="code-block text-gray-300 text-xs leading-relaxed">
               <pre>{`// actions.ts
 'use server'
@@ -255,7 +267,9 @@ export const loginAction = withZod(
         </h3>
         <div className="grid sm:grid-cols-2 gap-4">
           <div>
-            <p className="text-xs text-red-400 font-medium mb-2 uppercase tracking-widest">Manual</p>
+            <p className="text-xs text-red-400 font-medium mb-2 uppercase tracking-widest">
+              Manual
+            </p>
             <div className="code-block text-gray-300 text-xs leading-relaxed">
               <pre>{`// LoginForm.tsx
 'use client'
@@ -317,7 +331,9 @@ export function LoginForm() {
             </div>
           </div>
           <div>
-            <p className="text-xs text-brand-400 font-medium mb-2 uppercase tracking-widest">hookform-action</p>
+            <p className="text-xs text-brand-400 font-medium mb-2 uppercase tracking-widest">
+              hookform-action
+            </p>
             <div className="code-block text-gray-300 text-xs leading-relaxed">
               <pre>{`// LoginForm.tsx
 'use client'
@@ -367,7 +383,9 @@ export function LoginForm() {
           </div>
           <div className="bg-gray-900/50 border border-gray-800 rounded-xl p-4">
             <p className="text-2xl font-bold text-emerald-400 mb-1">−3</p>
-            <p className="text-gray-500 text-xs">concepts to keep in sync (resolver, transition, setError loop)</p>
+            <p className="text-gray-500 text-xs">
+              concepts to keep in sync (resolver, transition, setError loop)
+            </p>
           </div>
         </div>
       </section>
@@ -379,20 +397,20 @@ export function LoginForm() {
         <h2 className="text-2xl font-bold mb-4">Bottom line</h2>
         <div className="bg-gray-900/50 border border-gray-800 rounded-xl p-8 space-y-4 text-gray-300 leading-relaxed">
           <p>
-            The manual approach works. React Hook Form, Zod, and Server Actions are well-designed primitives and wiring
-            them yourself is absolutely viable on a small form.
+            The manual approach works. React Hook Form, Zod, and Server Actions are well-designed
+            primitives and wiring them yourself is absolutely viable on a small form.
           </p>
           <p>
-            The friction compounds as the app grows: every new form repeats the same <code>safeParse</code> boilerplate
-            on the server, the same <code>setError</code> loop on the client, the same <code>useTransition</code>{" "}
-            wrapper for pending state. When you add optimistic updates or multi-step persistence the surface area grows
-            further.
+            The friction compounds as the app grows: every new form repeats the same{' '}
+            <code>safeParse</code> boilerplate on the server, the same <code>setError</code> loop on
+            the client, the same <code>useTransition</code> wrapper for pending state. When you add
+            optimistic updates or multi-step persistence the surface area grows further.
           </p>
           <p>
-            <code>hookform-action</code> doesn&apos;t hide any of those primitives — it codifies the patterns you would
-            write anyway into a single hook and a single server wrapper. You keep full access to the underlying{" "}
-            <code>useForm</code> instance and can still pass any RHF option. The goal is to remove the repetitive
-            plumbing, not to abstract away control.
+            <code>hookform-action</code> doesn&apos;t hide any of those primitives — it codifies the
+            patterns you would write anyway into a single hook and a single server wrapper. You keep
+            full access to the underlying <code>useForm</code> instance and can still pass any RHF
+            option. The goal is to remove the repetitive plumbing, not to abstract away control.
           </p>
           <div className="pt-2 flex gap-4">
             <a
@@ -411,5 +429,5 @@ export function LoginForm() {
         </div>
       </section>
     </div>
-  );
+  )
 }
diff --git a/packages/core/src/__tests__/client-validation.test.ts b/packages/core/src/__tests__/client-validation.test.ts
index 34e7b07..725423b 100644
--- a/packages/core/src/__tests__/client-validation.test.ts
+++ b/packages/core/src/__tests__/client-validation.test.ts
@@ -1,276 +1,276 @@
-import { act, renderHook, waitFor } from "@testing-library/react";
-import { describe, expect, it, vi } from "vitest";
-import { z } from "zod";
-import type { JsonServerAction } from "../types";
-import { useActionForm } from "../use-action-form";
-import { withZod } from "../with-zod";
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import type { JsonServerAction } from '../types'
+import { useActionForm } from '../use-action-form'
+import { withZod } from '../with-zod'
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 const signupSchema = z.object({
-  email: z.string().email("Invalid email address"),
-  password: z.string().min(8, "Password must be at least 8 characters"),
-});
+  email: z.string().email('Invalid email address'),
+  password: z.string().min(8, 'Password must be at least 8 characters'),
+})
 
 /** JSON action that always succeeds */
 function createSuccessAction(): JsonServerAction<{ success: true }> {
-  return vi.fn(async (_data: unknown) => ({ success: true as const }));
+  return vi.fn(async (_data: unknown) => ({ success: true as const }))
 }
 
 // ---------------------------------------------------------------------------
 // Tests: Explicit schema validation
 // ---------------------------------------------------------------------------
 
-describe("useActionForm – client-side Zod validation (explicit schema)", () => {
-  it("validates on submit by default and blocks submission on error", async () => {
-    const action = createSuccessAction();
+describe('useActionForm – client-side Zod validation (explicit schema)', () => {
+  it('validates on submit by default and blocks submission on error', async () => {
+    const action = createSuccessAction()
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: "invalid", password: "short" },
+        defaultValues: { email: 'invalid', password: 'short' },
         schema: signupSchema,
-        clientValidation: "onSubmit",
+        clientValidation: 'onSubmit',
       }),
-    );
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
       // Action should NOT have been called because client validation failed
-      expect(action).not.toHaveBeenCalled();
+      expect(action).not.toHaveBeenCalled()
       // Errors should be set
-      expect(result.current.formState.serverErrors).not.toBeNull();
-    });
-  });
+      expect(result.current.formState.serverErrors).not.toBeNull()
+    })
+  })
 
-  it("allows submission when client validation passes", async () => {
-    const action = createSuccessAction();
+  it('allows submission when client validation passes', async () => {
+    const action = createSuccessAction()
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: "valid@test.com", password: "12345678" },
+        defaultValues: { email: 'valid@test.com', password: '12345678' },
         schema: signupSchema,
-        clientValidation: "onSubmit",
+        clientValidation: 'onSubmit',
       }),
-    );
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
-      expect(action).toHaveBeenCalled();
-      expect(result.current.formState.isSubmitSuccessful).toBe(true);
-    });
-  });
+      expect(action).toHaveBeenCalled()
+      expect(result.current.formState.isSubmitSuccessful).toBe(true)
+    })
+  })
 
-  it("sets specific field errors from client validation", async () => {
-    const action = createSuccessAction();
+  it('sets specific field errors from client validation', async () => {
+    const action = createSuccessAction()
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: "bad", password: "12345678" },
+        defaultValues: { email: 'bad', password: '12345678' },
         schema: signupSchema,
-        clientValidation: "onSubmit",
+        clientValidation: 'onSubmit',
       }),
-    );
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
       // Only email should have an error
-      const emailState = result.current.getFieldState("email");
-      expect(emailState.error?.message).toBe("Invalid email address");
-    });
-  });
+      const emailState = result.current.getFieldState('email')
+      expect(emailState.error?.message).toBe('Invalid email address')
+    })
+  })
 
-  it("validates onChange when clientValidation is onChange", async () => {
-    const action = createSuccessAction();
+  it('validates onChange when clientValidation is onChange', async () => {
+    const action = createSuccessAction()
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: "", password: "" },
+        defaultValues: { email: '', password: '' },
         schema: signupSchema,
-        clientValidation: "onChange",
+        clientValidation: 'onChange',
       }),
-    );
+    )
 
     // Trigger a change with invalid value
     act(() => {
-      result.current.setValue("email", "bad-email", { shouldDirty: true });
-    });
+      result.current.setValue('email', 'bad-email', { shouldDirty: true })
+    })
 
     // Wait for the watch subscription to fire
     await waitFor(() => {
-      const emailState = result.current.getFieldState("email");
-      expect(emailState.error?.message).toBe("Invalid email address");
-    });
-  });
+      const emailState = result.current.getFieldState('email')
+      expect(emailState.error?.message).toBe('Invalid email address')
+    })
+  })
 
-  it("clears errors when field becomes valid on onChange", async () => {
-    const action = createSuccessAction();
+  it('clears errors when field becomes valid on onChange', async () => {
+    const action = createSuccessAction()
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: "", password: "" },
+        defaultValues: { email: '', password: '' },
         schema: signupSchema,
-        clientValidation: "onChange",
+        clientValidation: 'onChange',
       }),
-    );
+    )
 
     // Set invalid value
     act(() => {
-      result.current.setValue("email", "bad", { shouldDirty: true });
-    });
+      result.current.setValue('email', 'bad', { shouldDirty: true })
+    })
 
     await waitFor(() => {
-      const emailState = result.current.getFieldState("email");
-      expect(emailState.error?.message).toBe("Invalid email address");
-    });
+      const emailState = result.current.getFieldState('email')
+      expect(emailState.error?.message).toBe('Invalid email address')
+    })
 
     // Set valid value
     act(() => {
-      result.current.setValue("email", "valid@test.com", { shouldDirty: true });
-    });
+      result.current.setValue('email', 'valid@test.com', { shouldDirty: true })
+    })
 
     await waitFor(() => {
-      const emailState = result.current.getFieldState("email");
-      expect(emailState.error).toBeUndefined();
-    });
-  });
-});
+      const emailState = result.current.getFieldState('email')
+      expect(emailState.error).toBeUndefined()
+    })
+  })
+})
 
 // ---------------------------------------------------------------------------
 // Tests: Auto-detected schema from withZod
 // ---------------------------------------------------------------------------
 
-describe("useActionForm – auto-detected schema from withZod", () => {
-  it("withZod attaches __schema to the action", () => {
-    const action = withZod(signupSchema, async (_data) => ({ success: true as const }));
-    expect(action.__schema).toBe(signupSchema);
-  });
+describe('useActionForm – auto-detected schema from withZod', () => {
+  it('withZod attaches __schema to the action', () => {
+    const action = withZod(signupSchema, async (_data) => ({ success: true as const }))
+    expect(action.__schema).toBe(signupSchema)
+  })
 
-  it("auto-detects schema from withZod action and validates on submit", async () => {
+  it('auto-detects schema from withZod action and validates on submit', async () => {
     const handler = vi.fn(async (data: unknown) => ({
       success: true as const,
       data,
-    }));
-    const action = withZod(signupSchema, handler);
+    }))
+    const action = withZod(signupSchema, handler)
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: "invalid", password: "short" },
+        defaultValues: { email: 'invalid', password: 'short' },
         // No explicit schema – should auto-detect from action.__schema
-        clientValidation: "onSubmit",
+        clientValidation: 'onSubmit',
       }),
-    );
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
       // Handler should NOT have been called since client validation fails
-      expect(handler).not.toHaveBeenCalled();
-      expect(result.current.formState.serverErrors).not.toBeNull();
-    });
-  });
+      expect(handler).not.toHaveBeenCalled()
+      expect(result.current.formState.serverErrors).not.toBeNull()
+    })
+  })
 
-  it("auto-detected schema validates onChange", async () => {
+  it('auto-detected schema validates onChange', async () => {
     const action = withZod(signupSchema, async (_data) => ({
       success: true as const,
-    }));
+    }))
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: "", password: "" },
+        defaultValues: { email: '', password: '' },
         // Auto-detects schema, validates on change
-        clientValidation: "onChange",
+        clientValidation: 'onChange',
       }),
-    );
+    )
 
     act(() => {
-      result.current.setValue("email", "bad", { shouldDirty: true });
-    });
+      result.current.setValue('email', 'bad', { shouldDirty: true })
+    })
 
     await waitFor(() => {
-      const emailState = result.current.getFieldState("email");
-      expect(emailState.error?.message).toBe("Invalid email address");
-    });
-  });
+      const emailState = result.current.getFieldState('email')
+      expect(emailState.error?.message).toBe('Invalid email address')
+    })
+  })
 
-  it("explicit schema takes priority over auto-detected", async () => {
+  it('explicit schema takes priority over auto-detected', async () => {
     const customSchema = z.object({
-      email: z.string().email("Custom error message"),
+      email: z.string().email('Custom error message'),
       password: z.string().min(1),
-    });
+    })
 
     const action = withZod(signupSchema, async (_data) => ({
       success: true as const,
-    }));
+    }))
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: "bad", password: "12345678" },
+        defaultValues: { email: 'bad', password: '12345678' },
         schema: customSchema, // This should take priority
-        clientValidation: "onSubmit",
+        clientValidation: 'onSubmit',
       }),
-    );
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
-      const emailState = result.current.getFieldState("email");
-      expect(emailState.error?.message).toBe("Custom error message"); // From custom schema, not withZod
-    });
-  });
-});
+      const emailState = result.current.getFieldState('email')
+      expect(emailState.error?.message).toBe('Custom error message') // From custom schema, not withZod
+    })
+  })
+})
 
 // ---------------------------------------------------------------------------
 // Tests: isPending state (useTransition integration)
 // ---------------------------------------------------------------------------
 
-describe("useActionForm – isPending / useTransition", () => {
-  it("formState includes isPending property", () => {
-    const action = createSuccessAction();
+describe('useActionForm – isPending / useTransition', () => {
+  it('formState includes isPending property', () => {
+    const action = createSuccessAction()
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: "" },
+        defaultValues: { email: '' },
       }),
-    );
+    )
 
-    expect(result.current.formState.isPending).toBe(false);
-  });
+    expect(result.current.formState.isPending).toBe(false)
+  })
 
-  it("isPending resolves to false after successful submission", async () => {
-    const action = createSuccessAction();
+  it('isPending resolves to false after successful submission', async () => {
+    const action = createSuccessAction()
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: "test@test.com", password: "12345678" },
+        defaultValues: { email: 'test@test.com', password: '12345678' },
       }),
-    );
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
-      expect(result.current.formState.isPending).toBe(false);
-      expect(result.current.formState.isSubmitSuccessful).toBe(true);
-    });
-  });
-});
+      expect(result.current.formState.isPending).toBe(false)
+      expect(result.current.formState.isSubmitSuccessful).toBe(true)
+    })
+  })
+})
diff --git a/packages/core/src/__tests__/optimistic.test.ts b/packages/core/src/__tests__/optimistic.test.ts
index 7ea09a3..68530e9 100644
--- a/packages/core/src/__tests__/optimistic.test.ts
+++ b/packages/core/src/__tests__/optimistic.test.ts
@@ -1,64 +1,64 @@
-import { act, renderHook, waitFor } from "@testing-library/react";
-import { describe, expect, it, vi } from "vitest";
-import type { JsonServerAction } from "../types";
-import { useActionForm } from "../use-action-form";
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import type { JsonServerAction } from '../types'
+import { useActionForm } from '../use-action-form'
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 interface TodoItem {
-  id: string;
-  title: string;
-  completed: boolean;
+  id: string
+  title: string
+  completed: boolean
 }
 
 /** JSON action that succeeds – simulates updating a todo */
 function createUpdateTodoAction(): JsonServerAction<{ success: true; data: TodoItem }> {
   return vi.fn(async (data: unknown) => {
-    const d = data as Record<string, unknown>;
+    const d = data as Record<string, unknown>
     return {
       success: true as const,
       data: {
-        id: (d.id as string) ?? "todo-1",
+        id: (d.id as string) ?? 'todo-1',
         title: d.title as string,
         completed: (d.completed as boolean) ?? false,
       },
-    };
-  });
+    }
+  })
 }
 
 /** JSON action that returns errors */
 function createErrorTodoAction(): JsonServerAction<{ errors: { title: string[] } }> {
   return vi.fn(async (_data: unknown) => ({
-    errors: { title: ["Title is required"] },
-  }));
+    errors: { title: ['Title is required'] },
+  }))
 }
 
 /** JSON action that throws */
 function createThrowingTodoAction(): JsonServerAction<{ success: true }> {
   return vi.fn(async (_data: unknown) => {
-    throw new Error("Network error");
-  });
+    throw new Error('Network error')
+  })
 }
 
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-describe("useActionForm – optimistic updates", () => {
+describe('useActionForm – optimistic updates', () => {
   const INITIAL_TODO: TodoItem = {
-    id: "todo-1",
-    title: "Buy groceries",
+    id: 'todo-1',
+    title: 'Buy groceries',
     completed: false,
-  };
+  }
 
-  it("returns optimistic state when optimisticReducer is provided", () => {
-    const action = createUpdateTodoAction();
+  it('returns optimistic state when optimisticReducer is provided', () => {
+    const action = createUpdateTodoAction()
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { title: "Buy groceries", completed: false },
+        defaultValues: { title: 'Buy groceries', completed: false },
         optimisticDefault: INITIAL_TODO,
         optimisticReducer: (current, formValues) => ({
           ...current,
@@ -66,32 +66,32 @@ describe("useActionForm – optimistic updates", () => {
           completed: formValues.completed,
         }),
       }),
-    );
+    )
 
-    expect(result.current.optimistic).toBeDefined();
-    expect(result.current.optimistic?.data).toEqual(INITIAL_TODO);
-    expect(result.current.optimistic?.isPending).toBe(false);
-    expect(typeof result.current.optimistic?.rollback).toBe("function");
-  });
+    expect(result.current.optimistic).toBeDefined()
+    expect(result.current.optimistic?.data).toEqual(INITIAL_TODO)
+    expect(result.current.optimistic?.isPending).toBe(false)
+    expect(typeof result.current.optimistic?.rollback).toBe('function')
+  })
 
-  it("returns undefined optimistic when no optimisticReducer is set", () => {
-    const action = createUpdateTodoAction();
+  it('returns undefined optimistic when no optimisticReducer is set', () => {
+    const action = createUpdateTodoAction()
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { title: "" },
+        defaultValues: { title: '' },
       }),
-    );
+    )
 
-    expect(result.current.optimistic).toBeUndefined();
-  });
+    expect(result.current.optimistic).toBeUndefined()
+  })
 
-  it("updates optimistic data on successful submit", async () => {
-    const action = createUpdateTodoAction();
+  it('updates optimistic data on successful submit', async () => {
+    const action = createUpdateTodoAction()
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { title: "Updated title", completed: true },
+        defaultValues: { title: 'Updated title', completed: true },
         optimisticDefault: INITIAL_TODO,
         optimisticReducer: (current, formValues) => ({
           ...current,
@@ -99,106 +99,106 @@ describe("useActionForm – optimistic updates", () => {
           completed: formValues.completed,
         }),
       }),
-    );
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(true);
-    });
+      expect(result.current.formState.isSubmitSuccessful).toBe(true)
+    })
 
     // After successful submit, the optimistic state should reflect the update
-    expect(result.current.optimistic?.data.title).toBe("Updated title");
-    expect(result.current.optimistic?.data.completed).toBe(true);
-  });
+    expect(result.current.optimistic?.data.title).toBe('Updated title')
+    expect(result.current.optimistic?.data.completed).toBe(true)
+  })
 
-  it("rolls back optimistic data on action error", async () => {
-    const action = createErrorTodoAction();
+  it('rolls back optimistic data on action error', async () => {
+    const action = createErrorTodoAction()
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { title: "" },
+        defaultValues: { title: '' },
         optimisticDefault: INITIAL_TODO,
         optimisticReducer: (current, formValues) => ({
           ...current,
           title: formValues.title,
         }),
       }),
-    );
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(false);
-    });
+      expect(result.current.formState.isSubmitSuccessful).toBe(false)
+    })
 
     // Should have rolled back to original
-    expect(result.current.optimistic?.data.title).toBe("Buy groceries");
-  });
+    expect(result.current.optimistic?.data.title).toBe('Buy groceries')
+  })
 
-  it("rolls back optimistic data on action throw", async () => {
-    const action = createThrowingTodoAction();
+  it('rolls back optimistic data on action throw', async () => {
+    const action = createThrowingTodoAction()
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { title: "Will fail" },
+        defaultValues: { title: 'Will fail' },
         optimisticDefault: INITIAL_TODO,
         optimisticReducer: (current, formValues) => ({
           ...current,
           title: formValues.title,
         }),
       }),
-    );
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitting).toBe(false);
-    });
+      expect(result.current.formState.isSubmitting).toBe(false)
+    })
 
     // Should have rolled back to original
-    expect(result.current.optimistic?.data.title).toBe("Buy groceries");
-  });
+    expect(result.current.optimistic?.data.title).toBe('Buy groceries')
+  })
 
-  it("manual rollback restores confirmed state", async () => {
-    const action = createUpdateTodoAction();
+  it('manual rollback restores confirmed state', async () => {
+    const action = createUpdateTodoAction()
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { title: "Updated title", completed: false },
+        defaultValues: { title: 'Updated title', completed: false },
         optimisticDefault: INITIAL_TODO,
         optimisticReducer: (current, formValues) => ({
           ...current,
           title: formValues.title,
         }),
       }),
-    );
+    )
 
     // Submit successfully to update confirmed state
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(true);
-    });
+      expect(result.current.formState.isSubmitSuccessful).toBe(true)
+    })
 
     // Now manually rollback
     act(() => {
-      result.current.optimistic?.rollback();
-    });
+      result.current.optimistic?.rollback()
+    })
 
     // The confirmed state after success should be the updated value
-    expect(result.current.optimistic?.data.title).toBe("Updated title");
-  });
-});
+    expect(result.current.optimistic?.data.title).toBe('Updated title')
+  })
+})
diff --git a/packages/core/src/__tests__/persistence.test.ts b/packages/core/src/__tests__/persistence.test.ts
index 2453b39..502d214 100644
--- a/packages/core/src/__tests__/persistence.test.ts
+++ b/packages/core/src/__tests__/persistence.test.ts
@@ -1,155 +1,155 @@
-import { act, renderHook, waitFor } from "@testing-library/react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { loadPersistedValues, savePersistedValues } from "../persist";
-import type { ServerAction } from "../types";
-import { useActionForm } from "../use-action-form";
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { loadPersistedValues, savePersistedValues } from '../persist'
+import type { ServerAction } from '../types'
+import { useActionForm } from '../use-action-form'
 
 // ---------------------------------------------------------------------------
 // Persistence integration tests
 // ---------------------------------------------------------------------------
 
-describe("useActionForm – persistence", () => {
-  const PERSIST_KEY = "wizard-step-1";
+describe('useActionForm – persistence', () => {
+  const PERSIST_KEY = 'wizard-step-1'
 
   beforeEach(() => {
-    sessionStorage.clear();
-  });
+    sessionStorage.clear()
+  })
 
-  it("restores values from sessionStorage on mount", () => {
+  it('restores values from sessionStorage on mount', () => {
     // Pre-populate storage
-    savePersistedValues(PERSIST_KEY, { email: "stored@test.com", name: "Bob" });
+    savePersistedValues(PERSIST_KEY, { email: 'stored@test.com', name: 'Bob' })
 
     const action: ServerAction<{ success: true }> = vi.fn(async () => ({
       success: true as const,
-    }));
+    }))
 
     const { result } = renderHook(() =>
       useActionForm(action, {
         persistKey: PERSIST_KEY,
-        defaultValues: { email: "", name: "" },
+        defaultValues: { email: '', name: '' },
       }),
-    );
+    )
 
-    expect(result.current.getValues("email")).toBe("stored@test.com");
-    expect(result.current.getValues("name")).toBe("Bob");
-  });
+    expect(result.current.getValues('email')).toBe('stored@test.com')
+    expect(result.current.getValues('name')).toBe('Bob')
+  })
 
-  it("persists form values to sessionStorage when fields change", async () => {
+  it('persists form values to sessionStorage when fields change', async () => {
     const action: ServerAction<{ success: true }> = vi.fn(async () => ({
       success: true as const,
-    }));
+    }))
 
     const { result } = renderHook(() =>
       useActionForm(action, {
         persistKey: PERSIST_KEY,
-        defaultValues: { email: "" },
+        defaultValues: { email: '' },
         persistDebounce: 50, // shorter for tests
       }),
-    );
+    )
 
     act(() => {
-      result.current.setValue("email", "typing@test.com");
-    });
+      result.current.setValue('email', 'typing@test.com')
+    })
 
     // Wait for debounce
-    await new Promise((r) => setTimeout(r, 100));
+    await new Promise((r) => setTimeout(r, 100))
 
-    const stored = loadPersistedValues<{ email: string }>(PERSIST_KEY);
-    expect(stored?.email).toBe("typing@test.com");
-  });
+    const stored = loadPersistedValues<{ email: string }>(PERSIST_KEY)
+    expect(stored?.email).toBe('typing@test.com')
+  })
 
-  it("clears sessionStorage after successful submission", async () => {
-    savePersistedValues(PERSIST_KEY, { email: "old@test.com" });
+  it('clears sessionStorage after successful submission', async () => {
+    savePersistedValues(PERSIST_KEY, { email: 'old@test.com' })
 
     const action: ServerAction<{ success: true }> = vi.fn(async () => ({
       success: true as const,
-    }));
+    }))
 
     const { result } = renderHook(() =>
       useActionForm(action, {
         persistKey: PERSIST_KEY,
-        defaultValues: { email: "old@test.com" },
+        defaultValues: { email: 'old@test.com' },
       }),
-    );
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(true);
-    });
+      expect(result.current.formState.isSubmitSuccessful).toBe(true)
+    })
 
-    expect(loadPersistedValues(PERSIST_KEY)).toBeNull();
-  });
+    expect(loadPersistedValues(PERSIST_KEY)).toBeNull()
+  })
 
-  it("does NOT clear sessionStorage when submission has errors", async () => {
-    savePersistedValues(PERSIST_KEY, { email: "bad@test.com" });
+  it('does NOT clear sessionStorage when submission has errors', async () => {
+    savePersistedValues(PERSIST_KEY, { email: 'bad@test.com' })
 
     const action: ServerAction<{ errors: { email: string[] } }> = vi.fn(async () => ({
-      errors: { email: ["Invalid"] },
-    }));
+      errors: { email: ['Invalid'] },
+    }))
 
     const { result } = renderHook(() =>
       useActionForm(action, {
         persistKey: PERSIST_KEY,
-        defaultValues: { email: "bad@test.com" },
+        defaultValues: { email: 'bad@test.com' },
       }),
-    );
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(false);
-    });
+      expect(result.current.formState.isSubmitSuccessful).toBe(false)
+    })
 
     // Storage should still exist
-    expect(loadPersistedValues(PERSIST_KEY)).not.toBeNull();
-  });
+    expect(loadPersistedValues(PERSIST_KEY)).not.toBeNull()
+  })
 
-  it("manually persists via persist()", () => {
+  it('manually persists via persist()', () => {
     const action: ServerAction<{ success: true }> = vi.fn(async () => ({
       success: true as const,
-    }));
+    }))
 
     const { result } = renderHook(() =>
       useActionForm(action, {
         persistKey: PERSIST_KEY,
-        defaultValues: { email: "" },
+        defaultValues: { email: '' },
       }),
-    );
+    )
 
     act(() => {
-      result.current.setValue("email", "manual@test.com");
-      result.current.persist();
-    });
+      result.current.setValue('email', 'manual@test.com')
+      result.current.persist()
+    })
 
-    const stored = loadPersistedValues<{ email: string }>(PERSIST_KEY);
-    expect(stored?.email).toBe("manual@test.com");
-  });
+    const stored = loadPersistedValues<{ email: string }>(PERSIST_KEY)
+    expect(stored?.email).toBe('manual@test.com')
+  })
 
-  it("clears persisted data via clearPersisted()", () => {
-    savePersistedValues(PERSIST_KEY, { email: "clear@test.com" });
+  it('clears persisted data via clearPersisted()', () => {
+    savePersistedValues(PERSIST_KEY, { email: 'clear@test.com' })
 
     const action: ServerAction<{ success: true }> = vi.fn(async () => ({
       success: true as const,
-    }));
+    }))
 
     const { result } = renderHook(() =>
       useActionForm(action, {
         persistKey: PERSIST_KEY,
-        defaultValues: { email: "" },
+        defaultValues: { email: '' },
       }),
-    );
+    )
 
     act(() => {
-      result.current.clearPersisted();
-    });
+      result.current.clearPersisted()
+    })
 
-    expect(loadPersistedValues(PERSIST_KEY)).toBeNull();
-  });
-});
+    expect(loadPersistedValues(PERSIST_KEY)).toBeNull()
+  })
+})
diff --git a/packages/core/src/__tests__/use-action-form-core.test.ts b/packages/core/src/__tests__/use-action-form-core.test.ts
index 9a73016..41486c9 100644
--- a/packages/core/src/__tests__/use-action-form-core.test.ts
+++ b/packages/core/src/__tests__/use-action-form-core.test.ts
@@ -1,334 +1,340 @@
-import { act, renderHook, waitFor } from "@testing-library/react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { SubmitFunction } from "../core-types";
-import { useActionFormCore } from "../use-action-form-core";
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { SubmitFunction } from '../core-types'
+import { useActionFormCore } from '../use-action-form-core'
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-function createSuccessSubmit(): SubmitFunction<Record<string, unknown>, { success: true; data: string }> {
+function createSuccessSubmit(): SubmitFunction<
+  Record<string, unknown>,
+  { success: true; data: string }
+> {
   return vi.fn(async (_data: Record<string, unknown>) => ({
     success: true as const,
-    data: "ok",
-  }));
+    data: 'ok',
+  }))
 }
 
-function createErrorSubmit(): SubmitFunction<Record<string, unknown>, { errors: { email: string[] } }> {
+function createErrorSubmit(): SubmitFunction<
+  Record<string, unknown>,
+  { errors: { email: string[] } }
+> {
   return vi.fn(async (_data: Record<string, unknown>) => ({
-    errors: { email: ["Invalid email address"] },
-  }));
+    errors: { email: ['Invalid email address'] },
+  }))
 }
 
 function createThrowingSubmit(): SubmitFunction<Record<string, unknown>, { success: true }> {
   return vi.fn(async (_data: Record<string, unknown>) => {
-    throw new Error("Network failure");
-  });
+    throw new Error('Network failure')
+  })
 }
 
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-describe("useActionFormCore", () => {
+describe('useActionFormCore', () => {
   beforeEach(() => {
-    sessionStorage.clear();
-  });
+    sessionStorage.clear()
+  })
 
   // ---- Basic rendering ----------------------------------------------------
 
-  it("returns all expected core properties", () => {
-    const submit = createSuccessSubmit();
-    const { result } = renderHook(() => useActionFormCore(submit));
+  it('returns all expected core properties', () => {
+    const submit = createSuccessSubmit()
+    const { result } = renderHook(() => useActionFormCore(submit))
 
-    expect(result.current.register).toBeDefined();
-    expect(result.current.handleSubmit).toBeDefined();
-    expect(result.current.formState).toBeDefined();
-    expect(result.current.setServerError).toBeDefined();
-    expect(result.current.persist).toBeDefined();
-    expect(result.current.clearPersisted).toBeDefined();
-    expect(result.current.control).toBeDefined();
-  });
+    expect(result.current.register).toBeDefined()
+    expect(result.current.handleSubmit).toBeDefined()
+    expect(result.current.formState).toBeDefined()
+    expect(result.current.setServerError).toBeDefined()
+    expect(result.current.persist).toBeDefined()
+    expect(result.current.clearPersisted).toBeDefined()
+    expect(result.current.control).toBeDefined()
+  })
 
   it("does NOT have formAction (that's adapter-specific)", () => {
-    const submit = createSuccessSubmit();
-    const { result } = renderHook(() => useActionFormCore(submit));
+    const submit = createSuccessSubmit()
+    const { result } = renderHook(() => useActionFormCore(submit))
 
-    expect((result.current as Record<string, unknown>).formAction).toBeUndefined();
-  });
+    expect((result.current as Record<string, unknown>).formAction).toBeUndefined()
+  })
 
-  it("uses provided defaultValues", () => {
-    const submit = createSuccessSubmit();
+  it('uses provided defaultValues', () => {
+    const submit = createSuccessSubmit()
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { email: "test@example.com" },
+        defaultValues: { email: 'test@example.com' },
       }),
-    );
+    )
 
-    expect(result.current.getValues("email")).toBe("test@example.com");
-  });
+    expect(result.current.getValues('email')).toBe('test@example.com')
+  })
 
   // ---- Successful submission ----------------------------------------------
 
-  it("calls the submit function on handleSubmit", async () => {
-    const submit = createSuccessSubmit();
+  it('calls the submit function on handleSubmit', async () => {
+    const submit = createSuccessSubmit()
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { email: "test@example.com" },
+        defaultValues: { email: 'test@example.com' },
       }),
-    );
+    )
 
     await act(async () => {
-      await result.current.handleSubmit()();
-    });
+      await result.current.handleSubmit()()
+    })
 
     await waitFor(() => {
-      expect(submit).toHaveBeenCalledWith({ email: "test@example.com" });
-    });
-  });
+      expect(submit).toHaveBeenCalledWith({ email: 'test@example.com' })
+    })
+  })
 
-  it("sets isSubmitSuccessful after success", async () => {
-    const submit = createSuccessSubmit();
+  it('sets isSubmitSuccessful after success', async () => {
+    const submit = createSuccessSubmit()
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { name: "test" },
+        defaultValues: { name: 'test' },
       }),
-    );
+    )
 
     await act(async () => {
-      await result.current.handleSubmit()();
-    });
+      await result.current.handleSubmit()()
+    })
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(true);
-      expect(result.current.formState.lastResult).toEqual({ success: true, data: "ok" });
-    });
-  });
+      expect(result.current.formState.isSubmitSuccessful).toBe(true)
+      expect(result.current.formState.lastResult).toEqual({ success: true, data: 'ok' })
+    })
+  })
 
   // ---- Error handling -----------------------------------------------------
 
-  it("maps server errors to form fields", async () => {
-    const submit = createErrorSubmit();
+  it('maps server errors to form fields', async () => {
+    const submit = createErrorSubmit()
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { email: "" },
+        defaultValues: { email: '' },
       }),
-    );
+    )
 
     await act(async () => {
-      await result.current.handleSubmit()();
-    });
+      await result.current.handleSubmit()()
+    })
 
     await waitFor(() => {
       expect(result.current.formState.serverErrors).toEqual({
-        email: ["Invalid email address"],
-      });
-      expect(result.current.formState.isSubmitSuccessful).toBe(false);
-    });
-  });
-
-  it("handles thrown errors gracefully", async () => {
-    const submit = createThrowingSubmit();
-    const onError = vi.fn();
+        email: ['Invalid email address'],
+      })
+      expect(result.current.formState.isSubmitSuccessful).toBe(false)
+    })
+  })
+
+  it('handles thrown errors gracefully', async () => {
+    const submit = createThrowingSubmit()
+    const onError = vi.fn()
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { email: "" },
+        defaultValues: { email: '' },
         onError,
       }),
-    );
+    )
 
     await act(async () => {
-      await result.current.handleSubmit()();
-    });
+      await result.current.handleSubmit()()
+    })
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(false);
-      expect(onError).toHaveBeenCalled();
-    });
-  });
+      expect(result.current.formState.isSubmitSuccessful).toBe(false)
+      expect(onError).toHaveBeenCalled()
+    })
+  })
 
   // ---- Callbacks ----------------------------------------------------------
 
-  it("calls onSuccess callback", async () => {
-    const submit = createSuccessSubmit();
-    const onSuccess = vi.fn();
+  it('calls onSuccess callback', async () => {
+    const submit = createSuccessSubmit()
+    const onSuccess = vi.fn()
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { name: "test" },
+        defaultValues: { name: 'test' },
         onSuccess,
       }),
-    );
+    )
 
     await act(async () => {
-      await result.current.handleSubmit()();
-    });
+      await result.current.handleSubmit()()
+    })
 
     await waitFor(() => {
-      expect(onSuccess).toHaveBeenCalledWith({ success: true, data: "ok" });
-    });
-  });
+      expect(onSuccess).toHaveBeenCalledWith({ success: true, data: 'ok' })
+    })
+  })
 
-  it("calls onError callback on field errors", async () => {
-    const submit = createErrorSubmit();
-    const onError = vi.fn();
+  it('calls onError callback on field errors', async () => {
+    const submit = createErrorSubmit()
+    const onError = vi.fn()
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { email: "" },
+        defaultValues: { email: '' },
         onError,
       }),
-    );
+    )
 
     await act(async () => {
-      await result.current.handleSubmit()();
-    });
+      await result.current.handleSubmit()()
+    })
 
     await waitFor(() => {
-      expect(onError).toHaveBeenCalled();
-    });
-  });
+      expect(onError).toHaveBeenCalled()
+    })
+  })
 
   // ---- Persistence --------------------------------------------------------
 
-  it("persists values to sessionStorage", async () => {
-    const submit = createSuccessSubmit();
+  it('persists values to sessionStorage', async () => {
+    const submit = createSuccessSubmit()
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { email: "" },
-        persistKey: "test-core-form",
+        defaultValues: { email: '' },
+        persistKey: 'test-core-form',
         persistDebounce: 0,
       }),
-    );
+    )
 
     await act(async () => {
-      result.current.persist();
-    });
+      result.current.persist()
+    })
 
-    const stored = sessionStorage.getItem("test-core-form");
-    expect(stored).toBeTruthy();
-  });
+    const stored = sessionStorage.getItem('test-core-form')
+    expect(stored).toBeTruthy()
+  })
 
-  it("clears persisted data", async () => {
-    sessionStorage.setItem("test-core-clear", JSON.stringify({ email: "old@test.com" }));
+  it('clears persisted data', async () => {
+    sessionStorage.setItem('test-core-clear', JSON.stringify({ email: 'old@test.com' }))
 
-    const submit = createSuccessSubmit();
+    const submit = createSuccessSubmit()
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        persistKey: "test-core-clear",
+        persistKey: 'test-core-clear',
       }),
-    );
+    )
 
     await act(async () => {
-      result.current.clearPersisted();
-    });
+      result.current.clearPersisted()
+    })
 
-    expect(sessionStorage.getItem("test-core-clear")).toBeNull();
-  });
+    expect(sessionStorage.getItem('test-core-clear')).toBeNull()
+  })
 
   // ---- setServerError -----------------------------------------------------
 
-  it("allows manually setting a server error", async () => {
-    const submit = createSuccessSubmit();
+  it('allows manually setting a server error', async () => {
+    const submit = createSuccessSubmit()
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { email: "" },
+        defaultValues: { email: '' },
       }),
-    );
+    )
 
     act(() => {
-      result.current.setServerError("email", "Custom server error");
-    });
+      result.current.setServerError('email', 'Custom server error')
+    })
 
     await waitFor(() => {
-      const emailState = result.current.getFieldState("email");
-      expect(emailState.error?.message).toBe("Custom server error");
-      expect(emailState.error?.type).toBe("server");
-    });
-  });
+      const emailState = result.current.getFieldState('email')
+      expect(emailState.error?.message).toBe('Custom server error')
+      expect(emailState.error?.type).toBe('server')
+    })
+  })
 
   // ---- DevTools control metadata ------------------------------------------
 
-  it("exposes submission history on control for DevTools", async () => {
-    const submit = createSuccessSubmit();
+  it('exposes submission history on control for DevTools', async () => {
+    const submit = createSuccessSubmit()
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { name: "test" },
+        defaultValues: { name: 'test' },
       }),
-    );
+    )
 
     // Initially empty
-    expect(result.current.control._submissionHistory).toEqual([]);
+    expect(result.current.control._submissionHistory).toEqual([])
 
     await act(async () => {
-      await result.current.handleSubmit()();
-    });
+      await result.current.handleSubmit()()
+    })
 
     await waitFor(() => {
-      const history = result.current.control._submissionHistory;
-      expect(history).toBeDefined();
-      expect(history?.length).toBe(1);
-      expect(history?.[0]?.success).toBe(true);
-      expect(history?.[0]?.payload).toEqual({ name: "test" });
-    });
-  });
+      const history = result.current.control._submissionHistory
+      expect(history).toBeDefined()
+      expect(history?.length).toBe(1)
+      expect(history?.[0]?.success).toBe(true)
+      expect(history?.[0]?.payload).toEqual({ name: 'test' })
+    })
+  })
 
   // ---- Plugin lifecycle ---------------------------------------------------
 
-  it("calls plugin onBeforeSubmit and can prevent submission", async () => {
-    const submit = createSuccessSubmit();
-    const onBeforeSubmit = vi.fn().mockReturnValue(false);
+  it('calls plugin onBeforeSubmit and can prevent submission', async () => {
+    const submit = createSuccessSubmit()
+    const onBeforeSubmit = vi.fn().mockReturnValue(false)
 
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { name: "test" },
-        plugins: [{ name: "blocker", onBeforeSubmit }],
+        defaultValues: { name: 'test' },
+        plugins: [{ name: 'blocker', onBeforeSubmit }],
       }),
-    );
+    )
 
     await act(async () => {
-      await result.current.handleSubmit()();
-    });
+      await result.current.handleSubmit()()
+    })
 
     await waitFor(() => {
-      expect(onBeforeSubmit).toHaveBeenCalled();
-      expect(submit).not.toHaveBeenCalled();
-    });
-  });
+      expect(onBeforeSubmit).toHaveBeenCalled()
+      expect(submit).not.toHaveBeenCalled()
+    })
+  })
 
-  it("calls plugin onSuccess after successful submission", async () => {
-    const submit = createSuccessSubmit();
-    const pluginOnSuccess = vi.fn();
+  it('calls plugin onSuccess after successful submission', async () => {
+    const submit = createSuccessSubmit()
+    const pluginOnSuccess = vi.fn()
 
     const { result } = renderHook(() =>
       useActionFormCore(submit, {
-        defaultValues: { name: "test" },
-        plugins: [{ name: "logger", onSuccess: pluginOnSuccess }],
+        defaultValues: { name: 'test' },
+        plugins: [{ name: 'logger', onSuccess: pluginOnSuccess }],
       }),
-    );
+    )
 
     await act(async () => {
-      await result.current.handleSubmit()();
-    });
+      await result.current.handleSubmit()()
+    })
 
     await waitFor(() => {
-      expect(pluginOnSuccess).toHaveBeenCalledWith({ success: true, data: "ok" }, { name: "test" });
-    });
-  });
+      expect(pluginOnSuccess).toHaveBeenCalledWith({ success: true, data: 'ok' }, { name: 'test' })
+    })
+  })
 
-  it("calls plugin onMount and cleanup", () => {
-    const cleanup = vi.fn();
-    const onMount = vi.fn().mockReturnValue(cleanup);
-    const submit = createSuccessSubmit();
+  it('calls plugin onMount and cleanup', () => {
+    const cleanup = vi.fn()
+    const onMount = vi.fn().mockReturnValue(cleanup)
+    const submit = createSuccessSubmit()
 
     const { unmount } = renderHook(() =>
       useActionFormCore(submit, {
-        plugins: [{ name: "mounter", onMount }],
+        plugins: [{ name: 'mounter', onMount }],
       }),
-    );
+    )
 
-    expect(onMount).toHaveBeenCalled();
+    expect(onMount).toHaveBeenCalled()
 
-    unmount();
+    unmount()
 
-    expect(cleanup).toHaveBeenCalled();
-  });
-});
+    expect(cleanup).toHaveBeenCalled()
+  })
+})
diff --git a/packages/core/src/__tests__/use-action-form.test.ts b/packages/core/src/__tests__/use-action-form.test.ts
index 67ed55a..35d73ff 100644
--- a/packages/core/src/__tests__/use-action-form.test.ts
+++ b/packages/core/src/__tests__/use-action-form.test.ts
@@ -1,7 +1,7 @@
-import { act, renderHook, waitFor } from "@testing-library/react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { FormDataServerAction, JsonServerAction } from "../types";
-import { useActionForm } from "../use-action-form";
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { FormDataServerAction, JsonServerAction } from '../types'
+import { useActionForm } from '../use-action-form'
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -9,326 +9,327 @@ import { useActionForm } from "../use-action-form";
 
 /** Classic FormData action (arity 2) */
 function createSuccessAction(): FormDataServerAction<{ success: true; data: string }> {
-  return vi.fn(async (_prev: unknown, _fd: FormData) => ({ success: true as const, data: "ok" }));
+  return vi.fn(async (_prev: unknown, _fd: FormData) => ({ success: true as const, data: 'ok' }))
 }
 
 /** Classic FormData action that returns errors (arity 2) */
 function createErrorAction(): FormDataServerAction<{
-  errors: { email: string[]; name?: string[] };
+  errors: { email: string[]; name?: string[] }
 }> {
   return vi.fn(async (_prev: unknown, _fd: FormData) => ({
-    errors: { email: ["Invalid email address"], name: ["Name is required"] },
-  }));
+    errors: { email: ['Invalid email address'], name: ['Name is required'] },
+  }))
 }
 
 /** Classic FormData action that throws (arity 2) */
 function createThrowingAction(): FormDataServerAction<{ success: true }> {
   return vi.fn(async (_prev: unknown, _fd: FormData) => {
-    throw new Error("Network failure");
-  });
+    throw new Error('Network failure')
+  })
 }
 
 /** JSON action (arity 1) – success */
 function createJsonSuccessAction(): JsonServerAction<{ success: true; data: string }> {
-  return vi.fn(async (_data: unknown) => ({ success: true as const, data: "json-ok" }));
+  return vi.fn(async (_data: unknown) => ({ success: true as const, data: 'json-ok' }))
 }
 
 /** JSON action (arity 1) – returns errors */
 function createJsonErrorAction(): JsonServerAction<{
-  errors: { email: string[] };
+  errors: { email: string[] }
 }> {
   return vi.fn(async (_data: unknown) => ({
-    errors: { email: ["Invalid email from JSON action"] },
-  }));
+    errors: { email: ['Invalid email from JSON action'] },
+  }))
 }
 
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-describe("useActionForm", () => {
+describe('useActionForm', () => {
   beforeEach(() => {
-    sessionStorage.clear();
-  });
+    sessionStorage.clear()
+  })
 
   // ---- Basic rendering ----------------------------------------------------
 
-  it("returns all expected properties", () => {
-    const action = createSuccessAction();
-    const { result } = renderHook(() => useActionForm(action));
-
-    expect(result.current.register).toBeDefined();
-    expect(result.current.handleSubmit).toBeDefined();
-    expect(result.current.formState).toBeDefined();
-    expect(result.current.setServerError).toBeDefined();
-    expect(result.current.persist).toBeDefined();
-    expect(result.current.clearPersisted).toBeDefined();
-    expect(result.current.formAction).toBeDefined();
-  });
-
-  it("uses provided defaultValues", () => {
-    const action = createSuccessAction();
+  it('returns all expected properties', () => {
+    const action = createSuccessAction()
+    const { result } = renderHook(() => useActionForm(action))
+
+    expect(result.current.register).toBeDefined()
+    expect(result.current.handleSubmit).toBeDefined()
+    expect(result.current.formState).toBeDefined()
+    expect(result.current.setServerError).toBeDefined()
+    expect(result.current.persist).toBeDefined()
+    expect(result.current.clearPersisted).toBeDefined()
+    expect(result.current.formAction).toBeDefined()
+  })
+
+  it('uses provided defaultValues', () => {
+    const action = createSuccessAction()
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: "test@example.com" },
+        defaultValues: { email: 'test@example.com' },
       }),
-    );
+    )
 
-    expect(result.current.getValues("email")).toBe("test@example.com");
-  });
+    expect(result.current.getValues('email')).toBe('test@example.com')
+  })
 
   // ---- Successful submission ----------------------------------------------
 
-  it("submits successfully and updates action state", async () => {
-    const action = createSuccessAction();
-    const onSuccess = vi.fn();
+  it('submits successfully and updates action state', async () => {
+    const action = createSuccessAction()
+    const onSuccess = vi.fn()
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: "user@test.com" },
+        defaultValues: { email: 'user@test.com' },
         onSuccess,
       }),
-    );
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(true);
-      expect(result.current.formState.serverErrors).toBeNull();
+      expect(result.current.formState.isSubmitSuccessful).toBe(true)
+      expect(result.current.formState.serverErrors).toBeNull()
       expect(result.current.formState.lastResult).toEqual({
         success: true,
-        data: "ok",
-      });
-      expect(onSuccess).toHaveBeenCalledWith({ success: true, data: "ok" });
-    });
-  });
+        data: 'ok',
+      })
+      expect(onSuccess).toHaveBeenCalledWith({ success: true, data: 'ok' })
+    })
+  })
 
   // ---- Error mapping ------------------------------------------------------
 
-  it("maps server errors to RHF fields automatically", async () => {
-    const action = createErrorAction();
-    const onError = vi.fn();
+  it('maps server errors to RHF fields automatically', async () => {
+    const action = createErrorAction()
+    const onError = vi.fn()
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: "", name: "" },
+        defaultValues: { email: '', name: '' },
         onError,
       }),
-    );
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(false);
+      expect(result.current.formState.isSubmitSuccessful).toBe(false)
       expect(result.current.formState.serverErrors).toEqual({
-        email: ["Invalid email address"],
-        name: ["Name is required"],
-      });
+        email: ['Invalid email address'],
+        name: ['Name is required'],
+      })
       // Use getFieldState to check RHF errors (avoids proxy subscription issue in tests)
-      const emailState = result.current.getFieldState("email");
-      const nameState = result.current.getFieldState("name");
-      expect(emailState.error?.message).toBe("Invalid email address");
-      expect(nameState.error?.message).toBe("Name is required");
-      expect(onError).toHaveBeenCalled();
-    });
-  });
+      const emailState = result.current.getFieldState('email')
+      const nameState = result.current.getFieldState('name')
+      expect(emailState.error?.message).toBe('Invalid email address')
+      expect(nameState.error?.message).toBe('Name is required')
+      expect(onError).toHaveBeenCalled()
+    })
+  })
 
   // ---- setServerError -----------------------------------------------------
 
-  it("allows manually setting a server error", async () => {
-    const action = createSuccessAction();
-    const { result } = renderHook(() => useActionForm(action, { defaultValues: { email: "" } }));
+  it('allows manually setting a server error', async () => {
+    const action = createSuccessAction()
+    const { result } = renderHook(() => useActionForm(action, { defaultValues: { email: '' } }))
 
     act(() => {
-      result.current.setServerError("email", "Already taken");
-    });
+      result.current.setServerError('email', 'Already taken')
+    })
 
     await waitFor(() => {
-      const emailState = result.current.getFieldState("email");
-      expect(emailState.error?.message).toBe("Already taken");
-      expect(emailState.error?.type).toBe("server");
-    });
-  });
+      const emailState = result.current.getFieldState('email')
+      expect(emailState.error?.message).toBe('Already taken')
+      expect(emailState.error?.type).toBe('server')
+    })
+  })
 
   // ---- Throwing action ----------------------------------------------------
 
-  it("handles action that throws an error", async () => {
-    const action = createThrowingAction();
-    const onError = vi.fn();
+  it('handles action that throws an error', async () => {
+    const action = createThrowingAction()
+    const onError = vi.fn()
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: "" },
+        defaultValues: { email: '' },
         onError,
       }),
-    );
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(false);
-      expect(result.current.formState.isSubmitting).toBe(false);
-      expect(onError).toHaveBeenCalledWith(expect.any(Error));
-    });
-  });
+      expect(result.current.formState.isSubmitSuccessful).toBe(false)
+      expect(result.current.formState.isSubmitting).toBe(false)
+      expect(onError).toHaveBeenCalledWith(expect.any(Error))
+    })
+  })
 
   // ---- Custom error mapper ------------------------------------------------
 
-  it("supports custom error mapper", async () => {
-    const action: FormDataServerAction<{ validationErrors: { field: string; msg: string }[] }> = vi.fn(
-      async (_prev: unknown, _fd: FormData) => ({
-        validationErrors: [{ field: "email", msg: "Bad email" }],
-      }),
-    );
+  it('supports custom error mapper', async () => {
+    const action: FormDataServerAction<{ validationErrors: { field: string; msg: string }[] }> =
+      vi.fn(async (_prev: unknown, _fd: FormData) => ({
+        validationErrors: [{ field: 'email', msg: 'Bad email' }],
+      }))
 
     const { result } = renderHook(() =>
       useActionForm(action, {
-        defaultValues: { email: "" },
+        defaultValues: { email: '' },
         errorMapper: (res) => {
-          if ("validationErrors" in res && Array.isArray(res.validationErrors)) {
-            const errors: Record<string, string[]> = {};
+          if ('validationErrors' in res && Array.isArray(res.validationErrors)) {
+            const errors: Record<string, string[]> = {}
             for (const err of res.validationErrors) {
-              errors[err.field] = [err.msg];
+              errors[err.field] = [err.msg]
             }
-            return errors;
+            return errors
           }
-          return null;
+          return null
         },
       }),
-    );
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit();
-      await handler();
-    });
+      const handler = result.current.handleSubmit()
+      await handler()
+    })
 
     await waitFor(() => {
-      const emailState = result.current.getFieldState("email");
-      expect(emailState.error?.message).toBe("Bad email");
-    });
-  });
+      const emailState = result.current.getFieldState('email')
+      expect(emailState.error?.message).toBe('Bad email')
+    })
+  })
 
   // ---- onValid callback ---------------------------------------------------
 
-  it("calls onValid callback before submitting", async () => {
-    const action = createSuccessAction();
-    const onValid = vi.fn();
+  it('calls onValid callback before submitting', async () => {
+    const action = createSuccessAction()
+    const onValid = vi.fn()
 
-    const { result } = renderHook(() => useActionForm(action, { defaultValues: { email: "a@b.com" } }));
+    const { result } = renderHook(() =>
+      useActionForm(action, { defaultValues: { email: 'a@b.com' } }),
+    )
 
     await act(async () => {
-      const handler = result.current.handleSubmit(onValid);
-      await handler();
-    });
+      const handler = result.current.handleSubmit(onValid)
+      await handler()
+    })
 
-    expect(onValid).toHaveBeenCalledWith({ email: "a@b.com" });
-    expect(action).toHaveBeenCalled();
-  });
+    expect(onValid).toHaveBeenCalledWith({ email: 'a@b.com' })
+    expect(action).toHaveBeenCalled()
+  })
 
   // ---- formAction ---------------------------------------------------------
 
-  it("formAction submits directly with FormData", async () => {
-    const action = createSuccessAction();
-    const { result } = renderHook(() => useActionForm(action));
+  it('formAction submits directly with FormData', async () => {
+    const action = createSuccessAction()
+    const { result } = renderHook(() => useActionForm(action))
 
-    const fd = new FormData();
-    fd.append("email", "direct@test.com");
+    const fd = new FormData()
+    fd.append('email', 'direct@test.com')
 
     await act(async () => {
-      await result.current.formAction(fd);
-    });
+      await result.current.formAction(fd)
+    })
 
     await waitFor(() => {
-      expect(action).toHaveBeenCalledWith(null, fd);
-      expect(result.current.formState.isSubmitSuccessful).toBe(true);
-    });
-  });
+      expect(action).toHaveBeenCalledWith(null, fd)
+      expect(result.current.formState.isSubmitSuccessful).toBe(true)
+    })
+  })
 
   // =========================================================================
   // JSON action tests (arity 1)
   // =========================================================================
 
-  describe("JSON actions (arity 1)", () => {
-    it("submits successfully with a JSON action", async () => {
-      const action = createJsonSuccessAction();
-      const onSuccess = vi.fn();
+  describe('JSON actions (arity 1)', () => {
+    it('submits successfully with a JSON action', async () => {
+      const action = createJsonSuccessAction()
+      const onSuccess = vi.fn()
 
       const { result } = renderHook(() =>
         useActionForm(action, {
-          defaultValues: { email: "json@test.com" },
+          defaultValues: { email: 'json@test.com' },
           onSuccess,
         }),
-      );
+      )
 
       await act(async () => {
-        const handler = result.current.handleSubmit();
-        await handler();
-      });
+        const handler = result.current.handleSubmit()
+        await handler()
+      })
 
       await waitFor(() => {
-        expect(result.current.formState.isSubmitSuccessful).toBe(true);
+        expect(result.current.formState.isSubmitSuccessful).toBe(true)
         expect(result.current.formState.lastResult).toEqual({
           success: true,
-          data: "json-ok",
-        });
-        expect(onSuccess).toHaveBeenCalledWith({ success: true, data: "json-ok" });
+          data: 'json-ok',
+        })
+        expect(onSuccess).toHaveBeenCalledWith({ success: true, data: 'json-ok' })
         // The action should have been called with a plain object, NOT FormData
-        expect(action).toHaveBeenCalledWith({ email: "json@test.com" });
-      });
-    });
+        expect(action).toHaveBeenCalledWith({ email: 'json@test.com' })
+      })
+    })
 
-    it("maps errors from a JSON action to RHF fields", async () => {
-      const action = createJsonErrorAction();
-      const onError = vi.fn();
+    it('maps errors from a JSON action to RHF fields', async () => {
+      const action = createJsonErrorAction()
+      const onError = vi.fn()
 
       const { result } = renderHook(() =>
         useActionForm(action, {
-          defaultValues: { email: "" },
+          defaultValues: { email: '' },
           onError,
         }),
-      );
+      )
 
       await act(async () => {
-        const handler = result.current.handleSubmit();
-        await handler();
-      });
+        const handler = result.current.handleSubmit()
+        await handler()
+      })
 
       await waitFor(() => {
-        expect(result.current.formState.isSubmitSuccessful).toBe(false);
+        expect(result.current.formState.isSubmitSuccessful).toBe(false)
         expect(result.current.formState.serverErrors).toEqual({
-          email: ["Invalid email from JSON action"],
-        });
-        const emailState = result.current.getFieldState("email");
-        expect(emailState.error?.message).toBe("Invalid email from JSON action");
-        expect(onError).toHaveBeenCalled();
-      });
-    });
+          email: ['Invalid email from JSON action'],
+        })
+        const emailState = result.current.getFieldState('email')
+        expect(emailState.error?.message).toBe('Invalid email from JSON action')
+        expect(onError).toHaveBeenCalled()
+      })
+    })
 
-    it("formAction converts FormData to object for JSON actions", async () => {
-      const action = createJsonSuccessAction();
-      const { result } = renderHook(() => useActionForm(action));
+    it('formAction converts FormData to object for JSON actions', async () => {
+      const action = createJsonSuccessAction()
+      const { result } = renderHook(() => useActionForm(action))
 
-      const fd = new FormData();
-      fd.append("email", "fd-to-json@test.com");
+      const fd = new FormData()
+      fd.append('email', 'fd-to-json@test.com')
 
       await act(async () => {
-        await result.current.formAction(fd);
-      });
+        await result.current.formAction(fd)
+      })
 
       await waitFor(() => {
         // JSON action should receive a plain object, not FormData
-        expect(action).toHaveBeenCalledWith({ email: "fd-to-json@test.com" });
-        expect(result.current.formState.isSubmitSuccessful).toBe(true);
-      });
-    });
-  });
-});
+        expect(action).toHaveBeenCalledWith({ email: 'fd-to-json@test.com' })
+        expect(result.current.formState.isSubmitSuccessful).toBe(true)
+      })
+    })
+  })
+})
diff --git a/packages/core/src/core-types.ts b/packages/core/src/core-types.ts
index 8e2a418..e423c22 100644
--- a/packages/core/src/core-types.ts
+++ b/packages/core/src/core-types.ts
@@ -1,5 +1,5 @@
-import type { DefaultValues, FieldValues, Mode, UseFormReturn } from "react-hook-form";
-import type { ZodSchema } from "zod";
+import type { DefaultValues, FieldValues, Mode, UseFormReturn } from 'react-hook-form'
+import type { ZodSchema } from 'zod'
 
 // ---------------------------------------------------------------------------
 // Field-level error shape (Zod `.flatten().fieldErrors` compatible)
@@ -9,7 +9,7 @@ import type { ZodSchema } from "zod";
  * Record mapping field names to arrays of error messages.
  * This is the shape produced by `ZodError.flatten().fieldErrors`.
  */
-export type FieldErrorRecord = Record<string, string[] | undefined>;
+export type FieldErrorRecord = Record<string, string[] | undefined>
 
 // ---------------------------------------------------------------------------
 // Default action result shape
@@ -19,10 +19,10 @@ export type FieldErrorRecord = Record<string, string[] | undefined>;
  * Standard result type from an action that uses Zod validation.
  */
 export interface ActionResult<TData = unknown> {
-  success?: boolean;
-  errors?: FieldErrorRecord;
-  data?: TData;
-  message?: string;
+  success?: boolean
+  errors?: FieldErrorRecord
+  data?: TData
+  message?: string
 }
 
 // ---------------------------------------------------------------------------
@@ -33,7 +33,7 @@ export interface ActionResult<TData = unknown> {
  * A function that takes the raw action result and extracts field errors.
  * Return `null` or `undefined` if there are no errors.
  */
-export type ErrorMapper<TResult> = (result: TResult) => FieldErrorRecord | null | undefined;
+export type ErrorMapper<TResult> = (result: TResult) => FieldErrorRecord | null | undefined
 
 /**
  * Default error mapper that works with the standard Zod flatten format:
@@ -42,14 +42,14 @@ export type ErrorMapper<TResult> = (result: TResult) => FieldErrorRecord | null
 export function defaultErrorMapper<TResult>(result: TResult): FieldErrorRecord | null | undefined {
   if (
     result &&
-    typeof result === "object" &&
-    "errors" in result &&
+    typeof result === 'object' &&
+    'errors' in result &&
     result.errors &&
-    typeof result.errors === "object"
+    typeof result.errors === 'object'
   ) {
-    return result.errors as FieldErrorRecord;
+    return result.errors as FieldErrorRecord
   }
-  return null;
+  return null
 }
 
 // ---------------------------------------------------------------------------
@@ -62,7 +62,7 @@ export function defaultErrorMapper<TResult>(result: TResult): FieldErrorRecord |
  * - `'onChange'` – validate on every field change
  * - `'onBlur'`  – validate when a field loses focus
  */
-export type ClientValidationMode = "onSubmit" | "onChange" | "onBlur";
+export type ClientValidationMode = 'onSubmit' | 'onChange' | 'onBlur'
 
 // ---------------------------------------------------------------------------
 // Optimistic UI types
@@ -76,7 +76,7 @@ export type ClientValidationMode = "onSubmit" | "onChange" | "onBlur";
 export type OptimisticReducer<TOptimistic, TFieldValues extends FieldValues = FieldValues> = (
   currentData: TOptimistic,
   formValues: TFieldValues,
-) => TOptimistic;
+) => TOptimistic
 
 /**
  * The optimistic state object returned by the hook when
@@ -84,11 +84,11 @@ export type OptimisticReducer<TOptimistic, TFieldValues extends FieldValues = Fi
  */
 export interface OptimisticState<TOptimistic> {
   /** The current optimistic data (updated instantly on submit). */
-  data: TOptimistic;
+  data: TOptimistic
   /** Whether an optimistic update is pending (action in flight). */
-  isPending: boolean;
+  isPending: boolean
   /** Manually revert to the last confirmed state. */
-  rollback: () => void;
+  rollback: () => void
 }
 
 // ---------------------------------------------------------------------------
@@ -99,7 +99,9 @@ export interface OptimisticState<TOptimistic> {
  * A generic async submit function. Adapters (Next.js, standalone, etc.)
  * are responsible for wrapping their specific action into this shape.
  */
-export type SubmitFunction<TFieldValues extends FieldValues, TResult> = (data: TFieldValues) => Promise<TResult>;
+export type SubmitFunction<TFieldValues extends FieldValues, TResult> = (
+  data: TFieldValues,
+) => Promise<TResult>
 
 // ---------------------------------------------------------------------------
 // Plugin interface (internal, v3)
@@ -109,17 +111,20 @@ export type SubmitFunction<TFieldValues extends FieldValues, TResult> = (data: T
  * Internal plugin interface for extending useActionFormCore behavior.
  * Not part of the public API yet — used for internal composition.
  */
-export interface ActionFormPlugin<TFieldValues extends FieldValues = FieldValues, TResult = ActionResult> {
+export interface ActionFormPlugin<
+  TFieldValues extends FieldValues = FieldValues,
+  TResult = ActionResult,
+> {
   /** Unique name for debugging */
-  name: string;
+  name: string
   /** Called before submit. Return false to prevent submission. */
-  onBeforeSubmit?: (data: TFieldValues) => boolean | Promise<boolean>;
+  onBeforeSubmit?: (data: TFieldValues) => boolean | Promise<boolean>
   /** Called after a successful submission. */
-  onSuccess?: (result: TResult, data: TFieldValues) => void;
+  onSuccess?: (result: TResult, data: TFieldValues) => void
   /** Called after a failed submission. */
-  onError?: (error: TResult | Error, data: TFieldValues) => void;
+  onError?: (error: TResult | Error, data: TFieldValues) => void
   /** Called on mount. Return a cleanup function. */
-  onMount?: () => (() => void) | undefined;
+  onMount?: () => (() => void) | undefined
 }
 
 // ---------------------------------------------------------------------------
@@ -136,41 +141,41 @@ export interface UseActionFormCoreOptions<
    * If `persistKey` is provided and stored data exists, persisted values
    * take precedence.
    */
-  defaultValues?: DefaultValues<TFieldValues>;
+  defaultValues?: DefaultValues<TFieldValues>
 
   /**
    * Validation mode passed to React Hook Form.
    * @default 'onSubmit'
    */
-  mode?: Mode;
+  mode?: Mode
 
   /**
    * When provided, enables transparent sessionStorage persistence.
    * The form state is saved under this key and restored on mount.
    */
-  persistKey?: string;
+  persistKey?: string
 
   /**
    * Custom function to extract field errors from the action result.
    * By default supports the Zod `.flatten().fieldErrors` format.
    */
-  errorMapper?: ErrorMapper<TResult>;
+  errorMapper?: ErrorMapper<TResult>
 
   /**
    * Callback fired after a successful submission (no field errors returned).
    */
-  onSuccess?: (result: TResult) => void;
+  onSuccess?: (result: TResult) => void
 
   /**
    * Callback fired when the action throws or returns field errors.
    */
-  onError?: (result: TResult | Error) => void;
+  onError?: (result: TResult | Error) => void
 
   /**
    * Debounce interval (ms) for sessionStorage persistence.
    * @default 300
    */
-  persistDebounce?: number;
+  persistDebounce?: number
 
   // ---- Client-side Zod validation -----------------------------------------
 
@@ -178,49 +183,49 @@ export interface UseActionFormCoreOptions<
    * Zod schema for client-side validation.
    * If provided, fields are validated in real-time (based on `validationMode`).
    */
-  schema?: ZodSchema;
+  schema?: ZodSchema
 
   /**
    * Controls when client-side Zod schema validation runs.
    * Only takes effect when `schema` is provided.
    * @default 'onSubmit'
    */
-  validationMode?: ClientValidationMode;
+  validationMode?: ClientValidationMode
 
   /**
    * Alias for `validationMode`.
    * @deprecated Use `validationMode` instead.
    */
-  clientValidation?: ClientValidationMode;
+  clientValidation?: ClientValidationMode
 
   // ---- Optimistic UI ------------------------------------------------------
 
   /**
    * Optional key used to enable optimistic UI mode and identify optimistic data.
    */
-  optimisticKey?: string;
+  optimisticKey?: string
 
   /**
    * Reducer that computes optimistic data from current data + submitted values.
    */
-  optimisticData?: OptimisticReducer<TOptimistic, TFieldValues>;
+  optimisticData?: OptimisticReducer<TOptimistic, TFieldValues>
 
   /**
    * Initial (confirmed) data used by optimistic mode.
    */
-  optimisticInitial?: TOptimistic;
+  optimisticInitial?: TOptimistic
 
   /**
    * Alias for `optimisticData`.
    * @deprecated Use `optimisticData` instead.
    */
-  optimisticReducer?: OptimisticReducer<TOptimistic, TFieldValues>;
+  optimisticReducer?: OptimisticReducer<TOptimistic, TFieldValues>
 
   /**
    * Alias for `optimisticInitial`.
    * @deprecated Use `optimisticInitial` instead.
    */
-  optimisticDefault?: TOptimistic;
+  optimisticDefault?: TOptimistic
 
   // ---- Internal plugins (v3) ----------------------------------------------
 
@@ -228,7 +233,7 @@ export interface UseActionFormCoreOptions<
    * Internal plugin array. Not part of the public API yet.
    * @internal
    */
-  plugins?: ActionFormPlugin<TFieldValues, TResult>[];
+  plugins?: ActionFormPlugin<TFieldValues, TResult>[]
 }
 
 // ---------------------------------------------------------------------------
@@ -237,27 +242,27 @@ export interface UseActionFormCoreOptions<
 
 export interface ActionFormState<TResult> {
   /** Whether the form is currently being submitted. */
-  isSubmitting: boolean;
+  isSubmitting: boolean
   /** Whether the last submission was successful (no field errors). */
-  isSubmitSuccessful: boolean;
+  isSubmitSuccessful: boolean
   /** Raw error record returned by the action (via errorMapper). */
-  submitErrors: FieldErrorRecord | null;
+  submitErrors: FieldErrorRecord | null
   /** Full result from the last action invocation, if any. */
-  actionResult: TResult | null;
+  actionResult: TResult | null
   /**
    * Alias for `submitErrors`.
    * @deprecated Use `submitErrors` instead.
    */
-  serverErrors: FieldErrorRecord | null;
+  serverErrors: FieldErrorRecord | null
   /**
    * Alias for `actionResult`.
    * @deprecated Use `actionResult` instead.
    */
-  lastResult: TResult | null;
+  lastResult: TResult | null
   /**
    * `true` while a transition is pending.
    */
-  isPending: boolean;
+  isPending: boolean
 }
 
 // ---------------------------------------------------------------------------
@@ -268,7 +273,7 @@ export interface UseActionFormCoreReturn<
   TFieldValues extends FieldValues = FieldValues,
   TResult = ActionResult,
   TOptimistic = undefined,
-> extends Omit<UseFormReturn<TFieldValues>, "handleSubmit"> {
+> extends Omit<UseFormReturn<TFieldValues>, 'handleSubmit'> {
   /**
    * Enhanced handleSubmit that submits via the provided submit function.
    * Call with no arguments: `onSubmit={handleSubmit()}`.
@@ -276,58 +281,58 @@ export interface UseActionFormCoreReturn<
    */
   handleSubmit: (
     onValid?: (data: TFieldValues) => void | Promise<void>,
-  ) => (e?: React.BaseSyntheticEvent) => Promise<void>;
+  ) => (e?: React.BaseSyntheticEvent) => Promise<void>
 
   /**
    * Extended form state including action status.
    */
-  formState: UseFormReturn<TFieldValues>["formState"] & ActionFormState<TResult>;
+  formState: UseFormReturn<TFieldValues>['formState'] & ActionFormState<TResult>
 
   /**
    * Manually set a server-side error on a specific field.
    */
-  setSubmitError: (field: keyof TFieldValues & string, message: string) => void;
+  setSubmitError: (field: keyof TFieldValues & string, message: string) => void
 
   /**
    * Alias for `setSubmitError`.
    * @deprecated Use `setSubmitError` instead.
    */
-  setServerError: (field: keyof TFieldValues & string, message: string) => void;
+  setServerError: (field: keyof TFieldValues & string, message: string) => void
 
   /**
    * Manually persist the current form state to sessionStorage.
    * Only works when `persistKey` is set.
    */
-  persist: () => void;
+  persist: () => void
 
   /**
    * Clear persisted data from sessionStorage.
    * Only works when `persistKey` is set.
    */
-  clearPersistedData: () => void;
+  clearPersistedData: () => void
 
   /**
    * Alias for `clearPersistedData`.
    * @deprecated Use `clearPersistedData` instead.
    */
-  clearPersisted: () => void;
+  clearPersisted: () => void
 
   /**
    * Optimistic state. Only populated when `optimisticKey` is provided.
    * Contains `data`, `isPending`, and `rollback()`.
    */
-  optimistic: TOptimistic extends undefined ? undefined : OptimisticState<TOptimistic>;
+  optimistic: TOptimistic extends undefined ? undefined : OptimisticState<TOptimistic>
 
   /**
    * A control object that exposes internals for DevTools.
    * @internal
    */
-  control: UseFormReturn<TFieldValues>["control"] & {
+  control: UseFormReturn<TFieldValues>['control'] & {
     /** Submission history for DevTools inspection. */
-    _submissionHistory?: SubmissionRecord<TResult>[];
+    _submissionHistory?: SubmissionRecord<TResult>[]
     /** The core action form state. */
-    _actionFormState?: ActionFormState<TResult>;
-  };
+    _actionFormState?: ActionFormState<TResult>
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -336,17 +341,17 @@ export interface UseActionFormCoreReturn<
 
 export interface SubmissionRecord<TResult> {
   /** Unique ID for this submission */
-  id: string;
+  id: string
   /** Timestamp of submission */
-  timestamp: number;
+  timestamp: number
   /** The payload sent */
-  payload: Record<string, unknown>;
+  payload: Record<string, unknown>
   /** The response from the action */
-  response: TResult | null;
+  response: TResult | null
   /** Error, if any */
-  error: Error | null;
+  error: Error | null
   /** Duration in ms */
-  duration: number;
+  duration: number
   /** Whether the submission was successful */
-  success: boolean;
+  success: boolean
 }
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
index 19668d4..b0aaa0d 100644
--- a/packages/core/src/types.ts
+++ b/packages/core/src/types.ts
@@ -1,5 +1,5 @@
-import type { DefaultValues, FieldValues, Mode, UseFormReturn } from "react-hook-form";
-import type { ZodSchema } from "zod";
+import type { DefaultValues, FieldValues, Mode, UseFormReturn } from 'react-hook-form'
+import type { ZodSchema } from 'zod'
 
 // ---------------------------------------------------------------------------
 // Server Action type – supports both Next.js App Router conventions:
@@ -10,7 +10,7 @@ import type { ZodSchema } from "zod";
 /**
  * A Server Action that receives a single JSON payload and returns a promise.
  */
-export type JsonServerAction<TResult = unknown> = (data: unknown) => Promise<TResult>;
+export type JsonServerAction<TResult = unknown> = (data: unknown) => Promise<TResult>
 
 /**
  * A Server Action that receives the previous state and a FormData.
@@ -19,23 +19,28 @@ export type JsonServerAction<TResult = unknown> = (data: unknown) => Promise<TRe
 export type FormDataServerAction<TResult = unknown> = (
   prevState: Awaited<TResult> | null,
   formData: FormData,
-) => Promise<TResult>;
+) => Promise<TResult>
 
 /**
  * Represents a Next.js Server Action function signature.
  * Supports both the classic (prevState, formData) signature and the
  * simpler (data) => Promise signature for JSON-based actions.
  */
-export type ServerAction<TResult = unknown> = JsonServerAction<TResult> | FormDataServerAction<TResult>;
+export type ServerAction<TResult = unknown> =
+  | JsonServerAction<TResult>
+  | FormDataServerAction<TResult>
 
 /**
  * A Server Action created with `withZod` that has the schema attached.
  * This allows `useActionForm` to automatically infer the schema for
  * client-side validation.
  */
-export type ZodServerAction<TSchema extends ZodSchema = ZodSchema, TResult = unknown> = ServerAction<TResult> & {
-  __schema: TSchema;
-};
+export type ZodServerAction<
+  TSchema extends ZodSchema = ZodSchema,
+  TResult = unknown,
+> = ServerAction<TResult> & {
+  __schema: TSchema
+}
 
 // ---------------------------------------------------------------------------
 // Infer the result type of a Server Action
@@ -47,8 +52,8 @@ export type ZodServerAction<TSchema extends ZodSchema = ZodSchema, TResult = unk
 export type InferActionResult<TAction> = TAction extends JsonServerAction<infer R>
   ? Awaited<R>
   : TAction extends FormDataServerAction<infer R>
-  ? Awaited<R>
-  : never;
+    ? Awaited<R>
+    : never
 
 // ---------------------------------------------------------------------------
 // Standard field-level error shape returned by Zod `.flatten().fieldErrors`
@@ -58,7 +63,7 @@ export type InferActionResult<TAction> = TAction extends JsonServerAction<infer
  * Record mapping field names to arrays of error messages.
  * This is the shape produced by `ZodError.flatten().fieldErrors`.
  */
-export type FieldErrorRecord = Record<string, string[] | undefined>;
+export type FieldErrorRecord = Record<string, string[] | undefined>
 
 // ---------------------------------------------------------------------------
 // Default action result shape (what most Server Actions return)
@@ -68,10 +73,10 @@ export type FieldErrorRecord = Record<string, string[] | undefined>;
  * Standard result type from a Server Action that uses Zod validation.
  */
 export interface ActionResult<TData = unknown> {
-  success?: boolean;
-  errors?: FieldErrorRecord;
-  data?: TData;
-  message?: string;
+  success?: boolean
+  errors?: FieldErrorRecord
+  data?: TData
+  message?: string
 }
 
 // ---------------------------------------------------------------------------
@@ -82,14 +87,16 @@ export interface ActionResult<TData = unknown> {
  * A function that takes the raw action result and extracts field errors.
  * Return `null` or `undefined` if there are no errors.
  */
-export type ErrorMapper<TResult> = (result: TResult) => FieldErrorRecord | null | undefined;
+export type ErrorMapper<TResult> = (result: TResult) => FieldErrorRecord | null | undefined
 
 /**
  * Detect whether a Server Action uses the FormData signature (arity === 2)
  * or the JSON signature (arity <= 1).
  */
-export function isFormDataAction<TResult>(action: ServerAction<TResult>): action is FormDataServerAction<TResult> {
-  return action.length >= 2;
+export function isFormDataAction<TResult>(
+  action: ServerAction<TResult>,
+): action is FormDataServerAction<TResult> {
+  return action.length >= 2
 }
 
 /**
@@ -99,14 +106,14 @@ export function isFormDataAction<TResult>(action: ServerAction<TResult>): action
 export function defaultErrorMapper<TResult>(result: TResult): FieldErrorRecord | null | undefined {
   if (
     result &&
-    typeof result === "object" &&
-    "errors" in result &&
+    typeof result === 'object' &&
+    'errors' in result &&
     result.errors &&
-    typeof result.errors === "object"
+    typeof result.errors === 'object'
   ) {
-    return result.errors as FieldErrorRecord;
+    return result.errors as FieldErrorRecord
   }
-  return null;
+  return null
 }
 
 /**
@@ -116,7 +123,7 @@ export function defaultErrorMapper<TResult>(result: TResult): FieldErrorRecord |
 export function hasAttachedSchema<TResult>(
   action: ServerAction<TResult>,
 ): action is ZodServerAction<ZodSchema, TResult> {
-  return "__schema" in action && (action as unknown as Record<string, unknown>).__schema != null;
+  return '__schema' in action && (action as unknown as Record<string, unknown>).__schema != null
 }
 
 // ---------------------------------------------------------------------------
@@ -129,7 +136,7 @@ export function hasAttachedSchema<TResult>(
  * - `'onChange'` – validate on every field change
  * - `'onBlur'`  – validate when a field loses focus
  */
-export type ClientValidationMode = "onSubmit" | "onChange" | "onBlur";
+export type ClientValidationMode = 'onSubmit' | 'onChange' | 'onBlur'
 
 // ---------------------------------------------------------------------------
 // Optimistic UI types
@@ -143,7 +150,7 @@ export type ClientValidationMode = "onSubmit" | "onChange" | "onBlur";
 export type OptimisticReducer<TOptimistic, TFieldValues extends FieldValues = FieldValues> = (
   currentData: TOptimistic,
   formValues: TFieldValues,
-) => TOptimistic;
+) => TOptimistic
 
 /**
  * The optimistic state object returned by `useActionForm` when
@@ -151,11 +158,11 @@ export type OptimisticReducer<TOptimistic, TFieldValues extends FieldValues = Fi
  */
 export interface OptimisticState<TOptimistic> {
   /** The current optimistic data (updated instantly on submit). */
-  data: TOptimistic;
+  data: TOptimistic
   /** Whether an optimistic update is pending (action in flight). */
-  isPending: boolean;
+  isPending: boolean
   /** Manually revert to the last confirmed state. */
-  rollback: () => void;
+  rollback: () => void
 }
 
 // ---------------------------------------------------------------------------
@@ -172,41 +179,41 @@ export interface UseActionFormOptions<
    * If `persistKey` is provided and stored data exists, persisted values
    * take precedence.
    */
-  defaultValues?: DefaultValues<TFieldValues>;
+  defaultValues?: DefaultValues<TFieldValues>
 
   /**
    * Validation mode passed to React Hook Form.
    * @default 'onSubmit'
    */
-  mode?: Mode;
+  mode?: Mode
 
   /**
    * When provided, enables transparent sessionStorage persistence.
    * The form state is saved under this key and restored on mount.
    */
-  persistKey?: string;
+  persistKey?: string
 
   /**
    * Custom function to extract field errors from the action result.
    * By default supports the Zod `.flatten().fieldErrors` format.
    */
-  errorMapper?: ErrorMapper<TResult>;
+  errorMapper?: ErrorMapper<TResult>
 
   /**
    * Callback fired after a successful submission (no field errors returned).
    */
-  onSuccess?: (result: TResult) => void;
+  onSuccess?: (result: TResult) => void
 
   /**
    * Callback fired when the action throws or returns field errors.
    */
-  onError?: (result: TResult | Error) => void;
+  onError?: (result: TResult | Error) => void
 
   /**
    * Debounce interval (ms) for sessionStorage persistence.
    * @default 300
    */
-  persistDebounce?: number;
+  persistDebounce?: number
 
   // ---- v2: Client-side Zod validation -------------------------------------
 
@@ -215,49 +222,49 @@ export interface UseActionFormOptions<
    * If provided, fields are validated in real-time (based on `validationMode`).
    * If the action was created with `withZod`, the schema is auto-detected.
    */
-  schema?: ZodSchema;
+  schema?: ZodSchema
 
   /**
    * Controls when client-side Zod schema validation runs.
    * Only takes effect when `schema` is provided (or inferred from `withZod`).
    * @default 'onSubmit'
    */
-  validationMode?: ClientValidationMode;
+  validationMode?: ClientValidationMode
 
   /**
    * Alias for `validationMode`.
    * @deprecated Use `validationMode` instead.
    */
-  clientValidation?: ClientValidationMode;
+  clientValidation?: ClientValidationMode
 
   // ---- v2: Optimistic UI --------------------------------------------------
 
   /**
    * Optional key used to enable optimistic UI mode and identify optimistic data.
    */
-  optimisticKey?: string;
+  optimisticKey?: string
 
   /**
    * Reducer that computes optimistic data from current data + submitted values.
    */
-  optimisticData?: OptimisticReducer<TOptimistic, TFieldValues>;
+  optimisticData?: OptimisticReducer<TOptimistic, TFieldValues>
 
   /**
    * Initial (confirmed) data used by optimistic mode.
    */
-  optimisticInitial?: TOptimistic;
+  optimisticInitial?: TOptimistic
 
   /**
    * Alias for `optimisticData`.
    * @deprecated Use `optimisticData` instead.
    */
-  optimisticReducer?: OptimisticReducer<TOptimistic, TFieldValues>;
+  optimisticReducer?: OptimisticReducer<TOptimistic, TFieldValues>
 
   /**
    * Alias for `optimisticInitial`.
    * @deprecated Use `optimisticInitial` instead.
    */
-  optimisticDefault?: TOptimistic;
+  optimisticDefault?: TOptimistic
 }
 
 // ---------------------------------------------------------------------------
@@ -266,28 +273,28 @@ export interface UseActionFormOptions<
 
 export interface ActionFormState<TResult> {
   /** Whether the form is currently being submitted to the server action. */
-  isSubmitting: boolean;
+  isSubmitting: boolean
   /** Whether the last submission was successful (no field errors). */
-  isSubmitSuccessful: boolean;
+  isSubmitSuccessful: boolean
   /** Raw error record returned by the server action (via errorMapper). */
-  submitErrors: FieldErrorRecord | null;
+  submitErrors: FieldErrorRecord | null
   /** Full result from the last action invocation, if any. */
-  actionResult: TResult | null;
+  actionResult: TResult | null
   /**
    * Alias for `submitErrors`.
    * @deprecated Use `submitErrors` instead.
    */
-  serverErrors: FieldErrorRecord | null;
+  serverErrors: FieldErrorRecord | null
   /**
    * Alias for `actionResult`.
    * @deprecated Use `actionResult` instead.
    */
-  lastResult: TResult | null;
+  lastResult: TResult | null
   /**
    * `true` while a transition is pending (React 19 `useTransition`).
    * Falls back to `isSubmitting` on React 18.
    */
-  isPending: boolean;
+  isPending: boolean
 }
 
 // ---------------------------------------------------------------------------
@@ -298,7 +305,7 @@ export interface UseActionFormReturn<
   TFieldValues extends FieldValues = FieldValues,
   TResult = ActionResult,
   TOptimistic = undefined,
-> extends Omit<UseFormReturn<TFieldValues>, "handleSubmit"> {
+> extends Omit<UseFormReturn<TFieldValues>, 'handleSubmit'> {
   /**
    * Enhanced handleSubmit that submits to the Server Action.
    * Call with no arguments: `onSubmit={handleSubmit()}`.
@@ -306,50 +313,50 @@ export interface UseActionFormReturn<
    */
   handleSubmit: (
     onValid?: (data: TFieldValues) => void | Promise<void>,
-  ) => (e?: React.BaseSyntheticEvent) => Promise<void>;
+  ) => (e?: React.BaseSyntheticEvent) => Promise<void>
 
   /**
    * Extended form state including server action status.
    */
-  formState: UseFormReturn<TFieldValues>["formState"] & ActionFormState<TResult>;
+  formState: UseFormReturn<TFieldValues>['formState'] & ActionFormState<TResult>
 
   /**
    * Manually set a server-side error on a specific field.
    */
-  setSubmitError: (field: keyof TFieldValues & string, message: string) => void;
+  setSubmitError: (field: keyof TFieldValues & string, message: string) => void
 
   /**
    * Alias for `setSubmitError`.
    * @deprecated Use `setSubmitError` instead.
    */
-  setServerError: (field: keyof TFieldValues & string, message: string) => void;
+  setServerError: (field: keyof TFieldValues & string, message: string) => void
 
   /**
    * Manually persist the current form state to sessionStorage.
    * Only works when `persistKey` is set.
    */
-  persist: () => void;
+  persist: () => void
 
   /**
    * Clear persisted data from sessionStorage.
    * Only works when `persistKey` is set.
    */
-  clearPersistedData: () => void;
+  clearPersistedData: () => void
 
   /**
    * Alias for `clearPersistedData`.
    * @deprecated Use `clearPersistedData` instead.
    */
-  clearPersisted: () => void;
+  clearPersisted: () => void
 
   /**
    * The underlying form action compatible with Next.js `<form action={…}>`.
    */
-  formAction: (formData: FormData) => Promise<void>;
+  formAction: (formData: FormData) => Promise<void>
 
   /**
    * Optimistic state (v2). Only populated when `optimisticKey` is provided.
    * Contains `data`, `isPending`, and `rollback()`.
    */
-  optimistic: TOptimistic extends undefined ? undefined : OptimisticState<TOptimistic>;
+  optimistic: TOptimistic extends undefined ? undefined : OptimisticState<TOptimistic>
 }
diff --git a/packages/core/src/use-action-form-core.ts b/packages/core/src/use-action-form-core.ts
index 53666f5..dc1f8e2 100644
--- a/packages/core/src/use-action-form-core.ts
+++ b/packages/core/src/use-action-form-core.ts
@@ -1,8 +1,8 @@
-"use client";
+'use client'
 
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { type DefaultValues, type FieldPath, type FieldValues, useForm } from "react-hook-form";
-import type { ZodError, ZodSchema } from "zod";
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { type DefaultValues, type FieldPath, type FieldValues, useForm } from 'react-hook-form'
+import type { ZodError, ZodSchema } from 'zod'
 
 import type {
   ActionFormState,
@@ -14,30 +14,37 @@ import type {
   SubmitFunction,
   UseActionFormCoreOptions,
   UseActionFormCoreReturn,
-} from "./core-types";
-import { defaultErrorMapper } from "./core-types";
-import { clearPersistedValues, debounce, loadPersistedValues, savePersistedValues } from "./persist";
-import { hasUseOptimistic, useOptimistic as useOptimisticReact19, useTransition } from "./react-shim";
+} from './core-types'
+import { defaultErrorMapper } from './core-types'
+import { clearPersistedValues, debounce, loadPersistedValues, savePersistedValues } from './persist'
+import {
+  hasUseOptimistic,
+  useOptimistic as useOptimisticReact19,
+  useTransition,
+} from './react-shim'
 
 // ---------------------------------------------------------------------------
 // Internal: client-side Zod validation helper
 // ---------------------------------------------------------------------------
 
-function validateWithSchema(schema: ZodSchema, values: Record<string, unknown>): FieldErrorRecord | null {
-  const result = schema.safeParse(values);
-  if (result.success) return null;
+function validateWithSchema(
+  schema: ZodSchema,
+  values: Record<string, unknown>,
+): FieldErrorRecord | null {
+  const result = schema.safeParse(values)
+  if (result.success) return null
 
-  const zodError = result.error as ZodError;
-  const flat = zodError.flatten();
-  const errors: FieldErrorRecord = {};
+  const zodError = result.error as ZodError
+  const flat = zodError.flatten()
+  const errors: FieldErrorRecord = {}
 
   for (const [field, messages] of Object.entries(flat.fieldErrors)) {
     if (messages && messages.length > 0) {
-      errors[field] = messages as string[];
+      errors[field] = messages as string[]
     }
   }
 
-  return Object.keys(errors).length > 0 ? errors : null;
+  return Object.keys(errors).length > 0 ? errors : null
 }
 
 // ---------------------------------------------------------------------------
@@ -45,8 +52,8 @@ function validateWithSchema(schema: ZodSchema, values: Record<string, unknown>):
 // ---------------------------------------------------------------------------
 
 function useOptimisticFallback<T>(initial: T): [T, (value: T) => void] {
-  const [state, setState] = useState<T>(initial);
-  return [state, setState];
+  const [state, setState] = useState<T>(initial)
+  return [state, setState]
 }
 
 // ---------------------------------------------------------------------------
@@ -79,7 +86,7 @@ export function useActionFormCore<
 ): UseActionFormCoreReturn<TFieldValues, TResult, TOptimistic> {
   const {
     defaultValues: optionDefaults,
-    mode = "onSubmit",
+    mode = 'onSubmit',
     persistKey,
     errorMapper = defaultErrorMapper as ErrorMapper<TResult>,
     onSuccess,
@@ -94,42 +101,42 @@ export function useActionFormCore<
     optimisticReducer,
     optimisticDefault,
     plugins = [],
-  } = options;
+  } = options
 
-  const resolvedValidationMode = validationMode ?? clientValidation ?? "onSubmit";
-  const resolvedOptimisticData = optimisticData ?? optimisticReducer;
-  const resolvedOptimisticInitial = (optimisticInitial ?? optimisticDefault) as TOptimistic;
+  const resolvedValidationMode = validationMode ?? clientValidation ?? 'onSubmit'
+  const resolvedOptimisticData = optimisticData ?? optimisticReducer
+  const resolvedOptimisticInitial = (optimisticInitial ?? optimisticDefault) as TOptimistic
 
   // ----- Resolve Zod schema -----------------------------------------------
 
-  const resolvedSchema = useMemo(() => optionsSchema ?? undefined, [optionsSchema]);
+  const resolvedSchema = useMemo(() => optionsSchema ?? undefined, [optionsSchema])
 
   // ----- Resolve initial values (persisted > options) ----------------------
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: intentionally run once on mount
   const resolvedDefaults = useMemo<DefaultValues<TFieldValues> | undefined>(() => {
     if (persistKey) {
-      const persisted = loadPersistedValues<TFieldValues>(persistKey);
+      const persisted = loadPersistedValues<TFieldValues>(persistKey)
       if (persisted) {
         return {
           ...(optionDefaults as Record<string, unknown> | undefined),
           ...persisted,
-        } as DefaultValues<TFieldValues>;
+        } as DefaultValues<TFieldValues>
       }
     }
-    return optionDefaults;
-  }, []);
+    return optionDefaults
+  }, [])
 
   // ----- React Hook Form ---------------------------------------------------
 
   const form = useForm<TFieldValues>({
     defaultValues: resolvedDefaults,
     mode,
-  });
+  })
 
   // ----- useTransition (React 18 & 19) ------------------------------------
 
-  const [isTransitioning, startTransition] = useTransition();
+  const [isTransitioning, startTransition] = useTransition()
 
   // ----- Action state ------------------------------------------------------
 
@@ -141,114 +148,116 @@ export function useActionFormCore<
     serverErrors: null,
     lastResult: null,
     isPending: false,
-  });
+  })
 
   // ----- Submission history (for DevTools) ----------------------------------
 
-  const submissionHistoryRef = useRef<SubmissionRecord<TResult>[]>([]);
+  const submissionHistoryRef = useRef<SubmissionRecord<TResult>[]>([])
 
   // ----- Optimistic UI (React 19 only) -------------------------------------
 
-  const hasOptimistic = resolvedOptimisticData != null && (optimisticKey != null || optimisticReducer != null);
+  const hasOptimistic =
+    resolvedOptimisticData != null && (optimisticKey != null || optimisticReducer != null)
 
-  const useOptimisticHook = hasUseOptimistic && useOptimisticReact19 ? useOptimisticReact19 : useOptimisticFallback;
+  const useOptimisticHook =
+    hasUseOptimistic && useOptimisticReact19 ? useOptimisticReact19 : useOptimisticFallback
 
-  const [optimisticState, setOptimistic] = useOptimisticHook(resolvedOptimisticInitial);
+  const [optimisticState, setOptimistic] = useOptimisticHook(resolvedOptimisticInitial)
 
-  const confirmedOptimisticRef = useRef<TOptimistic>(resolvedOptimisticInitial);
+  const confirmedOptimisticRef = useRef<TOptimistic>(resolvedOptimisticInitial)
 
   const rollbackOptimistic = useCallback(() => {
-    setOptimistic(confirmedOptimisticRef.current);
-  }, [setOptimistic]);
+    setOptimistic(confirmedOptimisticRef.current)
+  }, [setOptimistic])
 
   // ----- Persistence -------------------------------------------------------
 
   const debouncedSave = useMemo(() => {
-    if (!persistKey) return null;
+    if (!persistKey) return null
     return debounce((values: TFieldValues) => {
-      savePersistedValues(persistKey, values);
-    }, persistDebounce);
-  }, [persistKey, persistDebounce]);
+      savePersistedValues(persistKey, values)
+    }, persistDebounce)
+  }, [persistKey, persistDebounce])
 
   useEffect(() => {
-    if (!persistKey || !debouncedSave) return;
+    if (!persistKey || !debouncedSave) return
 
     const subscription = form.watch((values) => {
-      debouncedSave(values as TFieldValues);
-    });
+      debouncedSave(values as TFieldValues)
+    })
 
-    return () => subscription.unsubscribe();
-  }, [persistKey, debouncedSave, form]);
+    return () => subscription.unsubscribe()
+  }, [persistKey, debouncedSave, form])
 
   // ----- Client-side Zod validation (onChange / onBlur) ---------------------
 
   useEffect(() => {
-    if (!resolvedSchema || resolvedValidationMode === "onSubmit") return;
+    if (!resolvedSchema || resolvedValidationMode === 'onSubmit') return
 
     const subscription = form.watch((values, { name, type }) => {
-      if (!name) return;
+      if (!name) return
 
-      if (resolvedValidationMode === "onChange" || type === "blur") {
-        const fieldResult = resolvedSchema.safeParse(values);
+      if (resolvedValidationMode === 'onChange' || type === 'blur') {
+        const fieldResult = resolvedSchema.safeParse(values)
         if (fieldResult.success) {
-          form.clearErrors(name as FieldPath<TFieldValues>);
+          form.clearErrors(name as FieldPath<TFieldValues>)
         } else {
-          const zodError = fieldResult.error as ZodError;
-          const flat = zodError.flatten();
-          const fieldErrors = flat.fieldErrors[name];
+          const zodError = fieldResult.error as ZodError
+          const flat = zodError.flatten()
+          const fieldErrors = flat.fieldErrors[name]
 
           if (fieldErrors && fieldErrors.length > 0) {
             form.setError(name as FieldPath<TFieldValues>, {
-              type: "validation",
+              type: 'validation',
               message: fieldErrors[0],
-            });
+            })
           } else {
-            form.clearErrors(name as FieldPath<TFieldValues>);
+            form.clearErrors(name as FieldPath<TFieldValues>)
           }
         }
       }
-    });
+    })
 
-    return () => subscription.unsubscribe();
-  }, [resolvedSchema, resolvedValidationMode, form]);
+    return () => subscription.unsubscribe()
+  }, [resolvedSchema, resolvedValidationMode, form])
 
   // ----- Plugin lifecycle: onMount -----------------------------------------
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: plugins identity changes every render; run once on mount
   useEffect(() => {
-    const cleanups = plugins.map((p) => p.onMount?.()).filter(Boolean) as (() => void)[];
+    const cleanups = plugins.map((p) => p.onMount?.()).filter(Boolean) as (() => void)[]
 
     return () => {
       for (const cleanup of cleanups) {
-        cleanup();
+        cleanup()
       }
-    };
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps -- run once on mount
+    }
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps -- run once on mount
 
   // ----- Manual persist / clear --------------------------------------------
 
   const persist = useCallback(() => {
-    if (!persistKey) return;
-    savePersistedValues(persistKey, form.getValues());
-  }, [persistKey, form]);
+    if (!persistKey) return
+    savePersistedValues(persistKey, form.getValues())
+  }, [persistKey, form])
 
   const clearPersistedData = useCallback(() => {
-    if (!persistKey) return;
-    clearPersistedValues(persistKey);
-  }, [persistKey]);
+    if (!persistKey) return
+    clearPersistedValues(persistKey)
+  }, [persistKey])
 
-  const clearPersisted = clearPersistedData;
+  const clearPersisted = clearPersistedData
 
   // ----- Set a server error on a field -------------------------------------
 
   const setSubmitError = useCallback(
     (field: keyof TFieldValues & string, message: string) => {
-      form.setError(field as never, { type: "server", message });
+      form.setError(field as never, { type: 'server', message })
     },
     [form],
-  );
+  )
 
-  const setServerError = setSubmitError;
+  const setServerError = setSubmitError
 
   // ----- Map server errors to RHF ------------------------------------------
 
@@ -257,24 +266,24 @@ export function useActionFormCore<
       for (const [field, messages] of Object.entries(errors)) {
         if (messages && messages.length > 0) {
           form.setError(field as never, {
-            type: "server",
+            type: 'server',
             message: messages[0],
-          });
+          })
         }
       }
     },
     [form],
-  );
+  )
 
   // ----- Core submit logic -------------------------------------------------
 
   const executeSubmit = useCallback(
     async (data: TFieldValues) => {
       // Client-side schema validation (for onSubmit mode)
-      if (resolvedSchema && resolvedValidationMode === "onSubmit") {
-        const clientErrors = validateWithSchema(resolvedSchema, data as Record<string, unknown>);
+      if (resolvedSchema && resolvedValidationMode === 'onSubmit') {
+        const clientErrors = validateWithSchema(resolvedSchema, data as Record<string, unknown>)
         if (clientErrors) {
-          applyServerErrors(clientErrors);
+          applyServerErrors(clientErrors)
           setActionState({
             isSubmitting: false,
             isSubmitSuccessful: false,
@@ -283,16 +292,16 @@ export function useActionFormCore<
             serverErrors: clientErrors,
             lastResult: null,
             isPending: false,
-          });
-          return;
+          })
+          return
         }
       }
 
       // Plugin: onBeforeSubmit
       for (const plugin of plugins) {
         if (plugin.onBeforeSubmit) {
-          const shouldContinue = await plugin.onBeforeSubmit(data);
-          if (shouldContinue === false) return;
+          const shouldContinue = await plugin.onBeforeSubmit(data)
+          if (shouldContinue === false) return
         }
       }
 
@@ -302,20 +311,20 @@ export function useActionFormCore<
         isPending: true,
         submitErrors: null,
         serverErrors: null,
-      }));
+      }))
 
       // Apply optimistic update before the action runs
       if (hasOptimistic && resolvedOptimisticData) {
-        const optimisticResult = resolvedOptimisticData(confirmedOptimisticRef.current, data);
-        setOptimistic(optimisticResult);
+        const optimisticResult = resolvedOptimisticData(confirmedOptimisticRef.current, data)
+        setOptimistic(optimisticResult)
       }
 
-      const startTime = Date.now();
+      const startTime = Date.now()
 
       try {
-        const result = await submit(data);
+        const result = await submit(data)
 
-        const fieldErrors = errorMapper(result);
+        const fieldErrors = errorMapper(result)
 
         // Record submission for DevTools
         const record: SubmissionRecord<TResult> = {
@@ -326,14 +335,14 @@ export function useActionFormCore<
           error: null,
           duration: Date.now() - startTime,
           success: !fieldErrors || Object.keys(fieldErrors).length === 0,
-        };
-        submissionHistoryRef.current = [...submissionHistoryRef.current.slice(-49), record];
+        }
+        submissionHistoryRef.current = [...submissionHistoryRef.current.slice(-49), record]
 
         if (fieldErrors && Object.keys(fieldErrors).length > 0) {
-          applyServerErrors(fieldErrors);
+          applyServerErrors(fieldErrors)
 
           if (hasOptimistic) {
-            rollbackOptimistic();
+            rollbackOptimistic()
           }
 
           setActionState({
@@ -344,22 +353,25 @@ export function useActionFormCore<
             serverErrors: fieldErrors,
             lastResult: result,
             isPending: false,
-          });
+          })
 
           // Plugin: onError
           for (const plugin of plugins) {
-            plugin.onError?.(result, data);
+            plugin.onError?.(result, data)
           }
 
-          onError?.(result);
+          onError?.(result)
         } else {
           // Success – update confirmed optimistic state
           if (hasOptimistic && resolvedOptimisticData) {
-            confirmedOptimisticRef.current = resolvedOptimisticData(confirmedOptimisticRef.current, data);
+            confirmedOptimisticRef.current = resolvedOptimisticData(
+              confirmedOptimisticRef.current,
+              data,
+            )
           }
 
           // Clear persisted data
-          if (persistKey) clearPersistedValues(persistKey);
+          if (persistKey) clearPersistedValues(persistKey)
 
           setActionState({
             isSubmitting: false,
@@ -369,14 +381,14 @@ export function useActionFormCore<
             serverErrors: null,
             lastResult: result,
             isPending: false,
-          });
+          })
 
           // Plugin: onSuccess
           for (const plugin of plugins) {
-            plugin.onSuccess?.(result, data);
+            plugin.onSuccess?.(result, data)
           }
 
-          onSuccess?.(result);
+          onSuccess?.(result)
         }
       } catch (error) {
         // Record failed submission for DevTools
@@ -388,11 +400,11 @@ export function useActionFormCore<
           error: error instanceof Error ? error : new Error(String(error)),
           duration: Date.now() - startTime,
           success: false,
-        };
-        submissionHistoryRef.current = [...submissionHistoryRef.current.slice(-49), record];
+        }
+        submissionHistoryRef.current = [...submissionHistoryRef.current.slice(-49), record]
 
         if (hasOptimistic) {
-          rollbackOptimistic();
+          rollbackOptimistic()
         }
 
         setActionState((prev) => ({
@@ -400,16 +412,16 @@ export function useActionFormCore<
           isSubmitting: false,
           isSubmitSuccessful: false,
           isPending: false,
-        }));
+        }))
 
-        const wrappedError = error instanceof Error ? error : new Error(String(error));
+        const wrappedError = error instanceof Error ? error : new Error(String(error))
 
         // Plugin: onError
         for (const plugin of plugins) {
-          plugin.onError?.(wrappedError as TResult & Error, data);
+          plugin.onError?.(wrappedError as TResult & Error, data)
         }
 
-        onError?.(wrappedError);
+        onError?.(wrappedError)
       }
     },
     [
@@ -427,23 +439,23 @@ export function useActionFormCore<
       rollbackOptimistic,
       plugins,
     ],
-  );
+  )
 
   // ----- handleSubmit wrapper ----------------------------------------------
 
   const handleSubmit = useCallback(
     (onValid?: (data: TFieldValues) => void | Promise<void>) => {
       return form.handleSubmit(async (data) => {
-        if (onValid) await onValid(data);
+        if (onValid) await onValid(data)
 
         // @ts-ignore – React 19 supports async transitions; React 18 ignores the promise
         startTransition(async () => {
-          await executeSubmit(data);
-        });
-      });
+          await executeSubmit(data)
+        })
+      })
     },
     [form, executeSubmit, startTransition],
-  );
+  )
 
   // ----- Compose return value ----------------------------------------------
 
@@ -464,30 +476,30 @@ export function useActionFormCore<
       isPending: isTransitioning || actionState.isPending,
     }),
     [form.formState, actionState, isTransitioning],
-  );
+  )
 
   // ----- Compose optimistic return -----------------------------------------
 
   const optimisticReturn = useMemo(() => {
-    if (!hasOptimistic) return undefined;
+    if (!hasOptimistic) return undefined
     return {
       data: optimisticState,
       isPending: isTransitioning || actionState.isPending,
       rollback: rollbackOptimistic,
-    } as OptimisticState<TOptimistic>;
-  }, [hasOptimistic, optimisticState, isTransitioning, actionState.isPending, rollbackOptimistic]);
+    } as OptimisticState<TOptimistic>
+  }, [hasOptimistic, optimisticState, isTransitioning, actionState.isPending, rollbackOptimistic])
 
   // ----- Compose control with DevTools metadata ----------------------------
 
   const enhancedControl = useMemo(() => {
     const ctrl = form.control as typeof form.control & {
-      _submissionHistory: SubmissionRecord<TResult>[];
-      _actionFormState: ActionFormState<TResult>;
-    };
-    ctrl._submissionHistory = submissionHistoryRef.current;
-    ctrl._actionFormState = actionState;
-    return ctrl;
-  }, [form.control, actionState]);
+      _submissionHistory: SubmissionRecord<TResult>[]
+      _actionFormState: ActionFormState<TResult>
+    }
+    ctrl._submissionHistory = submissionHistoryRef.current
+    ctrl._actionFormState = actionState
+    return ctrl
+  }, [form.control, actionState])
 
   return {
     ...form,
@@ -500,5 +512,5 @@ export function useActionFormCore<
     clearPersistedData,
     clearPersisted,
     optimistic: optimisticReturn,
-  } as UseActionFormCoreReturn<TFieldValues, TResult, TOptimistic>;
+  } as UseActionFormCoreReturn<TFieldValues, TResult, TOptimistic>
 }
diff --git a/packages/core/src/use-action-form.ts b/packages/core/src/use-action-form.ts
index 268e697..0343079 100644
--- a/packages/core/src/use-action-form.ts
+++ b/packages/core/src/use-action-form.ts
@@ -1,11 +1,15 @@
-"use client";
-
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { type DefaultValues, type FieldPath, type FieldValues, useForm } from "react-hook-form";
-import type { ZodError, ZodSchema } from "zod";
-
-import { clearPersistedValues, debounce, loadPersistedValues, savePersistedValues } from "./persist";
-import { hasUseOptimistic, useOptimistic as useOptimisticReact19, useTransition } from "./react-shim";
+'use client'
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { type DefaultValues, type FieldPath, type FieldValues, useForm } from 'react-hook-form'
+import type { ZodError, ZodSchema } from 'zod'
+
+import { clearPersistedValues, debounce, loadPersistedValues, savePersistedValues } from './persist'
+import {
+  hasUseOptimistic,
+  useOptimistic as useOptimisticReact19,
+  useTransition,
+} from './react-shim'
 import type {
   ActionFormState,
   ActionResult,
@@ -15,38 +19,44 @@ import type {
   ServerAction,
   UseActionFormOptions,
   UseActionFormReturn,
-} from "./types";
-import { defaultErrorMapper, hasAttachedSchema, isFormDataAction } from "./types";
+} from './types'
+import { defaultErrorMapper, hasAttachedSchema, isFormDataAction } from './types'
 
 // ---------------------------------------------------------------------------
 // Internal: resolve Zod schema from options or attached action
 // ---------------------------------------------------------------------------
 
-function resolveSchema<TResult>(action: ServerAction<TResult>, optionsSchema?: ZodSchema): ZodSchema | undefined {
-  if (optionsSchema) return optionsSchema;
-  if (hasAttachedSchema(action)) return action.__schema;
-  return undefined;
+function resolveSchema<TResult>(
+  action: ServerAction<TResult>,
+  optionsSchema?: ZodSchema,
+): ZodSchema | undefined {
+  if (optionsSchema) return optionsSchema
+  if (hasAttachedSchema(action)) return action.__schema
+  return undefined
 }
 
 // ---------------------------------------------------------------------------
 // Internal: client-side Zod validation helper
 // ---------------------------------------------------------------------------
 
-function validateWithSchema(schema: ZodSchema, values: Record<string, unknown>): FieldErrorRecord | null {
-  const result = schema.safeParse(values);
-  if (result.success) return null;
+function validateWithSchema(
+  schema: ZodSchema,
+  values: Record<string, unknown>,
+): FieldErrorRecord | null {
+  const result = schema.safeParse(values)
+  if (result.success) return null
 
-  const zodError = result.error as ZodError;
-  const flat = zodError.flatten();
-  const errors: FieldErrorRecord = {};
+  const zodError = result.error as ZodError
+  const flat = zodError.flatten()
+  const errors: FieldErrorRecord = {}
 
   for (const [field, messages] of Object.entries(flat.fieldErrors)) {
     if (messages && messages.length > 0) {
-      errors[field] = messages as string[];
+      errors[field] = messages as string[]
     }
   }
 
-  return Object.keys(errors).length > 0 ? errors : null;
+  return Object.keys(errors).length > 0 ? errors : null
 }
 
 // ---------------------------------------------------------------------------
@@ -54,8 +64,8 @@ function validateWithSchema(schema: ZodSchema, values: Record<string, unknown>):
 // ---------------------------------------------------------------------------
 
 function useOptimisticFallback<T>(initial: T): [T, (value: T) => void] {
-  const [state, setState] = useState<T>(initial);
-  return [state, setState];
+  const [state, setState] = useState<T>(initial)
+  return [state, setState]
 }
 
 // ---------------------------------------------------------------------------
@@ -105,7 +115,7 @@ export function useActionForm<
 ): UseActionFormReturn<TFieldValues, TResult, TOptimistic> {
   const {
     defaultValues: optionDefaults,
-    mode = "onSubmit",
+    mode = 'onSubmit',
     persistKey,
     errorMapper = defaultErrorMapper as ErrorMapper<TResult>,
     onSuccess,
@@ -119,42 +129,45 @@ export function useActionForm<
     optimisticInitial,
     optimisticReducer,
     optimisticDefault,
-  } = options;
+  } = options
 
-  const resolvedValidationMode = validationMode ?? clientValidation ?? "onSubmit";
-  const resolvedOptimisticData = optimisticData ?? optimisticReducer;
-  const resolvedOptimisticInitial = (optimisticInitial ?? optimisticDefault) as TOptimistic;
+  const resolvedValidationMode = validationMode ?? clientValidation ?? 'onSubmit'
+  const resolvedOptimisticData = optimisticData ?? optimisticReducer
+  const resolvedOptimisticInitial = (optimisticInitial ?? optimisticDefault) as TOptimistic
 
   // ----- Resolve Zod schema (explicit or auto-detected from withZod) -------
 
-  const resolvedSchema = useMemo(() => resolveSchema(action, optionsSchema), [action, optionsSchema]);
+  const resolvedSchema = useMemo(
+    () => resolveSchema(action, optionsSchema),
+    [action, optionsSchema],
+  )
 
   // ----- Resolve initial values (persisted > options) ----------------------
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: intentionally run once on mount
   const resolvedDefaults = useMemo<DefaultValues<TFieldValues> | undefined>(() => {
     if (persistKey) {
-      const persisted = loadPersistedValues<TFieldValues>(persistKey);
+      const persisted = loadPersistedValues<TFieldValues>(persistKey)
       if (persisted) {
         return {
           ...(optionDefaults as Record<string, unknown> | undefined),
           ...persisted,
-        } as DefaultValues<TFieldValues>;
+        } as DefaultValues<TFieldValues>
       }
     }
-    return optionDefaults;
-  }, []);
+    return optionDefaults
+  }, [])
 
   // ----- React Hook Form ---------------------------------------------------
 
   const form = useForm<TFieldValues>({
     defaultValues: resolvedDefaults,
     mode,
-  });
+  })
 
   // ----- useTransition (React 18 & 19) ------------------------------------
 
-  const [isTransitioning, startTransition] = useTransition();
+  const [isTransitioning, startTransition] = useTransition()
 
   // ----- Action state ------------------------------------------------------
 
@@ -166,109 +179,111 @@ export function useActionForm<
     serverErrors: null,
     lastResult: null,
     isPending: false,
-  });
+  })
 
   // Keep a ref to the latest action result so callbacks read fresh state
-  const resultRef = useRef<TResult | null>(null);
+  const resultRef = useRef<TResult | null>(null)
   // Track the previous server state for the action
-  const prevStateRef = useRef<Awaited<TResult> | null>(null);
+  const prevStateRef = useRef<Awaited<TResult> | null>(null)
 
   // ----- Optimistic UI (React 19 only) -------------------------------------
 
-  const hasOptimistic = resolvedOptimisticData != null && (optimisticKey != null || optimisticReducer != null);
+  const hasOptimistic =
+    resolvedOptimisticData != null && (optimisticKey != null || optimisticReducer != null)
 
   // We use the React 19 useOptimistic when available, otherwise a simple state fallback.
-  const useOptimisticHook = hasUseOptimistic && useOptimisticReact19 ? useOptimisticReact19 : useOptimisticFallback;
+  const useOptimisticHook =
+    hasUseOptimistic && useOptimisticReact19 ? useOptimisticReact19 : useOptimisticFallback
 
-  const [optimisticState, setOptimistic] = useOptimisticHook(resolvedOptimisticInitial);
+  const [optimisticState, setOptimistic] = useOptimisticHook(resolvedOptimisticInitial)
 
   // Track confirmed state for rollback
-  const confirmedOptimisticRef = useRef<TOptimistic>(resolvedOptimisticInitial);
+  const confirmedOptimisticRef = useRef<TOptimistic>(resolvedOptimisticInitial)
 
   const rollbackOptimistic = useCallback(() => {
-    setOptimistic(confirmedOptimisticRef.current);
-  }, [setOptimistic]);
+    setOptimistic(confirmedOptimisticRef.current)
+  }, [setOptimistic])
 
   // ----- Persistence -------------------------------------------------------
 
   const debouncedSave = useMemo(() => {
-    if (!persistKey) return null;
+    if (!persistKey) return null
     return debounce((values: TFieldValues) => {
-      savePersistedValues(persistKey, values);
-    }, persistDebounce);
-  }, [persistKey, persistDebounce]);
+      savePersistedValues(persistKey, values)
+    }, persistDebounce)
+  }, [persistKey, persistDebounce])
 
   // Watch all fields and persist on change
   useEffect(() => {
-    if (!persistKey || !debouncedSave) return;
+    if (!persistKey || !debouncedSave) return
 
     const subscription = form.watch((values) => {
-      debouncedSave(values as TFieldValues);
-    });
+      debouncedSave(values as TFieldValues)
+    })
 
-    return () => subscription.unsubscribe();
-  }, [persistKey, debouncedSave, form]);
+    return () => subscription.unsubscribe()
+  }, [persistKey, debouncedSave, form])
 
   // ----- Client-side Zod validation (onChange / onBlur) ---------------------
 
   useEffect(() => {
-    if (!resolvedSchema || resolvedValidationMode === "onSubmit") return;
+    if (!resolvedSchema || resolvedValidationMode === 'onSubmit') return
 
     const subscription = form.watch((values, { name, type }) => {
-      if (!name) return;
+      if (!name) return
 
       // For onBlur mode, only validate if the event type is blur
       // (RHF watch fires on all changes, so we validate on onChange mode always)
-      if (resolvedValidationMode === "onChange" || type === "blur") {
+      if (resolvedValidationMode === 'onChange' || type === 'blur') {
         // Validate the single changed field
-        const fieldResult = resolvedSchema.safeParse(values);
+        const fieldResult = resolvedSchema.safeParse(values)
         if (fieldResult.success) {
           // Clear any existing errors for this field
-          form.clearErrors(name as FieldPath<TFieldValues>);
+          form.clearErrors(name as FieldPath<TFieldValues>)
         } else {
-          const zodError = fieldResult.error as ZodError;
-          const flat = zodError.flatten();
-          const fieldErrors = flat.fieldErrors[name];
+          const zodError = fieldResult.error as ZodError
+          const flat = zodError.flatten()
+          const fieldErrors = flat.fieldErrors[name]
 
           if (fieldErrors && fieldErrors.length > 0) {
             form.setError(name as FieldPath<TFieldValues>, {
-              type: "validation",
+              type: 'validation',
               message: fieldErrors[0],
-            });
+            })
           } else {
-            form.clearErrors(name as FieldPath<TFieldValues>);
+            form.clearErrors(name as FieldPath<TFieldValues>)
           }
         }
       }
-    });
+    })
 
-    return () => subscription.unsubscribe();
-  }, [resolvedSchema, resolvedValidationMode, form]);
+    return () => subscription.unsubscribe()
+  }, [resolvedSchema, resolvedValidationMode, form])
 
   // ----- Manual persist / clear --------------------------------------------
 
   const persist = useCallback(() => {
-    if (!persistKey) return;
-    savePersistedValues(persistKey, form.getValues());
-  }, [persistKey, form]);
+    if (!persistKey) return
+    savePersistedValues(persistKey, form.getValues())
+  }, [persistKey, form])
 
   const clearPersistedData = useCallback(() => {
-    if (!persistKey) return;
-    clearPersistedValues(persistKey);
-  }, [persistKey]);
+    if (!persistKey) return
+    clearPersistedValues(persistKey)
+  }, [persistKey])
 
-  const clearPersisted = clearPersistedData;
+  const clearPersisted = clearPersistedData
 
   // ----- Set a server error on a field -------------------------------------
 
   const setSubmitError = useCallback(
     (field: keyof TFieldValues & string, message: string) => {
-      form.setError(field as never, { type: "server", message });
+      form.setError(field as never, { type: 'server', message })
     },
     [form],
-  );
+  )
 
-  const setServerError = setSubmitError;
+  const setServerError = setSubmitError
 
   // ----- Map server errors to RHF ------------------------------------------
 
@@ -277,29 +292,29 @@ export function useActionForm<
       for (const [field, messages] of Object.entries(errors)) {
         if (messages && messages.length > 0) {
           form.setError(field as never, {
-            type: "server",
+            type: 'server',
             message: messages[0],
-          });
+          })
         }
       }
     },
     [form],
-  );
+  )
 
   // ----- Detect action arity ------------------------------------------------
 
   /** true when the action expects (prevState, formData) — arity >= 2 */
-  const actionIsFormData = useMemo(() => isFormDataAction(action), [action]);
+  const actionIsFormData = useMemo(() => isFormDataAction(action), [action])
 
   // ----- Core submit logic (shared between formAction & handleSubmit) ------
 
   const executeAction = useCallback(
     async (data: TFieldValues | FormData, isFormDataSubmission: boolean) => {
       // Client-side schema validation (for onSubmit mode)
-      if (resolvedSchema && resolvedValidationMode === "onSubmit" && !(data instanceof FormData)) {
-        const clientErrors = validateWithSchema(resolvedSchema, data as Record<string, unknown>);
+      if (resolvedSchema && resolvedValidationMode === 'onSubmit' && !(data instanceof FormData)) {
+        const clientErrors = validateWithSchema(resolvedSchema, data as Record<string, unknown>)
         if (clientErrors) {
-          applyServerErrors(clientErrors);
+          applyServerErrors(clientErrors)
           setActionState({
             isSubmitting: false,
             isSubmitSuccessful: false,
@@ -308,8 +323,8 @@ export function useActionForm<
             serverErrors: clientErrors,
             lastResult: null,
             isPending: false,
-          });
-          return;
+          })
+          return
         }
       }
 
@@ -319,77 +334,78 @@ export function useActionForm<
         isPending: true,
         submitErrors: null,
         serverErrors: null,
-      }));
+      }))
 
       // Apply optimistic update before the action runs
       if (hasOptimistic && resolvedOptimisticData && !(data instanceof FormData)) {
-        const optimisticResult = resolvedOptimisticData(confirmedOptimisticRef.current, data as TFieldValues);
-        setOptimistic(optimisticResult);
+        const optimisticResult = resolvedOptimisticData(
+          confirmedOptimisticRef.current,
+          data as TFieldValues,
+        )
+        setOptimistic(optimisticResult)
       }
 
       try {
-        let result: TResult;
+        let result: TResult
 
         if (isFormDataSubmission && data instanceof FormData) {
           if (actionIsFormData) {
-            result = await (action as (prev: Awaited<TResult> | null, fd: FormData) => Promise<TResult>)(
-              prevStateRef.current,
-              data,
-            );
+            result = await (
+              action as (prev: Awaited<TResult> | null, fd: FormData) => Promise<TResult>
+            )(prevStateRef.current, data)
           } else {
             // Convert FormData to plain object for JSON actions
-            const obj: Record<string, unknown> = {};
+            const obj: Record<string, unknown> = {}
             for (const [key, value] of data.entries()) {
               if (key in obj) {
-                const existing = obj[key];
+                const existing = obj[key]
                 if (Array.isArray(existing)) {
-                  existing.push(value);
+                  existing.push(value)
                 } else {
-                  obj[key] = [existing, value];
+                  obj[key] = [existing, value]
                 }
               } else {
-                obj[key] = value;
+                obj[key] = value
               }
             }
-            result = await (action as (d: unknown) => Promise<TResult>)(obj);
+            result = await (action as (d: unknown) => Promise<TResult>)(obj)
           }
         } else if (actionIsFormData) {
           // Build FormData from validated values for (prevState, formData) actions
-          const formData = new FormData();
+          const formData = new FormData()
           for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
             if (value instanceof File) {
-              formData.append(key, value);
+              formData.append(key, value)
             } else if (value instanceof FileList) {
               for (let i = 0; i < value.length; i++) {
-                formData.append(key, value[i] as File);
+                formData.append(key, value[i] as File)
               }
             } else if (Array.isArray(value)) {
               for (const item of value) {
-                formData.append(key, String(item));
+                formData.append(key, String(item))
               }
             } else if (value !== null && value !== undefined) {
-              formData.append(key, String(value));
+              formData.append(key, String(value))
             }
           }
-          result = await (action as (prev: Awaited<TResult> | null, fd: FormData) => Promise<TResult>)(
-            prevStateRef.current,
-            formData,
-          );
+          result = await (
+            action as (prev: Awaited<TResult> | null, fd: FormData) => Promise<TResult>
+          )(prevStateRef.current, formData)
         } else {
-          result = await (action as (d: unknown) => Promise<TResult>)(data);
+          result = await (action as (d: unknown) => Promise<TResult>)(data)
         }
 
-        resultRef.current = result;
-        prevStateRef.current = result as Awaited<TResult>;
+        resultRef.current = result
+        prevStateRef.current = result as Awaited<TResult>
 
-        const fieldErrors = errorMapper(result);
+        const fieldErrors = errorMapper(result)
 
         if (fieldErrors && Object.keys(fieldErrors).length > 0) {
-          applyServerErrors(fieldErrors);
+          applyServerErrors(fieldErrors)
 
           // Rollback optimistic on error
           if (hasOptimistic) {
-            rollbackOptimistic();
+            rollbackOptimistic()
           }
 
           setActionState({
@@ -400,16 +416,19 @@ export function useActionForm<
             serverErrors: fieldErrors,
             lastResult: result,
             isPending: false,
-          });
-          onError?.(result);
+          })
+          onError?.(result)
         } else {
           // Success – update confirmed optimistic state
           if (hasOptimistic && resolvedOptimisticData && !(data instanceof FormData)) {
-            confirmedOptimisticRef.current = resolvedOptimisticData(confirmedOptimisticRef.current, data as TFieldValues);
+            confirmedOptimisticRef.current = resolvedOptimisticData(
+              confirmedOptimisticRef.current,
+              data as TFieldValues,
+            )
           }
 
           // Clear persisted data
-          if (persistKey) clearPersistedValues(persistKey);
+          if (persistKey) clearPersistedValues(persistKey)
 
           setActionState({
             isSubmitting: false,
@@ -419,13 +438,13 @@ export function useActionForm<
             serverErrors: null,
             lastResult: result,
             isPending: false,
-          });
-          onSuccess?.(result);
+          })
+          onSuccess?.(result)
         }
       } catch (error) {
         // Rollback optimistic on throw
         if (hasOptimistic) {
-          rollbackOptimistic();
+          rollbackOptimistic()
         }
 
         setActionState((prev) => ({
@@ -433,8 +452,8 @@ export function useActionForm<
           isSubmitting: false,
           isSubmitSuccessful: false,
           isPending: false,
-        }));
-        onError?.(error instanceof Error ? error : new Error(String(error)));
+        }))
+        onError?.(error instanceof Error ? error : new Error(String(error)))
       }
     },
     [
@@ -452,7 +471,7 @@ export function useActionForm<
       setOptimistic,
       rollbackOptimistic,
     ],
-  );
+  )
 
   // ----- Form action (for Next.js <form action={…}>) -----------------------
 
@@ -460,11 +479,11 @@ export function useActionForm<
     async (formData: FormData) => {
       // @ts-ignore – React 19 supports async transitions; React 18 ignores the promise
       startTransition(async () => {
-        await executeAction(formData, true);
-      });
+        await executeAction(formData, true)
+      })
     },
     [executeAction, startTransition],
-  );
+  )
 
   // ----- handleSubmit wrapper ----------------------------------------------
 
@@ -472,16 +491,16 @@ export function useActionForm<
     (onValid?: (data: TFieldValues) => void | Promise<void>) => {
       return form.handleSubmit(async (data) => {
         // Run optional client-side callback first
-        if (onValid) await onValid(data);
+        if (onValid) await onValid(data)
 
         // @ts-ignore – React 19 supports async transitions; React 18 ignores the promise
         startTransition(async () => {
-          await executeAction(data, false);
-        });
-      });
+          await executeAction(data, false)
+        })
+      })
     },
     [form, executeAction, startTransition],
-  );
+  )
 
   // ----- Compose return value ----------------------------------------------
 
@@ -504,18 +523,18 @@ export function useActionForm<
       isPending: isTransitioning || actionState.isPending,
     }),
     [form.formState, actionState, isTransitioning],
-  );
+  )
 
   // ----- Compose optimistic return -----------------------------------------
 
   const optimisticReturn = useMemo(() => {
-    if (!hasOptimistic) return undefined;
+    if (!hasOptimistic) return undefined
     return {
       data: optimisticState,
       isPending: isTransitioning || actionState.isPending,
       rollback: rollbackOptimistic,
-    } as OptimisticState<TOptimistic>;
-  }, [hasOptimistic, optimisticState, isTransitioning, actionState.isPending, rollbackOptimistic]);
+    } as OptimisticState<TOptimistic>
+  }, [hasOptimistic, optimisticState, isTransitioning, actionState.isPending, rollbackOptimistic])
 
   return {
     ...form,
@@ -528,5 +547,5 @@ export function useActionForm<
     clearPersisted,
     formAction,
     optimistic: optimisticReturn,
-  } as UseActionFormReturn<TFieldValues, TResult, TOptimistic>;
+  } as UseActionFormReturn<TFieldValues, TResult, TOptimistic>
 }
diff --git a/packages/devtools/src/FormDevTool.tsx b/packages/devtools/src/FormDevTool.tsx
index 6078291..3da7f8b 100644
--- a/packages/devtools/src/FormDevTool.tsx
+++ b/packages/devtools/src/FormDevTool.tsx
@@ -1,9 +1,9 @@
-"use client";
+'use client'
 
-import type { ActionFormState, SubmissionRecord } from "hookform-action-core";
-import { type CSSProperties, useCallback, useEffect, useState } from "react";
-import type { Control, FieldValues } from "react-hook-form";
-import { useFormState, useWatch } from "react-hook-form";
+import type { ActionFormState, SubmissionRecord } from 'hookform-action-core'
+import { type CSSProperties, useCallback, useEffect, useState } from 'react'
+import type { Control, FieldValues } from 'react-hook-form'
+import { useFormState, useWatch } from 'react-hook-form'
 
 // ---------------------------------------------------------------------------
 // Types
@@ -15,21 +15,21 @@ export interface FormDevToolProps<TFieldValues extends FieldValues = FieldValues
    * Must be the enhanced control that includes `_submissionHistory` and `_actionFormState`.
    */
   control: Control<TFieldValues> & {
-    _submissionHistory?: SubmissionRecord<unknown>[];
-    _actionFormState?: ActionFormState<unknown>;
-  };
+    _submissionHistory?: SubmissionRecord<unknown>[]
+    _actionFormState?: ActionFormState<unknown>
+  }
 
   /**
    * Position of the floating panel toggle button.
    * @default 'bottom-right'
    */
-  position?: "bottom-left" | "bottom-right" | "top-left" | "top-right";
+  position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'
 
   /**
    * Initial open state.
    * @default false
    */
-  defaultOpen?: boolean;
+  defaultOpen?: boolean
 }
 
 // ---------------------------------------------------------------------------
@@ -37,181 +37,182 @@ export interface FormDevToolProps<TFieldValues extends FieldValues = FieldValues
 // ---------------------------------------------------------------------------
 
 const COLORS = {
-  bg: "#1a1a2e",
-  bgLight: "#16213e",
-  bgPanel: "#0f3460",
-  text: "#e2e8f0",
-  textMuted: "#94a3b8",
-  accent: "#e94560",
-  success: "#10b981",
-  error: "#ef4444",
-  warning: "#f59e0b",
-  border: "#334155",
-  badge: "#7c3aed",
-};
+  bg: '#1a1a2e',
+  bgLight: '#16213e',
+  bgPanel: '#0f3460',
+  text: '#e2e8f0',
+  textMuted: '#94a3b8',
+  accent: '#e94560',
+  success: '#10b981',
+  error: '#ef4444',
+  warning: '#f59e0b',
+  border: '#334155',
+  badge: '#7c3aed',
+}
 
 function getToggleStyles(position: string): CSSProperties {
   const base: CSSProperties = {
-    position: "fixed",
+    position: 'fixed',
     zIndex: 99999,
     width: 48,
     height: 48,
-    borderRadius: "50%",
-    border: "none",
+    borderRadius: '50%',
+    border: 'none',
     backgroundColor: COLORS.accent,
-    color: "#fff",
+    color: '#fff',
     fontSize: 20,
-    cursor: "pointer",
-    display: "flex",
-    alignItems: "center",
-    justifyContent: "center",
-    boxShadow: "0 4px 12px rgba(0,0,0,0.3)",
-    transition: "transform 0.2s, box-shadow 0.2s",
-  };
+    cursor: 'pointer',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    boxShadow: '0 4px 12px rgba(0,0,0,0.3)',
+    transition: 'transform 0.2s, box-shadow 0.2s',
+  }
 
   switch (position) {
-    case "bottom-left":
-      return { ...base, bottom: 16, left: 16 };
-    case "top-left":
-      return { ...base, top: 16, left: 16 };
-    case "top-right":
-      return { ...base, top: 16, right: 16 };
+    case 'bottom-left':
+      return { ...base, bottom: 16, left: 16 }
+    case 'top-left':
+      return { ...base, top: 16, left: 16 }
+    case 'top-right':
+      return { ...base, top: 16, right: 16 }
     default:
-      return { ...base, bottom: 16, right: 16 };
+      return { ...base, bottom: 16, right: 16 }
   }
 }
 
 function getPanelStyles(position: string): CSSProperties {
   const base: CSSProperties = {
-    position: "fixed",
+    position: 'fixed',
     zIndex: 99998,
     width: 420,
-    maxHeight: "70vh",
+    maxHeight: '70vh',
     backgroundColor: COLORS.bg,
     color: COLORS.text,
     borderRadius: 12,
-    boxShadow: "0 8px 32px rgba(0,0,0,0.4)",
-    fontFamily: 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
+    boxShadow: '0 8px 32px rgba(0,0,0,0.4)',
+    fontFamily:
+      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
     fontSize: 13,
-    overflow: "hidden",
-    display: "flex",
-    flexDirection: "column",
-  };
+    overflow: 'hidden',
+    display: 'flex',
+    flexDirection: 'column',
+  }
 
   switch (position) {
-    case "bottom-left":
-      return { ...base, bottom: 72, left: 16 };
-    case "top-left":
-      return { ...base, top: 72, left: 16 };
-    case "top-right":
-      return { ...base, top: 72, right: 16 };
+    case 'bottom-left':
+      return { ...base, bottom: 72, left: 16 }
+    case 'top-left':
+      return { ...base, top: 72, left: 16 }
+    case 'top-right':
+      return { ...base, top: 72, right: 16 }
     default:
-      return { ...base, bottom: 72, right: 16 };
+      return { ...base, bottom: 72, right: 16 }
   }
 }
 
 const headerStyle: CSSProperties = {
-  display: "flex",
-  alignItems: "center",
-  justifyContent: "space-between",
-  padding: "12px 16px",
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  padding: '12px 16px',
   backgroundColor: COLORS.bgPanel,
   borderBottom: `1px solid ${COLORS.border}`,
   fontWeight: 700,
   fontSize: 14,
-};
+}
 
 const tabBarStyle: CSSProperties = {
-  display: "flex",
+  display: 'flex',
   borderBottom: `1px solid ${COLORS.border}`,
-};
+}
 
 const tabStyle = (active: boolean): CSSProperties => ({
   flex: 1,
-  padding: "8px 12px",
-  border: "none",
-  backgroundColor: active ? COLORS.bgLight : "transparent",
+  padding: '8px 12px',
+  border: 'none',
+  backgroundColor: active ? COLORS.bgLight : 'transparent',
   color: active ? COLORS.text : COLORS.textMuted,
-  cursor: "pointer",
+  cursor: 'pointer',
   fontSize: 12,
   fontWeight: active ? 600 : 400,
-  borderBottom: active ? `2px solid ${COLORS.accent}` : "2px solid transparent",
-  fontFamily: "inherit",
-});
+  borderBottom: active ? `2px solid ${COLORS.accent}` : '2px solid transparent',
+  fontFamily: 'inherit',
+})
 
 const contentStyle: CSSProperties = {
-  overflow: "auto",
+  overflow: 'auto',
   padding: 16,
-  maxHeight: "calc(70vh - 100px)",
-};
+  maxHeight: 'calc(70vh - 100px)',
+}
 
 const sectionTitle: CSSProperties = {
   fontSize: 11,
   fontWeight: 700,
-  textTransform: "uppercase",
+  textTransform: 'uppercase',
   color: COLORS.textMuted,
   marginBottom: 8,
-  letterSpacing: "0.05em",
-};
+  letterSpacing: '0.05em',
+}
 
 const kvRow: CSSProperties = {
-  display: "flex",
-  justifyContent: "space-between",
-  padding: "4px 0",
+  display: 'flex',
+  justifyContent: 'space-between',
+  padding: '4px 0',
   borderBottom: `1px solid ${COLORS.border}`,
-};
+}
 
 const keyStyle: CSSProperties = {
   color: COLORS.textMuted,
   fontSize: 12,
-};
+}
 
 const valueStyle: CSSProperties = {
   color: COLORS.text,
   fontSize: 12,
   fontWeight: 500,
   maxWidth: 200,
-  overflow: "hidden",
-  textOverflow: "ellipsis",
-  whiteSpace: "nowrap",
-};
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+}
 
 const badgeStyle = (color: string): CSSProperties => ({
-  display: "inline-block",
-  padding: "2px 8px",
+  display: 'inline-block',
+  padding: '2px 8px',
   borderRadius: 9999,
   fontSize: 11,
   fontWeight: 600,
   backgroundColor: color,
-  color: "#fff",
-});
+  color: '#fff',
+})
 
 const historyItemStyle = (success: boolean): CSSProperties => ({
-  padding: "8px 12px",
+  padding: '8px 12px',
   marginBottom: 8,
   borderRadius: 8,
   backgroundColor: COLORS.bgLight,
   borderLeft: `3px solid ${success ? COLORS.success : COLORS.error}`,
-});
+})
 
 const actionBtnStyle: CSSProperties = {
-  padding: "6px 12px",
+  padding: '6px 12px',
   border: `1px solid ${COLORS.border}`,
   borderRadius: 6,
-  backgroundColor: "transparent",
+  backgroundColor: 'transparent',
   color: COLORS.text,
-  cursor: "pointer",
+  cursor: 'pointer',
   fontSize: 12,
-  fontFamily: "inherit",
+  fontFamily: 'inherit',
   marginRight: 8,
-  transition: "background-color 0.2s",
-};
+  transition: 'background-color 0.2s',
+}
 
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
 
-type Tab = "state" | "history" | "actions";
+type Tab = 'state' | 'history' | 'actions'
 
 /**
  * `<FormDevTool />` – Floating debug panel for hookform-action.
@@ -241,32 +242,32 @@ type Tab = "state" | "history" | "actions";
  */
 export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
   control,
-  position = "bottom-right",
+  position = 'bottom-right',
   defaultOpen = false,
 }: FormDevToolProps<TFieldValues>) {
-  const [isOpen, setIsOpen] = useState(defaultOpen);
-  const [activeTab, setActiveTab] = useState<Tab>("state");
-  const [_refreshKey, setRefreshKey] = useState(0);
+  const [isOpen, setIsOpen] = useState(defaultOpen)
+  const [activeTab, setActiveTab] = useState<Tab>('state')
+  const [_refreshKey, setRefreshKey] = useState(0)
 
   // Force re-render to pick up submission history changes
   useEffect(() => {
-    if (!isOpen) return;
-    const interval = setInterval(() => setRefreshKey((k) => k + 1), 1000);
-    return () => clearInterval(interval);
-  }, [isOpen]);
+    if (!isOpen) return
+    const interval = setInterval(() => setRefreshKey((k) => k + 1), 1000)
+    return () => clearInterval(interval)
+  }, [isOpen])
 
   // Get RHF form state
-  const formState = useFormState({ control: control as Control<TFieldValues> });
+  const formState = useFormState({ control: control as Control<TFieldValues> })
 
   // Watch all field values
-  const watchedValues = useWatch({ control: control as Control<TFieldValues> });
+  const watchedValues = useWatch({ control: control as Control<TFieldValues> })
 
   // Get action form state from control
-  const ctrl = control as unknown as Record<string, unknown>;
-  const actionFormState = ctrl?._actionFormState as ActionFormState<unknown> | undefined;
-  const submissionHistory = ctrl?._submissionHistory as SubmissionRecord<unknown>[] | undefined;
+  const ctrl = control as unknown as Record<string, unknown>
+  const actionFormState = ctrl?._actionFormState as ActionFormState<unknown> | undefined
+  const submissionHistory = ctrl?._submissionHistory as SubmissionRecord<unknown>[] | undefined
 
-  const togglePanel = useCallback(() => setIsOpen((o) => !o), []);
+  const togglePanel = useCallback(() => setIsOpen((o) => !o), [])
 
   // ---- Render: Toggle button ----------------------------------------------
 
@@ -278,11 +279,11 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
       title="Toggle Form DevTools"
       aria-label="Toggle Form DevTools"
     >
-      {isOpen ? "✕" : "🔍"}
+      {isOpen ? '✕' : '🔍'}
     </button>
-  );
+  )
 
-  if (!isOpen) return toggleButton;
+  if (!isOpen) return toggleButton
 
   // ---- State Tab ----------------------------------------------------------
 
@@ -304,7 +305,11 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
       </div>
       <div style={kvRow}>
         <span style={keyStyle}>isSubmitSuccessful</span>
-        <span style={badgeStyle(actionFormState?.isSubmitSuccessful ? COLORS.success : COLORS.textMuted)}>
+        <span
+          style={badgeStyle(
+            actionFormState?.isSubmitSuccessful ? COLORS.success : COLORS.textMuted,
+          )}
+        >
           {String(actionFormState?.isSubmitSuccessful ?? formState.isSubmitSuccessful)}
         </span>
       </div>
@@ -314,21 +319,25 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
       </div>
       <div style={kvRow}>
         <span style={keyStyle}>isDirty</span>
-        <span style={badgeStyle(formState.isDirty ? COLORS.warning : COLORS.success)}>{String(formState.isDirty)}</span>
+        <span style={badgeStyle(formState.isDirty ? COLORS.warning : COLORS.success)}>
+          {String(formState.isDirty)}
+        </span>
       </div>
       <div style={kvRow}>
         <span style={keyStyle}>isValid</span>
-        <span style={badgeStyle(formState.isValid ? COLORS.success : COLORS.error)}>{String(formState.isValid)}</span>
+        <span style={badgeStyle(formState.isValid ? COLORS.success : COLORS.error)}>
+          {String(formState.isValid)}
+        </span>
       </div>
 
       {/* Current Values */}
       <div style={{ ...sectionTitle, marginTop: 16 }}>Current Values</div>
-      {watchedValues && typeof watchedValues === "object" ? (
+      {watchedValues && typeof watchedValues === 'object' ? (
         Object.entries(watchedValues as Record<string, unknown>).map(([key, value]) => (
           <div key={key} style={kvRow}>
             <span style={keyStyle}>{key}</span>
-            <span style={valueStyle} title={String(value ?? "")}>
-              {value === undefined ? "undefined" : value === null ? "null" : String(value)}
+            <span style={valueStyle} title={String(value ?? '')}>
+              {value === undefined ? 'undefined' : value === null ? 'null' : String(value)}
             </span>
           </div>
         ))
@@ -343,7 +352,7 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
           <div key={key} style={kvRow}>
             <span style={{ ...keyStyle, color: COLORS.error }}>{key}</span>
             <span style={{ ...valueStyle, color: COLORS.error }}>
-              {String((error as Record<string, unknown>)?.message ?? "Error")}
+              {String((error as Record<string, unknown>)?.message ?? 'Error')}
             </span>
           </div>
         ))
@@ -358,13 +367,15 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
           {Object.entries(actionFormState.serverErrors).map(([key, messages]) => (
             <div key={key} style={kvRow}>
               <span style={{ ...keyStyle, color: COLORS.error }}>{key}</span>
-              <span style={{ ...valueStyle, color: COLORS.error }}>{(messages ?? []).join(", ")}</span>
+              <span style={{ ...valueStyle, color: COLORS.error }}>
+                {(messages ?? []).join(', ')}
+              </span>
             </div>
           ))}
         </>
       )}
     </div>
-  );
+  )
 
   // ---- History Tab --------------------------------------------------------
 
@@ -374,9 +385,9 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
       {submissionHistory && submissionHistory.length > 0 ? (
         [...submissionHistory].reverse().map((record) => (
           <div key={record.id} style={historyItemStyle(record.success)}>
-            <div style={{ display: "flex", justifyContent: "space-between", marginBottom: 4 }}>
+            <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 4 }}>
               <span style={badgeStyle(record.success ? COLORS.success : COLORS.error)}>
-                {record.success ? "SUCCESS" : "FAILED"}
+                {record.success ? 'SUCCESS' : 'FAILED'}
               </span>
               <span style={{ color: COLORS.textMuted, fontSize: 11 }}>{record.duration}ms</span>
             </div>
@@ -387,7 +398,7 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
               <span style={{ color: COLORS.textMuted }}>Payload: </span>
               <span style={{ color: COLORS.text }}>
                 {JSON.stringify(record.payload).slice(0, 100)}
-                {JSON.stringify(record.payload).length > 100 ? "…" : ""}
+                {JSON.stringify(record.payload).length > 100 ? '…' : ''}
               </span>
             </div>
             {record.response != null && (
@@ -395,34 +406,36 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
                 <span style={{ color: COLORS.textMuted }}>Response: </span>
                 <span style={{ color: COLORS.text }}>
                   {String(JSON.stringify(record.response)).slice(0, 100)}
-                  {String(JSON.stringify(record.response)).length > 100 ? "…" : ""}
+                  {String(JSON.stringify(record.response)).length > 100 ? '…' : ''}
                 </span>
               </div>
             )}
-            {record.error && <div style={{ fontSize: 11, color: COLORS.error }}>Error: {record.error.message}</div>}
+            {record.error && (
+              <div style={{ fontSize: 11, color: COLORS.error }}>Error: {record.error.message}</div>
+            )}
           </div>
         ))
       ) : (
-        <div style={{ color: COLORS.textMuted, fontSize: 12, textAlign: "center", padding: 24 }}>
+        <div style={{ color: COLORS.textMuted, fontSize: 12, textAlign: 'center', padding: 24 }}>
           No submissions yet
         </div>
       )}
     </div>
-  );
+  )
 
   // ---- Actions Tab --------------------------------------------------------
 
   const actionsContent = (
     <div>
       <div style={sectionTitle}>Debug Actions</div>
-      <div style={{ display: "flex", flexWrap: "wrap", gap: 8 }}>
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
         <button
           type="button"
           style={actionBtnStyle}
           onClick={() => {
             // Force a simulated success by dispatching to action state
             // This is a read-only view, but we can still trigger re-renders
-            console.log("[FormDevTool] Current values:", watchedValues);
+            console.log('[FormDevTool] Current values:', watchedValues)
           }}
           title="Log current form values to console"
         >
@@ -432,10 +445,10 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
           type="button"
           style={actionBtnStyle}
           onClick={() => {
-            console.log("[FormDevTool] Form state:", {
+            console.log('[FormDevTool] Form state:', {
               ...formState,
               actionFormState,
-            });
+            })
           }}
           title="Log full form state to console"
         >
@@ -445,7 +458,7 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
           type="button"
           style={actionBtnStyle}
           onClick={() => {
-            console.log("[FormDevTool] Submission history:", submissionHistory);
+            console.log('[FormDevTool] Submission history:', submissionHistory)
           }}
           title="Log submission history to console"
         >
@@ -459,8 +472,8 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
             color: COLORS.error,
           }}
           onClick={() => {
-            console.log("[FormDevTool] Errors:", formState.errors);
-            console.log("[FormDevTool] Server errors:", actionFormState?.serverErrors);
+            console.log('[FormDevTool] Errors:', formState.errors)
+            console.log('[FormDevTool] Server errors:', actionFormState?.serverErrors)
           }}
           title="Log all errors to console"
         >
@@ -490,11 +503,11 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
         <span style={valueStyle}>
           {submissionHistory && submissionHistory.length > 0
             ? `${Math.round(submissionHistory.reduce((a, r) => a + r.duration, 0) / submissionHistory.length)}ms`
-            : "N/A"}
+            : 'N/A'}
         </span>
       </div>
     </div>
-  );
+  )
 
   // ---- Panel Layout -------------------------------------------------------
 
@@ -510,34 +523,50 @@ export function FormDevTool<TFieldValues extends FieldValues = FieldValues>({
               actionFormState?.isSubmitting
                 ? COLORS.warning
                 : actionFormState?.isSubmitSuccessful
-                ? COLORS.success
-                : COLORS.badge,
+                  ? COLORS.success
+                  : COLORS.badge,
             )}
           >
-            {actionFormState?.isSubmitting ? "Submitting" : actionFormState?.isSubmitSuccessful ? "Success" : "Idle"}
+            {actionFormState?.isSubmitting
+              ? 'Submitting'
+              : actionFormState?.isSubmitSuccessful
+                ? 'Success'
+                : 'Idle'}
           </span>
         </div>
 
         {/* Tab Bar */}
         <div style={tabBarStyle}>
-          <button type="button" style={tabStyle(activeTab === "state")} onClick={() => setActiveTab("state")}>
+          <button
+            type="button"
+            style={tabStyle(activeTab === 'state')}
+            onClick={() => setActiveTab('state')}
+          >
             📋 State
           </button>
-          <button type="button" style={tabStyle(activeTab === "history")} onClick={() => setActiveTab("history")}>
+          <button
+            type="button"
+            style={tabStyle(activeTab === 'history')}
+            onClick={() => setActiveTab('history')}
+          >
             📜 History ({submissionHistory?.length ?? 0})
           </button>
-          <button type="button" style={tabStyle(activeTab === "actions")} onClick={() => setActiveTab("actions")}>
+          <button
+            type="button"
+            style={tabStyle(activeTab === 'actions')}
+            onClick={() => setActiveTab('actions')}
+          >
             ⚡ Actions
           </button>
         </div>
 
         {/* Content */}
         <div style={contentStyle}>
-          {activeTab === "state" && stateContent}
-          {activeTab === "history" && historyContent}
-          {activeTab === "actions" && actionsContent}
+          {activeTab === 'state' && stateContent}
+          {activeTab === 'history' && historyContent}
+          {activeTab === 'actions' && actionsContent}
         </div>
       </dialog>
     </>
-  );
+  )
 }
diff --git a/packages/standalone/src/__tests__/use-action-form.test.ts b/packages/standalone/src/__tests__/use-action-form.test.ts
index 2b573de..946e2fb 100644
--- a/packages/standalone/src/__tests__/use-action-form.test.ts
+++ b/packages/standalone/src/__tests__/use-action-form.test.ts
@@ -1,6 +1,6 @@
-import { act, renderHook, waitFor } from "@testing-library/react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { useActionForm } from "../use-action-form";
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { useActionForm } from '../use-action-form'
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -9,198 +9,201 @@ import { useActionForm } from "../use-action-form";
 function createFetchSubmit() {
   return vi.fn(async (data: Record<string, unknown>) => {
     // Simulate a successful API call
-    return { success: true, data };
-  });
+    return { success: true, data }
+  })
 }
 
 function createFetchErrorSubmit() {
   return vi.fn(async (_data: Record<string, unknown>) => {
-    return { errors: { email: ["Email already exists"] } };
-  });
+    return { errors: { email: ['Email already exists'] } }
+  })
 }
 
 function createThrowingFetchSubmit() {
   return vi.fn(async (_data: Record<string, unknown>) => {
-    throw new Error("Network error");
-  });
+    throw new Error('Network error')
+  })
 }
 
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-describe("hookform-action-standalone – useActionForm", () => {
+describe('hookform-action-standalone – useActionForm', () => {
   beforeEach(() => {
-    sessionStorage.clear();
-  });
+    sessionStorage.clear()
+  })
 
-  it("returns all expected properties", () => {
+  it('returns all expected properties', () => {
     const { result } = renderHook(() =>
       useActionForm({
         submit: createFetchSubmit(),
-        defaultValues: { email: "" },
+        defaultValues: { email: '' },
       }),
-    );
+    )
 
-    expect(result.current.register).toBeDefined();
-    expect(result.current.handleSubmit).toBeDefined();
-    expect(result.current.formState).toBeDefined();
-    expect(result.current.setServerError).toBeDefined();
-    expect(result.current.persist).toBeDefined();
-    expect(result.current.clearPersisted).toBeDefined();
-  });
+    expect(result.current.register).toBeDefined()
+    expect(result.current.handleSubmit).toBeDefined()
+    expect(result.current.formState).toBeDefined()
+    expect(result.current.setServerError).toBeDefined()
+    expect(result.current.persist).toBeDefined()
+    expect(result.current.clearPersisted).toBeDefined()
+  })
 
-  it("does NOT have formAction (standalone has no Server Actions)", () => {
+  it('does NOT have formAction (standalone has no Server Actions)', () => {
     const { result } = renderHook(() =>
       useActionForm({
         submit: createFetchSubmit(),
       }),
-    );
+    )
 
-    expect((result.current as Record<string, unknown>).formAction).toBeUndefined();
-  });
+    expect((result.current as Record<string, unknown>).formAction).toBeUndefined()
+  })
 
-  it("uses defaultValues", () => {
+  it('uses defaultValues', () => {
     const { result } = renderHook(() =>
       useActionForm({
         submit: createFetchSubmit(),
-        defaultValues: { email: "hello@world.com" },
+        defaultValues: { email: 'hello@world.com' },
       }),
-    );
+    )
 
-    expect(result.current.getValues("email")).toBe("hello@world.com");
-  });
+    expect(result.current.getValues('email')).toBe('hello@world.com')
+  })
 
-  it("calls the submit function on form submit", async () => {
-    const submit = createFetchSubmit();
+  it('calls the submit function on form submit', async () => {
+    const submit = createFetchSubmit()
     const { result } = renderHook(() =>
       useActionForm({
         submit,
-        defaultValues: { email: "test@test.com" },
+        defaultValues: { email: 'test@test.com' },
       }),
-    );
+    )
 
     await act(async () => {
-      await result.current.handleSubmit()();
-    });
+      await result.current.handleSubmit()()
+    })
 
     await waitFor(() => {
-      expect(submit).toHaveBeenCalledWith({ email: "test@test.com" });
-    });
-  });
+      expect(submit).toHaveBeenCalledWith({ email: 'test@test.com' })
+    })
+  })
 
-  it("sets isSubmitSuccessful after success", async () => {
-    const submit = createFetchSubmit();
+  it('sets isSubmitSuccessful after success', async () => {
+    const submit = createFetchSubmit()
     const { result } = renderHook(() =>
       useActionForm({
         submit,
-        defaultValues: { name: "Vite user" },
+        defaultValues: { name: 'Vite user' },
       }),
-    );
+    )
 
     await act(async () => {
-      await result.current.handleSubmit()();
-    });
+      await result.current.handleSubmit()()
+    })
 
     await waitFor(() => {
-      expect(result.current.formState.isSubmitSuccessful).toBe(true);
-    });
-  });
+      expect(result.current.formState.isSubmitSuccessful).toBe(true)
+    })
+  })
 
-  it("maps server errors to form fields", async () => {
-    const submit = createFetchErrorSubmit();
+  it('maps server errors to form fields', async () => {
+    const submit = createFetchErrorSubmit()
     const { result } = renderHook(() =>
       useActionForm({
         submit,
-        defaultValues: { email: "" },
+        defaultValues: { email: '' },
       }),
-    );
+    )
 
     await act(async () => {
-      await result.current.handleSubmit()();
-    });
+      await result.current.handleSubmit()()
+    })
 
     await waitFor(() => {
       expect(result.current.formState.serverErrors).toEqual({
-        email: ["Email already exists"],
-      });
-    });
-  });
+        email: ['Email already exists'],
+      })
+    })
+  })
 
-  it("handles thrown errors", async () => {
-    const onError = vi.fn();
+  it('handles thrown errors', async () => {
+    const onError = vi.fn()
     const { result } = renderHook(() =>
       useActionForm({
         submit: createThrowingFetchSubmit(),
-        defaultValues: { email: "" },
+        defaultValues: { email: '' },
         onError,
       }),
-    );
+    )
 
     await act(async () => {
-      await result.current.handleSubmit()();
-    });
+      await result.current.handleSubmit()()
+    })
 
     await waitFor(() => {
-      expect(onError).toHaveBeenCalled();
-    });
-  });
+      expect(onError).toHaveBeenCalled()
+    })
+  })
 
-  it("calls onSuccess callback", async () => {
-    const submit = createFetchSubmit();
-    const onSuccess = vi.fn();
+  it('calls onSuccess callback', async () => {
+    const submit = createFetchSubmit()
+    const onSuccess = vi.fn()
     const { result } = renderHook(() =>
       useActionForm({
         submit,
-        defaultValues: { email: "test@test.com" },
+        defaultValues: { email: 'test@test.com' },
         onSuccess,
       }),
-    );
+    )
 
     await act(async () => {
-      await result.current.handleSubmit()();
-    });
+      await result.current.handleSubmit()()
+    })
 
     await waitFor(() => {
-      expect(onSuccess).toHaveBeenCalled();
-    });
-  });
+      expect(onSuccess).toHaveBeenCalled()
+    })
+  })
 
-  it("supports persistKey", async () => {
-    const submit = createFetchSubmit();
+  it('supports persistKey', async () => {
+    const submit = createFetchSubmit()
     const { result } = renderHook(() =>
       useActionForm({
         submit,
-        defaultValues: { email: "persist@test.com" },
-        persistKey: "standalone-test",
+        defaultValues: { email: 'persist@test.com' },
+        persistKey: 'standalone-test',
         persistDebounce: 0,
       }),
-    );
+    )
 
     await act(async () => {
-      result.current.persist();
-    });
+      result.current.persist()
+    })
 
-    const stored = sessionStorage.getItem("standalone-test");
-    expect(stored).toBeTruthy();
-    expect(JSON.parse(stored as string).email).toBe("persist@test.com");
-  });
+    const stored = sessionStorage.getItem('standalone-test')
+    expect(stored).toBeTruthy()
+    expect(JSON.parse(stored as string).email).toBe('persist@test.com')
+  })
 
-  it("works with optimistic updates", async () => {
-    const submit = createFetchSubmit();
+  it('works with optimistic updates', async () => {
+    const submit = createFetchSubmit()
     const { result } = renderHook(() =>
       useActionForm({
         submit,
-        defaultValues: { title: "New Todo" },
-        optimisticReducer: (current: Record<string, unknown>, formValues: Record<string, unknown>) => ({
+        defaultValues: { title: 'New Todo' },
+        optimisticReducer: (
+          current: Record<string, unknown>,
+          formValues: Record<string, unknown>,
+        ) => ({
           ...current,
           title: formValues.title,
         }),
-        optimisticDefault: { title: "Old Todo" },
+        optimisticDefault: { title: 'Old Todo' },
       }),
-    );
+    )
 
-    expect(result.current.optimistic).toBeDefined();
-    expect(result.current.optimistic?.data).toEqual({ title: "Old Todo" });
-  });
-});
+    expect(result.current.optimistic).toBeDefined()
+    expect(result.current.optimistic?.data).toEqual({ title: 'Old Todo' })
+  })
+})

From 1cc6a240329bce6c14a87b3dc799d25409d9ff45 Mon Sep 17 00:00:00 2001
From: Gabriel <gabriel_paes@live.com>
Date: Mon, 9 Mar 2026 19:07:58 -0300
Subject: [PATCH 4/5] chore-ignore-claude-folder

---
 .claude/settings.local.json | 18 ------------------
 .gitignore                  |  1 +
 2 files changed, 1 insertion(+), 18 deletions(-)
 delete mode 100644 .claude/settings.local.json

diff --git a/.claude/settings.local.json b/.claude/settings.local.json
deleted file mode 100644
index fa28abc..0000000
--- a/.claude/settings.local.json
+++ /dev/null
@@ -1,18 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(pnpm tsc:*)",
-      "Bash(pnpm build:*)",
-      "Bash(pnpm dlx publint:*)",
-      "Bash(pnpm dlx madge:*)",
-      "Bash(pnpm dlx jscpd:*)",
-      "Bash(pnpm turbo build:*)",
-      "Bash(pnpm test:*)",
-      "Bash(pnpm add:*)",
-      "Bash(pnpm install:*)",
-      "Bash(npx biome check:*)",
-      "Bash(pnpm lint:*)",
-      "Bash(pnpm check-types)"
-    ]
-  }
-}
diff --git a/.gitignore b/.gitignore
index 2db59c1..b0c87b6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,3 +6,4 @@ coverage
 *.tsbuildinfo
 .env
 .env.local
+.claude/

From 68f9e9884a4d40215aa91773bb82ed58aa1f2d27 Mon Sep 17 00:00:00 2001
From: Gabriel <gabriel_paes@live.com>
Date: Mon, 9 Mar 2026 19:17:47 -0300
Subject: [PATCH 5/5] chore-add-changeset-for-npm-release

---
 .changeset/release-4-0-4.md | 8 ++++++++
 1 file changed, 8 insertions(+)
 create mode 100644 .changeset/release-4-0-4.md

diff --git a/.changeset/release-4-0-4.md b/.changeset/release-4-0-4.md
new file mode 100644
index 0000000..472be7b
--- /dev/null
+++ b/.changeset/release-4-0-4.md
@@ -0,0 +1,8 @@
+---
+'hookform-action': patch
+'hookform-action-core': patch
+'hookform-action-standalone': patch
+'hookform-action-devtools': patch
+---
+
+Publish a patch release with the latest docs, examples, lint/format alignment, and core adapter consistency updates.