attaform 0.22.0 → 0.24.0

package/dist/shared/{attaform.FN0vaQAg.d.mts → attaform.CwFZGv5-.d.ts}

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { G as GenericForm, w as FlatPath, S as NestedType, F as FormKey, U as UseFormConfiguration, a as AbstractSchema, D as DefaultValuesInput, au as ValidateOnConfig, b as UseFormReturnType } from './attaform.DvUH4a3o.mjs';
+import { G as GenericForm, u as FlatPath, O as NestedType, F as FormKey, U as UseFormConfiguration, a as AbstractSchema, D as DefaultValuesInput, af as ValidateOnConfig, b as UseFormReturnType } from './attaform.GJbSmwLB.js';
 
 /**
  * The shape `form.values.<key>` returns at runtime.
@@ -120,6 +120,38 @@ type StorageLeaf<L> = InputIsUnknown<L> extends true ? unknown : L extends {
     };
 } ? Out : never;
 
+/**
+ * The Zod v4 schema roots `useForm` accepts. A fixed-shape
+ * `z.object({ … })` is the common case; `z.record(K, V)` admits a
+ * dictionary form (a homogeneous map with runtime-known keys);
+ * `z.discriminatedUnion(disc, [...])` admits a variant form (one of
+ * several object shapes, picked by a discriminator). Each projects to
+ * a `GenericForm`-shaped value the form engine drives: an object root
+ * descends into its fixed keys, a record root treats its entries as an
+ * open live-keyed container, a variant root lifts the active variant's
+ * keys into one addressable surface.
+ *
+ * Other roots (a bare `z.union`, a root `z.array`, primitives,
+ * `z.map` / `z.set`) are not form roots; wrap them under a key. The
+ * adapter's runtime construction rejects them with a legible error.
+ *
+ * `z.ZodObject` MUST keep its `z.ZodRawShape` argument, and the
+ * discriminated-union arm MUST stay fully applied. The unified entry's
+ * v4 overload constrains on `SupportedRootSchema & ZodV4Internals` to
+ * keep v3 schemas out (see `../unified/types-zod-major.ts`). In a
+ * single-major (v3-only) consumer install, the published `.d.mts`
+ * resolves this `z` to v3, where a bare or under-applied Zod class is
+ * missing its required arguments and degrades to an `any`-like error
+ * type; `any` then absorbs the union and `any & ZodV4Internals`
+ * collapses back to `any`, so the marker stops excluding v3 schemas and
+ * the read slot poisons to `never`. `z.ZodRecord` carries defaults for
+ * both arguments, so it stays concrete in either major.
+ * `z.ZodDiscriminatedUnion` does NOT (v3 requires both arguments, and
+ * its parameter order is the reverse of v4's), so the arm is written
+ * fully applied; the v3-only bundled-types fixture guards it.
+ */
+type SupportedRootSchema = z.ZodObject<z.ZodRawShape> | z.ZodRecord | z.ZodDiscriminatedUnion<readonly z.ZodObject<z.ZodRawShape>[], string>;
+
 /**
  * Zod v4 adapter entry point. Re-exports the adapter + the useForm
  * wrapper that threads zod-v4-specific schema types through
@@ -188,12 +220,12 @@ type PathOutput<Schema extends z.ZodType, Path extends string> = z.output<Schema
  * generics ride on the alias rather than re-evaluating the
  * conditional from scratch.
  */
