attaform 0.17.0 → 0.17.2

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

@@ -0,0 +1,165 @@
+import { z } from 'zod';
+import { G as GenericForm, s as FlatPath, B as NestedType, U as UseFormConfiguration, b as AbstractSchema, D as DeepPartial, c as DefaultValuesShape, ag as ValidateOnConfig, d as UseFormReturnType } from './attaform.C_5aB6EQ.js';
+
+/**
+ * The shape `form.values.<key>` returns at runtime.
+ *
+ * Per leaf:
+ *
+ * 1. `z.preprocess(fn, inner)` — compiles to `ZodPipe<ZodTransform, inner>`.
+ *    The preprocess fn fires at the write boundary (synthesized into
+ *    `setValue`), so storage holds whatever `inner` stores. Recurse
+ *    `StorageShape` on `inner` so a defaulted leaf inside `inner` still
+ *    reads `T` (not `T | undefined`).
+ *
+ * 2. `inner.transform(fn)` — compiles to `ZodPipe<inner, ZodTransform>`.
+ *    Transforms fire at submit / validate, NOT at the write boundary,
+ *    so storage holds whatever `inner` stores. Recurse `StorageShape`
+ *    on `inner` for the same reason.
+ *
+ *    A bare top-level `ZodTransform` (no `in` schema) reads
+ *    `_zod.input` directly — there's no inner to recurse into.
+ *
+ * 3. Codec / generic pipe — neither side is a transform. Read
+ *    `_zod.output`. Codecs aren't write-boundary-synthesized, so the
+ *    post-parse view is the only honest storage type.
+ *
+ * 4. Everything else (defaults, catch, readonly, optional, primitives,
+ *    nested objects) — read `_zod.output`. Defaults and catches fire
+ *    at parse time, so the post-init view is what storage holds.
+ *    Nested objects delegate to Zod's own recursion on `_zod.output`,
+ *    which peels nested defaults inside structural containers.
+ *
+ * Recursion: the alias calls itself on the non-transform side of a
+ * pipe so the inner shape gets the same per-key storage treatment as
+ * the top level. Without it, an inner `.default(...)` inside a
+ * transformed object would peel back to `T | undefined` (the broad
+ * input contract). Recursion only fires for pipe leaves — most leaves
+ * skip it.
+ *
+ * Implementation note: direct `_zod` property access mirrors Zod's
+ * own `$InferObjectOutput` / `$InferObjectInput`, which read
+ * `T[k]['_zod']['output']` / `T[k]['_zod']['input']` directly rather
+ * than wrapping in the top-level `output<T>` / `input<T>` conditional.
+ * Wrapping per key spawns a fresh conditional instantiation for every
+ * key; Volar's web-worker checker collapses that per-key walk to
+ * `any` once the schema is non-trivial. Property access has no
+ * conditional and resolves cleanly under the same budget.
+ *
+ * Shape access also goes through `_zod.def.shape` rather than
+ * `infer Shape from z.ZodObject<Shape>` — the latter collapses to the
+ * `$ZodShape` upper bound in the same worker because of
+ * `z.ZodObject`'s `out Shape` covariance markers.
+ */
+type StorageShape<S> = S extends {
+    _zod: {
+        def: {
+            type: 'object';
+            shape: infer Shape;
+        };
+    };
+} ? {
+    [K in keyof Shape]-?: StorageLeaf<Shape[K]>;
+} : StorageLeaf<S>;
+type StorageLeaf<L> = L extends {
+    _zod: {
+        def: {
+            type: 'pipe';
+            in: infer A;
+            out: infer B;
+        };
+    };
+} ? A extends {
+    _zod: {
+        def: {
+            type: 'transform';
+        };
+    };
+} ? StorageShape<B> : B extends {
+    _zod: {
+        def: {
+            type: 'transform';
+        };
+    };
+} ? StorageShape<A> : L extends {
+    _zod: {
+        output: infer Out;
+    };
+} ? Out : never : L extends {
+    _zod: {
+        def: {
+            type: 'transform';
+        };
+    };
+} ? L extends {
+    _zod: {
+        input: infer In;
+    };
+} ? In : never : L extends {
+    _zod: {
+        output: infer Out;
+    };
+} ? Out : never;
+
+/**
+ * Zod v4 adapter entry point. Re-exports the adapter + the useForm
+ * wrapper that threads zod-v4-specific schema types through
+ * useAbstractForm.
+ */
+
+/**
+ * Type of the value accepted at `Path` for `setValue` / `defaultValues`
+ * — the schema's `z.input<Schema>` shape at that path. Matches what
+ * `form.values.X` returns at runtime (the honest input view storage
+ * holds before transforms run).
+ *
+ * ```ts
+ * const schema = z.object({
+ *   flag: z.string().transform((v) => v.length > 10),
+ * })
+ * type FlagWriteIn = PathInput<typeof schema, 'flag'> // string
+ * ```
+ */
+type PathInput<Schema extends z.ZodType, Path extends string> = z.input<Schema> extends GenericForm ? Path extends FlatPath<z.input<Schema>> ? NestedType<z.input<Schema>, Path> : never : never;
+/**
+ * Type produced at `Path` after the full parse pipeline — the schema's
+ * `z.output<Schema>` shape at that path. Matches the `data` payload of
+ * `form.process()` and the value handed to `handleSubmit`'s callback.
+ *
+ * ```ts
+ * const schema = z.object({
+ *   flag: z.string().transform((v) => v.length > 10),
+ * })
+ * type FlagParsedOut = PathOutput<typeof schema, 'flag'> // boolean
+ * ```
+ */
+type PathOutput<Schema extends z.ZodType, Path extends string> = z.output<Schema> extends GenericForm ? Path extends FlatPath<z.output<Schema>> ? NestedType<z.output<Schema>, Path> : never : never;
+/**
+ * Create a form bound to a Zod v4 schema.
+ *
+ * ```ts
+ * import { useForm } from 'attaform/zod'
+ * import { z } from 'zod'
+ *
+ * const form = useForm({
+ *   schema: z.object({
+ *     email: z.email(),
+ *     password: z.string().min(8),
+ *   }),
+ *   defaultValues: { email: '' },
+ * })
+ * ```
+ *
+ * Returns a form API exposing `register`, `values`, `errors`,
+ * `fields`, `setValue`, `handleSubmit`, `meta`, field-array
+ * helpers, and more. See `UseFormReturnType` for the full
+ * surface.
+ *
+ * For Zod v3, import from `attaform/zod-v3` instead.
+ */
+declare function useForm<Schema extends z.ZodObject>(configuration: Omit<UseFormConfiguration<z.input<Schema> extends GenericForm ? z.input<Schema> : never, z.output<Schema> extends GenericForm ? z.output<Schema> : never, AbstractSchema<z.input<Schema> extends GenericForm ? z.input<Schema> : never, z.output<Schema> extends GenericForm ? z.output<Schema> : never>, DeepPartial<DefaultValuesShape<z.input<Schema> extends GenericForm ? z.input<Schema> : never>>>, 'schema' | 'validateOn' | 'debounceMs'> & {
+    schema: Schema;
+} & ValidateOnConfig): UseFormReturnType<z.input<Schema> extends GenericForm ? z.input<Schema> : never, z.output<Schema> extends GenericForm ? z.output<Schema> : never, StorageShape<Schema> extends GenericForm ? StorageShape<Schema> : never>;
+
+export { useForm as u };
+export type { PathInput as P, StorageShape as S, PathOutput as a };

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

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { ag as ValidateOnConfig, F as FormKey, E as OnInvalidSubmitPolicy, X as PersistConfig, y as HistoryConfig, C as CoercionRegistry } from './attaform.C_5aB6EQ.mjs';
+
+/**
+ * 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>;
+
+/**
+ * Configuration object for the Zod v3 `useForm` overload. Same
+ * shape as the schema-agnostic `UseFormConfiguration`, but with
+ * `schema` constrained to a `z.ZodObject` (or wrapped form).
+ */
+type UseFormConfigurationWithZod<Schema extends z.ZodType<unknown>, DefaultValues> = ValidateOnConfig & {
+    /** A Zod v3 `ZodObject` schema (or one wrapped in `.optional()` / `.nullable()` / `.default()` / `.refine()`). */
+    schema: Schema extends z.ZodType<unknown> ? UnwrapZodObject<Schema> extends z.ZodObject<z.ZodRawShape> ? Schema : never : never;
+    key?: FormKey;
+    defaultValues?: DefaultValues;
+    strict?: boolean;
+    onInvalidSubmit?: OnInvalidSubmitPolicy;
+    persist?: PersistConfig;
+    history?: HistoryConfig;
+    rememberVariants?: boolean;
+    coerce?: boolean | CoercionRegistry;
+};
+/**
+ * Peel `.optional()` / `.nullable()` / `.default()` / `.refine()` /
+ * `.transform()` wrappers off a Zod v3 schema to reach the inner
+ * `ZodObject`. Returns `never` if no `ZodObject` is found.
+ *
+ * Used internally by the v3 `useForm` overload to verify the
+ * supplied schema bottoms out at a `ZodObject`.
+ */
+type UnwrapZodObject<T> = T extends z.ZodEffects<infer Inner> ? UnwrapZodObject<Inner> : T extends z.ZodOptional<infer Inner> ? UnwrapZodObject<Inner> : T extends z.ZodNullable<infer Inner> ? UnwrapZodObject<Inner> : T extends z.ZodDefault<infer Inner> ? UnwrapZodObject<Inner> : T extends z.ZodObject<infer Shape> ? z.ZodObject<Shape> : never;
+
+export type { StorageShape as S, UnwrapZodObject as U, UseFormConfigurationWithZod as a };

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

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { ag as ValidateOnConfig, F as FormKey, E as OnInvalidSubmitPolicy, X as PersistConfig, y as HistoryConfig, C as CoercionRegistry } from './attaform.C_5aB6EQ.js';
+
+/**
+ * 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>;
+
+/**
+ * Configuration object for the Zod v3 `useForm` overload. Same
+ * shape as the schema-agnostic `UseFormConfiguration`, but with
+ * `schema` constrained to a `z.ZodObject` (or wrapped form).
+ */
+type UseFormConfigurationWithZod<Schema extends z.ZodType<unknown>, DefaultValues> = ValidateOnConfig & {
+    /** A Zod v3 `ZodObject` schema (or one wrapped in `.optional()` / `.nullable()` / `.default()` / `.refine()`). */
+    schema: Schema extends z.ZodType<unknown> ? UnwrapZodObject<Schema> extends z.ZodObject<z.ZodRawShape> ? Schema : never : never;
+    key?: FormKey;
+    defaultValues?: DefaultValues;
+    strict?: boolean;
+    onInvalidSubmit?: OnInvalidSubmitPolicy;
+    persist?: PersistConfig;
+    history?: HistoryConfig;
+    rememberVariants?: boolean;
+    coerce?: boolean | CoercionRegistry;
+};
+/**
+ * Peel `.optional()` / `.nullable()` / `.default()` / `.refine()` /
+ * `.transform()` wrappers off a Zod v3 schema to reach the inner
+ * `ZodObject`. Returns `never` if no `ZodObject` is found.
+ *
+ * Used internally by the v3 `useForm` overload to verify the
+ * supplied schema bottoms out at a `ZodObject`.
+ */
+type UnwrapZodObject<T> = T extends z.ZodEffects<infer Inner> ? UnwrapZodObject<Inner> : T extends z.ZodOptional<infer Inner> ? UnwrapZodObject<Inner> : T extends z.ZodNullable<infer Inner> ? UnwrapZodObject<Inner> : T extends z.ZodDefault<infer Inner> ? UnwrapZodObject<Inner> : T extends z.ZodObject<infer Shape> ? z.ZodObject<Shape> : never;
+
+export type { StorageShape as S, UnwrapZodObject as U, UseFormConfigurationWithZod as a };

package/dist/shared/{attaform.D7lomopc.d.cts → attaform.C6qzEdIM.d.cts}

@@ -1,4 +1,4 @@
-import { G as GenericForm, F as FormKey, d as UseFormReturnType, R as RegisterValue } from './attaform.BYbsV2Wv.cjs';
+import { G as GenericForm, F as FormKey, d as UseFormReturnType, R as RegisterValue } from './attaform.C_5aB6EQ.cjs';
 import { Ref } from 'vue';
 
 /**

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

@@ -0,0 +1,165 @@
+import { z } from 'zod';
+import { G as GenericForm, s as FlatPath, B as NestedType, U as UseFormConfiguration, b as AbstractSchema, D as DeepPartial, c as DefaultValuesShape, ag as ValidateOnConfig, d as UseFormReturnType } from './attaform.C_5aB6EQ.cjs';
+
+/**
+ * The shape `form.values.<key>` returns at runtime.
+ *
+ * Per leaf:
+ *
+ * 1. `z.preprocess(fn, inner)` — compiles to `ZodPipe<ZodTransform, inner>`.
+ *    The preprocess fn fires at the write boundary (synthesized into
+ *    `setValue`), so storage holds whatever `inner` stores. Recurse
+ *    `StorageShape` on `inner` so a defaulted leaf inside `inner` still
+ *    reads `T` (not `T | undefined`).
+ *
+ * 2. `inner.transform(fn)` — compiles to `ZodPipe<inner, ZodTransform>`.
+ *    Transforms fire at submit / validate, NOT at the write boundary,
+ *    so storage holds whatever `inner` stores. Recurse `StorageShape`
+ *    on `inner` for the same reason.
+ *
+ *    A bare top-level `ZodTransform` (no `in` schema) reads
+ *    `_zod.input` directly — there's no inner to recurse into.
+ *
+ * 3. Codec / generic pipe — neither side is a transform. Read
+ *    `_zod.output`. Codecs aren't write-boundary-synthesized, so the
+ *    post-parse view is the only honest storage type.
+ *
+ * 4. Everything else (defaults, catch, readonly, optional, primitives,
+ *    nested objects) — read `_zod.output`. Defaults and catches fire
+ *    at parse time, so the post-init view is what storage holds.
+ *    Nested objects delegate to Zod's own recursion on `_zod.output`,
+ *    which peels nested defaults inside structural containers.
+ *
+ * Recursion: the alias calls itself on the non-transform side of a
+ * pipe so the inner shape gets the same per-key storage treatment as
+ * the top level. Without it, an inner `.default(...)` inside a
+ * transformed object would peel back to `T | undefined` (the broad
+ * input contract). Recursion only fires for pipe leaves — most leaves
+ * skip it.
+ *
+ * Implementation note: direct `_zod` property access mirrors Zod's
+ * own `$InferObjectOutput` / `$InferObjectInput`, which read
+ * `T[k]['_zod']['output']` / `T[k]['_zod']['input']` directly rather
+ * than wrapping in the top-level `output<T>` / `input<T>` conditional.
+ * Wrapping per key spawns a fresh conditional instantiation for every
+ * key; Volar's web-worker checker collapses that per-key walk to
+ * `any` once the schema is non-trivial. Property access has no
+ * conditional and resolves cleanly under the same budget.
+ *
+ * Shape access also goes through `_zod.def.shape` rather than
+ * `infer Shape from z.ZodObject<Shape>` — the latter collapses to the
+ * `$ZodShape` upper bound in the same worker because of
+ * `z.ZodObject`'s `out Shape` covariance markers.
+ */
+type StorageShape<S> = S extends {
+    _zod: {
+        def: {
+            type: 'object';
+            shape: infer Shape;
+        };
+    };
+} ? {
+    [K in keyof Shape]-?: StorageLeaf<Shape[K]>;
+} : StorageLeaf<S>;
+type StorageLeaf<L> = L extends {
+    _zod: {
+        def: {
+            type: 'pipe';
+            in: infer A;
+            out: infer B;
+        };
+    };
+} ? A extends {
+    _zod: {
+        def: {
+            type: 'transform';
+        };
+    };
+} ? StorageShape<B> : B extends {
+    _zod: {
+        def: {
+            type: 'transform';
+        };
+    };
+} ? StorageShape<A> : L extends {
+    _zod: {
+        output: infer Out;
+    };
+} ? Out : never : L extends {
+    _zod: {
+        def: {
+            type: 'transform';
+        };
+    };
+} ? L extends {
+    _zod: {
+        input: infer In;
+    };
+} ? In : never : L extends {
+    _zod: {
+        output: infer Out;
+    };
+} ? Out : never;
+
+/**
+ * Zod v4 adapter entry point. Re-exports the adapter + the useForm
+ * wrapper that threads zod-v4-specific schema types through
+ * useAbstractForm.
+ */
+
+/**
+ * Type of the value accepted at `Path` for `setValue` / `defaultValues`
+ * — the schema's `z.input<Schema>` shape at that path. Matches what
+ * `form.values.X` returns at runtime (the honest input view storage
+ * holds before transforms run).
+ *
+ * ```ts
+ * const schema = z.object({
+ *   flag: z.string().transform((v) => v.length > 10),
+ * })
+ * type FlagWriteIn = PathInput<typeof schema, 'flag'> // string
+ * ```
+ */
+type PathInput<Schema extends z.ZodType, Path extends string> = z.input<Schema> extends GenericForm ? Path extends FlatPath<z.input<Schema>> ? NestedType<z.input<Schema>, Path> : never : never;
+/**
+ * Type produced at `Path` after the full parse pipeline — the schema's
+ * `z.output<Schema>` shape at that path. Matches the `data` payload of
+ * `form.process()` and the value handed to `handleSubmit`'s callback.
+ *
+ * ```ts
+ * const schema = z.object({
+ *   flag: z.string().transform((v) => v.length > 10),
+ * })
+ * type FlagParsedOut = PathOutput<typeof schema, 'flag'> // boolean
+ * ```
+ */
+type PathOutput<Schema extends z.ZodType, Path extends string> = z.output<Schema> extends GenericForm ? Path extends FlatPath<z.output<Schema>> ? NestedType<z.output<Schema>, Path> : never : never;
+/**
+ * Create a form bound to a Zod v4 schema.
+ *
+ * ```ts
+ * import { useForm } from 'attaform/zod'
+ * import { z } from 'zod'
+ *
+ * const form = useForm({
+ *   schema: z.object({
+ *     email: z.email(),
+ *     password: z.string().min(8),
+ *   }),
+ *   defaultValues: { email: '' },
+ * })
+ * ```
+ *
+ * Returns a form API exposing `register`, `values`, `errors`,
+ * `fields`, `setValue`, `handleSubmit`, `meta`, field-array
+ * helpers, and more. See `UseFormReturnType` for the full
+ * surface.
+ *
+ * For Zod v3, import from `attaform/zod-v3` instead.
+ */
+declare function useForm<Schema extends z.ZodObject>(configuration: Omit<UseFormConfiguration<z.input<Schema> extends GenericForm ? z.input<Schema> : never, z.output<Schema> extends GenericForm ? z.output<Schema> : never, AbstractSchema<z.input<Schema> extends GenericForm ? z.input<Schema> : never, z.output<Schema> extends GenericForm ? z.output<Schema> : never>, DeepPartial<DefaultValuesShape<z.input<Schema> extends GenericForm ? z.input<Schema> : never>>>, 'schema' | 'validateOn' | 'debounceMs'> & {
+    schema: Schema;
+} & ValidateOnConfig): UseFormReturnType<z.input<Schema> extends GenericForm ? z.input<Schema> : never, z.output<Schema> extends GenericForm ? z.output<Schema> : never, StorageShape<Schema> extends GenericForm ? StorageShape<Schema> : never>;
+
+export { useForm as u };
+export type { PathInput as P, StorageShape as S, PathOutput as a };