-type FormOf<Schema extends z.ZodObject> = z.input<Schema> extends GenericForm ? z.input<Schema> : never;
-type OutOf<Schema extends z.ZodObject> = z.output<Schema> extends GenericForm ? z.output<Schema> : never;
-type ReadOf<Schema extends z.ZodObject> = StorageShape<Schema> extends GenericForm ? StorageShape<Schema> : never;
-declare function useForm<Schema extends z.ZodObject, K extends FormKey = FormKey>(configuration: Omit<UseFormConfiguration<FormOf<Schema>, OutOf<Schema>, AbstractSchema<FormOf<Schema>, OutOf<Schema>>, DefaultValuesInput<FormOf<Schema>>, K>, 'schema' | 'validateOn' | 'debounceMs'> & {
+type FormOf<Schema extends SupportedRootSchema> = z.input<Schema> extends GenericForm ? z.input<Schema> : never;
+type OutOf<Schema extends SupportedRootSchema> = z.output<Schema> extends GenericForm ? z.output<Schema> : never;
+type ReadOf<Schema extends SupportedRootSchema> = StorageShape<Schema> extends GenericForm ? StorageShape<Schema> : never;
+declare function useForm<Schema extends SupportedRootSchema, K extends FormKey = FormKey>(configuration: Omit<UseFormConfiguration<FormOf<Schema>, OutOf<Schema>, AbstractSchema<FormOf<Schema>, OutOf<Schema>>, DefaultValuesInput<FormOf<Schema>>, K>, 'schema' | 'validateOn' | 'debounceMs'> & {
     schema: Schema;
 } & ValidateOnConfig): UseFormReturnType<FormOf<Schema>, OutOf<Schema>, ReadOf<Schema>, K>;
 
 export { useForm as u };
-export type { PathInput as P, StorageShape as S, PathOutput as a };
+export type { PathInput as P, SupportedRootSchema as S, PathOutput as a, StorageShape as b };

package/dist/shared/{attaform.BGwNZ9GV.d.cts → attaform.DdUYEhkV.d.cts}

@@ -1,4 +1,4 @@
-import { F as FormKey, a5 as PathKey, p as DisplayCtx, d as GetDisplayState, q as DisplayMachine, a4 as Path, ap as SlimPrimitiveKind, C as CoercionEntry, j as CoercionRegistry, G as GenericForm, V as ValidationError, a as AbstractSchema, ay as WriteMeta, m as DeepPartial, az as WriteShape, aG as TransformAbortHolder, at as ValidateOn, $ as OnChangeSource, Z as OnChangeHandler, _ as OnChangeOptions, aH as PersistOptInRegistry, A as AttaformDefaults, b as UseFormReturnType, c as RegisterValue } from './attaform.DvUH4a3o.cjs';
+import { F as FormKey, W as PathKey, m as DisplayCtx, d as GetDisplayState, n as DisplayMachine, V as Path, aa as SlimPrimitiveKind, C as CoercionEntry, g as CoercionRegistry, G as GenericForm, ag as ValidationError, a as AbstractSchema, ak as WriteMeta, j as DeepPartial, al as WriteShape, as as TransformAbortHolder, ae as ValidateOn, A as AttaformDefaults, b as UseFormReturnType, c as RegisterValue } from './attaform.GJbSmwLB.cjs';
 import { Ref, ComputedRef, App, InjectionKey } from 'vue';
 
 /**
@@ -643,12 +643,12 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * Schema-driven errors. Written ONLY by the schema validation pipeline:
      * `scheduleFieldValidation`, `handleSubmit`, the construction-time seed,
      * history restore, and hydration. Cleared by `reset` / `resetField` and by
-     * a successful submit. `setFieldErrors*` APIs do NOT touch this Map.
+     * a successful submit. `setErrors` / `clearErrors` do NOT touch this Map.
      */
     readonly schemaErrors: Map<PathKey, ValidationError[]>;
     /**
-     * User-injected errors. Written ONLY by the `setFieldErrors*` API surfaces
-     * (and history / hydration replay). Survives schema revalidation and
+     * User-injected errors. Written ONLY by the `setErrors` / `clearErrors`
+     * API surface (and history / hydration replay). Survives schema revalidation and
      * successful submits — the consumer owns its lifetime explicitly.
      */
     readonly userErrors: Map<PathKey, ValidationError[]>;
@@ -967,17 +967,13 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
     /**
      * Replace the form value wholesale. Optional `meta` is forwarded to
      * every `onFormChange` listener so they can decide whether THIS write
-     * is one they care about — most importantly, the persistence layer
-     * only writes when `meta?.persist === true`. Internal callers that
-     * don't pass meta default to no-persist.
+     * is one they care about (e.g. history tagging a hydration replay).
      */
     applyFormReplacement(next: F, meta?: WriteMeta): void;
     /**
      * Set a single path's value. `meta` is forwarded to listeners via
-     * `applyFormReplacement` (see above). The directive's input handler
-     * computes `meta.persist` from the per-element opt-in registry; other
-     * internal call sites pass `meta.persist = hasAnyOptInForPath(path)`.
-     * Public `form.setValue` passes no meta.
+     * `applyFormReplacement` (see above). Public `form.setValue` passes no
+     * meta.
      *
      * Returns `false` when the slim-primitive gate rejects the write
      * (the value's primitive shape doesn't match the schema's slim
@@ -1009,7 +1005,7 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      */
     applySchemaErrorsForSubtree(path: Path, errors: ValidationError[]): void;
     setAllUserErrors(errors: readonly ValidationError[]): void;
-    addUserErrors(errors: readonly ValidationError[]): void;
+    setUserErrorsForPath(path: Path, errors: readonly ValidationError[]): void;
     clearUserErrors(path?: Path): void;
     /**
      * Merged read — returns `[...schemaErrors[path], ...userErrors[path]]`.
@@ -1191,28 +1187,17 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
     /**
      * Subscribe to every `applyFormReplacement`. Fires synchronously
      * after `form.value` has been swapped to `next` and all field /
-     * originals bookkeeping has run. Used by persistence + undo/redo
-     * to hook the single mutation funnel. The optional `meta` carries
-     * the originating call site's intent — the persistence subscription
-     * filters on `meta?.persist === true`; subscribers that don't care
-     * about meta can ignore the parameter. Returns an unsubscribe
-     * function.
+     * originals bookkeeping has run. Used by undo/redo to hook the single
+     * mutation funnel. The optional `meta` carries the originating call
+     * site's intent; subscribers that don't care about meta can ignore the
+     * parameter. Returns an unsubscribe function.
      */
     onFormChange(listener: (next: F, meta?: WriteMeta) => void): () => void;
-    /**
-     * Register a `form.onChange` side-channel handler. `source === undefined`
-     * is the whole form (root); `getForm` lazily resolves the public form
-     * handle for `ctx.form`. Returns an idempotent `stop()`. A no-op on SSR.
-     * The public `form.onChange` overloads and `useForm({ onChange })` wire
-     * through here; dispatch happens in `commitWritePatches`.
-     */
-    registerOnChange(source: OnChangeSource | undefined, handler: OnChangeHandler, options: OnChangeOptions | undefined, getForm: () => unknown): () => void;
     /**
      * Subscribe to successful submissions. Fires after the consumer's
      * `onSubmit` callback has resolved — not on validation failure,
-     * not on callback throw. Used by persistence's `clearOnSubmitSuccess`
-     * to drop the stored payload once the form is safely through the
-     * server round-trip. Returns an unsubscribe function.
+     * not on callback throw. The DevTools panel rides this to surface a
+     * submit event. Returns an unsubscribe function.
      */
     onSubmitSuccess(listener: () => void): () => void;
     /**
@@ -1258,58 +1243,6 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * owned by the caller (e.g. `'history'`).
      */
     readonly modules: Map<string, unknown>;
-    /**
-     * Per-element persistence opt-in tracker. Empty by default; the
-     * `v-register` directive populates entries on `mount` for each binding
-     * that passed `register('foo', { persist: true })` and clears them on
-     * `beforeUnmount`. Two SFCs sharing a key share this registry — opt-ins
-     * are per-DOM-element, not per-component. Internal to the persistence
-     * subsystem; not part of the consumer API surface.
-     */
-    readonly persistOptIns: PersistOptInRegistry;
-    /**
-     * Resolved sensitive-path predicate for THIS form. Honors the
-     * cascade (`useForm({ sensitiveNames })` > global default >
-     * library `DEFAULT_SENSITIVE_NAMES`). Used by:
-     *  - the persistence opt-in gate (`allowSensitivePersist`);
-     *  - the multi-tab sync module (outbound strip + inbound reject);
-     *  - DevTools edit rejection;
-     *  - any future surface that needs to flag "this path holds
-     *    sensitive data."
-     *
-     * Frozen at FormStore construction. Two callsites sharing a key
-     * share the predicate — consistent with the rest of the per-form
-     * resolved-config surface.
-     */
-    readonly isSensitivePath: (path: Path | PathKey | string) => boolean;
-    /**
-     * Canonical path keys explicitly opted OUT of multi-tab sync by
-     * `register(path, { multiTab: false })`. The sync module's outbound
-     * broadcaster strips patches at these paths AND the inbound listener
-     * rejects them — symmetric tab-local behaviour for selected fields.
-     *
-     * Read-only Set view; mutate via `incrementNoSyncOptOut` /
-     * `decrementNoSyncOptOut` which maintain a per-path ref count so
-     * multiple bindings on the same path balance correctly across
-     * dynamic conditional renders. Empty by default.
-     */
-    readonly noSyncPaths: ReadonlySet<PathKey>;
-    /**
-     * Ref-counted "this path is tab-local" registration. Called by
-     * `v-register`'s `created` hook for any binding that declared
-     * `register('x', { multiTab: false })`. The first call for a given
-     * path adds it to `noSyncPaths`; subsequent calls just bump the
-     * ref count. Pair with `decrementNoSyncOptOut`.
-     */
-    incrementNoSyncOptOut(path: PathKey): void;
-    /**
-     * Symmetric companion to `incrementNoSyncOptOut`. Called by
-     * `v-register`'s `beforeUnmount` hook. When the ref count for a
-     * path drops to zero, the path is removed from `noSyncPaths` —
-     * dynamic toggling (the binding rendered conditionally) restores
-     * full sync to the path when the last opt-out unmounts.
-     */
-    decrementNoSyncOptOut(path: PathKey): void;
     /**
      * Resolved schema-coercion index — the merged config from
      * `createAttaform({ defaults: { coerce } })` ∪ `useForm({ coerce })`,
@@ -1378,9 +1311,8 @@ type SerializedFormData = {
      */
     readonly schemaErrors: ReadonlyArray<readonly [string, unknown]>;
     /**
-     * Errors set explicitly via `setFieldErrors` / `addFieldErrors`
-     * (typically from a server response parsed via `parseApiErrors`)
-     * at snapshot time. Replayed at hydration; persists across
+     * Errors set explicitly via `setErrors` (typically a server
+     * response) at snapshot time. Replayed at hydration; persists across
      * client-side re-validation.
      */
     readonly userErrors: ReadonlyArray<readonly [string, unknown]>;
@@ -1808,9 +1740,9 @@ declare function lazy<Ctx = WizardCtx>(resolve: (ctx: Ctx) => AnyForm | string |
  *   `issue.code` (e.g. `zod:too_small`). No enum here because
  *   Zod's code list evolves.
  * - consumer-defined — anything the consumer's backend / app stamps
- *   onto a `ValidationError` (via the `parseApiErrors` wire payload
- *   or `setFieldErrors` directly). Pick a scope (`api:`, `auth:`,
- *   etc.) and stay consistent.
+ *   onto a `ValidationError` (a server response handed to `setErrors`,
+ *   or a code passed inline). Pick a scope (`api:`, `auth:`, etc.) and
+ *   stay consistent.
  *
  * Use these constants in tests and error-routing UI:
  *
@@ -1854,6 +1786,14 @@ declare const AttaformErrorCode: {
      * `form.hydrateError` for retry UX.
      */
     readonly ActivationFailed: "atta:activation-failed";
+    /**
+     * Default code stamped on a manual error set through `form.setErrors`
+     * when the caller omits an explicit `code`. The `setErrors` input is
+     * lenient (`code` optional), so this is the fallback that keeps every
+     * produced `ValidationError` carrying a stable, branchable identifier.
+     * Override it per error by passing your own `code` (`api:…`, `auth:…`).
+     */
+    readonly UserError: "atta:user-error";
 };
 type AttaformErrorCode = (typeof AttaformErrorCode)[keyof typeof AttaformErrorCode];
 

package/dist/shared/attaform.DdjDqTah.d.cts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+/**
+ * Peel `.optional()` / `.nullable()` / `.default()` / `.refine()` /
+ * `.transform()` wrappers off a Zod v3 schema to reach the form root,
+ * then return it: a `ZodObject` (fixed-shape form), a `ZodRecord`
+ * (dictionary form), or a `ZodDiscriminatedUnion` (variant form).
+ * Returns `never` for any other root, which makes the `useForm`
+ * projections collapse to `never` so the call fails to typecheck
+ * rather than producing a misshapen form type.
+ *
+ * Used internally by the v3 `useForm` overload to project an arbitrary
+ * supported root to its input / output / storage-read shapes.
+ */
+type UnwrapZodRoot<T> = T extends z.ZodEffects<infer Inner> ? UnwrapZodRoot<Inner> : T extends z.ZodOptional<infer Inner> ? UnwrapZodRoot<Inner> : T extends z.ZodNullable<infer Inner> ? UnwrapZodRoot<Inner> : T extends z.ZodDefault<infer Inner> ? UnwrapZodRoot<Inner> : T extends z.ZodObject<infer Shape> ? z.ZodObject<Shape> : T extends z.ZodRecord<infer Key, infer Value> ? z.ZodRecord<Key, Value> : T extends z.ZodDiscriminatedUnion<infer Disc, infer Options> ? z.ZodDiscriminatedUnion<Disc, Options> : never;
+
+/**
+ * The Zod v3 schema roots `useForm` accepts. Mirror of the v4
+ * `SupportedRootSchema`, expressed in v3's type vocabulary: a
+ * fixed-shape `z.object({ … })`, a `z.record(K, V)` dictionary form, or
+ * a `z.discriminatedUnion(disc, [...])` variant form.
+ *
+ * Other roots (a bare `z.union`, a root `z.array`, primitives,
+ * `z.map` / `z.set`) are not form roots; wrap them under a key. The
+ * adapter's runtime construction rejects them with a legible error.
+ *
+ * The discriminated-union arm is written with v3's parameter order
+ * (`<Discriminator, Options>`), the reverse of v4's; both classes
+ * require their arguments, so the arm stays fully applied to avoid the
+ * single-major `any`-collapse the v4 alias documents.
+ */
+type SupportedRootSchema = z.ZodObject<z.ZodRawShape> | z.ZodRecord<z.ZodTypeAny, z.ZodTypeAny> | z.ZodDiscriminatedUnion<string, readonly z.ZodDiscriminatedUnionOption<string>[]>;
+
+/**
+ * v3 mirror of the Zod v4 `StorageShape`. Per top-level key, default
+ * to `z.output<Shape[K]>` (the post-init view — defaults have fired,
+ * Zod's own recursion peels nested defaults inside structural
+ * containers); fall back to `z.input<Shape[K]>` for transform / pipe
+ * carriers (`ZodEffects`, `ZodPipeline`) where storage holds the
+ * pre-transform input — transforms only run at submission /
+ * validation, not at the write boundary.
+ *
+ * v3 quirk: `ZodEffects` covers BOTH `.transform()` and
+ * `z.preprocess()` at the TS level — v3 doesn't carry a separate
+ * preprocess class the way v4 does. Deferring to `z.input` for
+ * `ZodEffects` means a top-level `z.preprocess(fn, T)` leaf reads as
+ * the preprocess input (commonly `unknown`); reach for the
+ * `AbstractSchema` escape hatch if a stronger type is needed.
+ * Transforms preserve their pre-transform input shape, which matches
+ * storage.
+ */
+type StorageShape<S extends z.ZodTypeAny> = S extends z.ZodObject<infer Shape> ? {
+    [K in keyof Shape]-?: Shape[K] extends z.ZodEffects<z.ZodTypeAny> | z.ZodPipeline<z.ZodTypeAny, z.ZodTypeAny> ? z.input<Shape[K]> : z.output<Shape[K]>;
+} : z.input<S>;
+
+export type { SupportedRootSchema as S, UnwrapZodRoot as U, StorageShape as a };

package/dist/shared/attaform.DdjDqTah.d.mts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+/**
+ * Peel `.optional()` / `.nullable()` / `.default()` / `.refine()` /
+ * `.transform()` wrappers off a Zod v3 schema to reach the form root,
+ * then return it: a `ZodObject` (fixed-shape form), a `ZodRecord`
+ * (dictionary form), or a `ZodDiscriminatedUnion` (variant form).
+ * Returns `never` for any other root, which makes the `useForm`
+ * projections collapse to `never` so the call fails to typecheck
+ * rather than producing a misshapen form type.
+ *
+ * Used internally by the v3 `useForm` overload to project an arbitrary
+ * supported root to its input / output / storage-read shapes.
+ */
+type UnwrapZodRoot<T> = T extends z.ZodEffects<infer Inner> ? UnwrapZodRoot<Inner> : T extends z.ZodOptional<infer Inner> ? UnwrapZodRoot<Inner> : T extends z.ZodNullable<infer Inner> ? UnwrapZodRoot<Inner> : T extends z.ZodDefault<infer Inner> ? UnwrapZodRoot<Inner> : T extends z.ZodObject<infer Shape> ? z.ZodObject<Shape> : T extends z.ZodRecord<infer Key, infer Value> ? z.ZodRecord<Key, Value> : T extends z.ZodDiscriminatedUnion<infer Disc, infer Options> ? z.ZodDiscriminatedUnion<Disc, Options> : never;
+
+/**
+ * The Zod v3 schema roots `useForm` accepts. Mirror of the v4
+ * `SupportedRootSchema`, expressed in v3's type vocabulary: a
+ * fixed-shape `z.object({ … })`, a `z.record(K, V)` dictionary form, or
+ * a `z.discriminatedUnion(disc, [...])` variant form.
+ *
+ * Other roots (a bare `z.union`, a root `z.array`, primitives,
+ * `z.map` / `z.set`) are not form roots; wrap them under a key. The
+ * adapter's runtime construction rejects them with a legible error.
+ *
+ * The discriminated-union arm is written with v3's parameter order
+ * (`<Discriminator, Options>`), the reverse of v4's; both classes
+ * require their arguments, so the arm stays fully applied to avoid the
+ * single-major `any`-collapse the v4 alias documents.
+ */
+type SupportedRootSchema = z.ZodObject<z.ZodRawShape> | z.ZodRecord<z.ZodTypeAny, z.ZodTypeAny> | z.ZodDiscriminatedUnion<string, readonly z.ZodDiscriminatedUnionOption<string>[]>;
+
+/**
+ * v3 mirror of the Zod v4 `StorageShape`. Per top-level key, default
+ * to `z.output<Shape[K]>` (the post-init view — defaults have fired,
+ * Zod's own recursion peels nested defaults inside structural
+ * containers); fall back to `z.input<Shape[K]>` for transform / pipe
+ * carriers (`ZodEffects`, `ZodPipeline`) where storage holds the
+ * pre-transform input — transforms only run at submission /
+ * validation, not at the write boundary.
+ *
+ * v3 quirk: `ZodEffects` covers BOTH `.transform()` and
+ * `z.preprocess()` at the TS level — v3 doesn't carry a separate
+ * preprocess class the way v4 does. Deferring to `z.input` for
+ * `ZodEffects` means a top-level `z.preprocess(fn, T)` leaf reads as
+ * the preprocess input (commonly `unknown`); reach for the
+ * `AbstractSchema` escape hatch if a stronger type is needed.
+ * Transforms preserve their pre-transform input shape, which matches
+ * storage.
+ */
+type StorageShape<S extends z.ZodTypeAny> = S extends z.ZodObject<infer Shape> ? {
+    [K in keyof Shape]-?: Shape[K] extends z.ZodEffects<z.ZodTypeAny> | z.ZodPipeline<z.ZodTypeAny, z.ZodTypeAny> ? z.input<Shape[K]> : z.output<Shape[K]>;
+} : z.input<S>;
+
+export type { SupportedRootSchema as S, UnwrapZodRoot as U, StorageShape as a };

package/dist/shared/attaform.DdjDqTah.d.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+/**
+ * Peel `.optional()` / `.nullable()` / `.default()` / `.refine()` /
+ * `.transform()` wrappers off a Zod v3 schema to reach the form root,
+ * then return it: a `ZodObject` (fixed-shape form), a `ZodRecord`
+ * (dictionary form), or a `ZodDiscriminatedUnion` (variant form).
+ * Returns `never` for any other root, which makes the `useForm`
+ * projections collapse to `never` so the call fails to typecheck
+ * rather than producing a misshapen form type.
+ *
+ * Used internally by the v3 `useForm` overload to project an arbitrary
+ * supported root to its input / output / storage-read shapes.
+ */
+type UnwrapZodRoot<T> = T extends z.ZodEffects<infer Inner> ? UnwrapZodRoot<Inner> : T extends z.ZodOptional<infer Inner> ? UnwrapZodRoot<Inner> : T extends z.ZodNullable<infer Inner> ? UnwrapZodRoot<Inner> : T extends z.ZodDefault<infer Inner> ? UnwrapZodRoot<Inner> : T extends z.ZodObject<infer Shape> ? z.ZodObject<Shape> : T extends z.ZodRecord<infer Key, infer Value> ? z.ZodRecord<Key, Value> : T extends z.ZodDiscriminatedUnion<infer Disc, infer Options> ? z.ZodDiscriminatedUnion<Disc, Options> : never;
+
+/**
+ * The Zod v3 schema roots `useForm` accepts. Mirror of the v4
+ * `SupportedRootSchema`, expressed in v3's type vocabulary: a
+ * fixed-shape `z.object({ … })`, a `z.record(K, V)` dictionary form, or
+ * a `z.discriminatedUnion(disc, [...])` variant form.
+ *
+ * Other roots (a bare `z.union`, a root `z.array`, primitives,
+ * `z.map` / `z.set`) are not form roots; wrap them under a key. The
+ * adapter's runtime construction rejects them with a legible error.
+ *
+ * The discriminated-union arm is written with v3's parameter order
+ * (`<Discriminator, Options>`), the reverse of v4's; both classes
+ * require their arguments, so the arm stays fully applied to avoid the
+ * single-major `any`-collapse the v4 alias documents.
+ */
+type SupportedRootSchema = z.ZodObject<z.ZodRawShape> | z.ZodRecord<z.ZodTypeAny, z.ZodTypeAny> | z.ZodDiscriminatedUnion<string, readonly z.ZodDiscriminatedUnionOption<string>[]>;
+
+/**
+ * v3 mirror of the Zod v4 `StorageShape`. Per top-level key, default
+ * to `z.output<Shape[K]>` (the post-init view — defaults have fired,
+ * Zod's own recursion peels nested defaults inside structural
+ * containers); fall back to `z.input<Shape[K]>` for transform / pipe
+ * carriers (`ZodEffects`, `ZodPipeline`) where storage holds the
+ * pre-transform input — transforms only run at submission /
+ * validation, not at the write boundary.
+ *
+ * v3 quirk: `ZodEffects` covers BOTH `.transform()` and
+ * `z.preprocess()` at the TS level — v3 doesn't carry a separate
+ * preprocess class the way v4 does. Deferring to `z.input` for
+ * `ZodEffects` means a top-level `z.preprocess(fn, T)` leaf reads as
+ * the preprocess input (commonly `unknown`); reach for the
+ * `AbstractSchema` escape hatch if a stronger type is needed.
+ * Transforms preserve their pre-transform input shape, which matches
+ * storage.
+ */
+type StorageShape<S extends z.ZodTypeAny> = S extends z.ZodObject<infer Shape> ? {
+    [K in keyof Shape]-?: Shape[K] extends z.ZodEffects<z.ZodTypeAny> | z.ZodPipeline<z.ZodTypeAny, z.ZodTypeAny> ? z.input<Shape[K]> : z.output<Shape[K]>;
+} : z.input<S>;
+
+export type { SupportedRootSchema as S, UnwrapZodRoot as U, StorageShape as a };