package/dist/shared/{attaform.B0zue7zt.d.ts → attaform.CTwNcpLE.d.ts}

@@ -1,4 +1,4 @@
-import { G as GenericForm, F as FormKey, d as UseFormReturnType, R as RegisterValue } from './attaform.BYbsV2Wv.js';
+import { G as GenericForm, F as FormKey, d as UseFormReturnType, R as RegisterValue } from './attaform.C_5aB6EQ.js';
 import { Ref } from 'vue';
 
 /**

package/dist/shared/{attaform.BYbsV2Wv.d.mts → attaform.C_5aB6EQ.d.cts}

@@ -670,6 +670,34 @@ type AbstractSchema<Form, GetValueFormType> = {
      * callers treat that as "don't fill" and fall back to existing data.
      */
     getDefaultAtPath(path: Path): unknown;
+    /**
+     * Return the schema's "appropriate nullish value" at the given path
+     * — the underlying type's empty/falsy concrete, with `.default(x)`
+     * wrappers explicitly NOT honoured. Powers `form.clear(path)`:
+     * `clear` differs from `reset` precisely in that it ignores
+     * declared defaults and produces `false` / `0` / `''` / `[]` / a
+     * recursively-empty object instead.
+     *
+     * Semantics (mirrors `getDefaultAtPath`'s sub-path resolution,
+     * differs at leaves):
+     * - **Primitive leaf:** the primitive's falsy concrete
+     *   (`''` / `0` / `false` / `0n` / `new Date(0)`, etc.).
+     * - **Array / Set / Record:** empty.
+     * - **Optional<T>:** `undefined` (the wrapper's "absent" marker).
+     * - **Nullable<T>:** `null` (the wrapper's "explicit empty").
+     * - **Default<T> / Prefault<T> / Catch<T>:** inner-schema empty
+     *   — the declared default value is INTENTIONALLY skipped.
+     * - **Readonly<T> / preprocess(fn, T):** inner-schema empty.
+     * - **Object:** recursive — every property gets its own empty.
+     * - **Discriminated union:** first variant's recursive empty
+     *   (parallels `getDefaultAtPath`'s first-success precedent).
+     * - **Path doesn't exist in schema:** `undefined`.
+     *
+     * Adapters may return `undefined` when the path can't be resolved;
+     * callers treat that as "don't write" and leave existing storage
+     * unchanged.
+     */
+    getEmptyValueAtPath(path: Path): unknown;
     /**
      * Give the schema a chance to normalize the consumer's write value
      * before it lands in storage / hits the slim-primitive gate. Each
@@ -3016,23 +3044,30 @@ type FormMeta<F = unknown> = FieldState<F> & {
  * form.meta.submitting        // form-level reactive flag
  * ```
  *
- * Two generic slots split the input view from the output view:
+ * Three generic slots split the write view, parse view, and read view:
  *
- * - `Form` — the **input / storage shape** (`z.input<Schema>`). Used
- *   by `setValue`, `defaultValues`, `values`, `fields`, `register`,
- *   `toRef`, and every path-addressed API. Storage holds values as
- *   the consumer wrote them; preprocess normalization runs at the
- *   write boundary, but `.transform()`s are deferred to parse-time.
+ * - `Form` — the **input / write shape** (`z.input<Schema>`). Used
+ *   by `setValue`, `defaultValues`, and `register`'s write side.
+ *   Loose: preprocess paths accept `unknown` at the write boundary,
+ *   defaulted fields accept their inner type optionally.
  *
  * - `GetValueFormType` — the **output / parsed shape**
  *   (`z.output<Schema>`). Used by `handleSubmit`'s `onSubmit`
  *   callback and by `form.process()`'s success payload. This is the
  *   shape after refinements have fired and transforms have run.
  *
- * For schemas without transforms the two are identical, and the
- * default `GetValueFormType = Form` keeps the surface ergonomic.
+ * - `ReadForm` — the **read / storage shape**. Used by `values`,
+ *   `fields`, `register`'s read side, `toRef`. Per-key precise: at
+ *   the write-boundary wrappers (`default` / `prefault` / `catch` /
+ *   `readonly` / `preprocess`) the value is `z.output<Inner>`
+ *   (default has fired, preprocess has normalized); at transforms /
+ *   pipes the value stays `z.input<Inner>` (transforms are deferred
+ *   until parse). For schema-agnostic call sites defaults to `Form`.
+ *
+ * For schemas without write-boundary wrappers or transforms the three
+ * shapes coincide.
  */
-type UseFormReturnType<Form extends GenericForm, GetValueFormType extends GenericForm = Form> = {
+type UseFormReturnType<Form extends GenericForm, GetValueFormType extends GenericForm = Form, ReadForm extends GenericForm = Form> = {
     /**
      * Wraps your submit logic with validation and error routing.
      *
@@ -3079,7 +3114,7 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * value reads as `string`, not `boolean`. Use `handleSubmit` or
      * `form.process()` when you need the post-transform output shape.
      */
-    values: ValuesSurface<WriteShape<Form>>;
+    values: ValuesSurface<WriteShape<ReadForm>>;
     /**
      * Reactive per-field state proxy. Pinia-style nested object — read
      * leaf properties (`value`, `dirty`, `touched`, `errors`, `blurred`,
@@ -3108,7 +3143,7 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * Document edge case; rename the offending schema field if the
      * collision matters.
      */
-    fields: FieldStateMap<WriteShape<Form>>;
+    fields: FieldStateMap<WriteShape<ReadForm>>;
     /**
      * Write to the form programmatically. Two forms:
      *
@@ -3259,8 +3294,8 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * for storage activity to actually happen.
      */
     register: {
-        <Path extends RegisterFlatPath<Form, keyof Form>>(path: Path, options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<Form>, Path>>;
-        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [RegisterFlatPath<Form, keyof Form>] ? unknown : never), options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<Form>, JoinSegments<S>>>;
+        <Path extends RegisterFlatPath<Form, keyof Form>>(path: Path, options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<ReadForm>, Path>>;
+        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [RegisterFlatPath<Form, keyof Form>] ? unknown : never), options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<ReadForm>, JoinSegments<S>>>;
     };
     /**
      * The form's identifier — either the explicit `key` passed to
@@ -3315,8 +3350,8 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * scripts; `toRef` is for ref-shaped interop only.
      */
     toRef: {
-        <Path extends FlatPath<Form>>(path: Path): Readonly<Ref<NestedReadType<WriteShape<Form>, Path>>>;
-        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): Readonly<Ref<NestedReadType<WriteShape<Form>, JoinSegments<S>>>>;
+        <Path extends FlatPath<Form>>(path: Path): Readonly<Ref<NestedReadType<WriteShape<ReadForm>, Path>>>;
+        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): Readonly<Ref<NestedReadType<WriteShape<ReadForm>, JoinSegments<S>>>>;
     };
     /**
      * Replace every field error for this form with the provided list.
@@ -3430,6 +3465,51 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * from the persisted draft too.
      */
     resetField: (path: FlatPath<Form>) => void;
+    /**
+     * Wipe a field (or the whole form) to the "appropriate nullish
+     * value" for its declared type — the underlying type's empty/falsy
+     * concrete, with any `.default(x)` wrapper INTENTIONALLY skipped.
+     * Orthogonal to `reset` / `resetField` by design.
+     *
+     * ```ts
+     * const schema = z.object({
+     *   notify: z.boolean().default(true),
+     *   count: z.number().default(5),
+     * })
+     * const form = useForm({ schema })
+     *
+     * form.reset()         // notify → true,  count → 5  (defaults)
+     * form.clear()         // notify → false, count → 0  (falsy-for-type)
+     * form.clear('notify') // → false (NOT the declared default true)
+     * ```
+     *
+     * Per-wrapper semantics:
+     *
+     * - `.default(x)` / `.prefault(x)` / `.catch(x)` → inner-schema
+     *   empty (default is INTENTIONALLY skipped).
+     * - `.optional()` → `undefined` (the wrapper's "absent" marker).
+     * - `.nullable()` → `null` (the wrapper's "explicit empty").
+     * - Object → recursive (every property gets its own empty).
+     * - Array / Set / Record → empty.
+     *
+     * Returns `true` when the write was accepted, `false` when the
+     * adapter couldn't resolve an empty value at the path (e.g. the
+     * path doesn't exist in the schema). The form state is unchanged
+     * on a `false` return.
+     *
+     * Sugar over `setValue(path, schema.getEmptyValueAtPath(path))` —
+     * no separate bookkeeping. Variant memory, history, persistence,
+     * and listeners all see this as a regular write at the path.
+     *
+     * `clear()` (no arg) targets the whole form. `clear('')` targets
+     * the empty-string path slot SPECIFICALLY — the two are NOT
+     * interchangeable, matching `touch()` / `touch('')` from #184.
+     */
+    clear: {
+        (): boolean;
+        <Path extends FlatPath<Form> | ''>(path: Path): boolean;
+        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form> | ''] ? unknown : never)): boolean;
+    };
     /**
      * Write the current value at `path` to storage immediately. Useful
      * for explicit "Save draft" buttons, `beforeunload` handlers, or