@beignet/react-hook-form 0.0.57 → 0.0.59

package/dist/input-snapshot.js

@@ -0,0 +1,46 @@
+/**
+ * Snapshot data containers without manufacturing invalid copies of opaque
+ * instances (which may depend on private fields or native internal slots).
+ * Opaque instances and functions remain references and must be treated as immutable.
+ */
+export function snapshotInput(input) {
+    const seen = new WeakMap();
+    function copy(value) {
+        if (value === null || typeof value !== "object")
+            return value;
+        const previous = seen.get(value);
+        if (previous)
+            return previous;
+        const prototype = Object.getPrototypeOf(value);
+        let snapshot;
+        if (prototype === Date.prototype) {
+            snapshot = new Date(Date.prototype.getTime.call(value));
+        }
+        else if (Array.isArray(value) && prototype === Array.prototype) {
+            snapshot = new Array(value.length);
+        }
+        else if (prototype === Object.prototype || prototype === null) {
+            snapshot = Object.create(prototype);
+        }
+        else {
+            return value;
+        }
+        seen.set(value, snapshot);
+        for (const key of Reflect.ownKeys(value)) {
+            if (Array.isArray(value) && key === "length")
+                continue;
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor)
+                continue;
+            Object.defineProperty(snapshot, key, {
+                value: copy(Reflect.get(value, key)),
+                enumerable: descriptor.enumerable,
+                configurable: true,
+                writable: true,
+            });
+        }
+        return snapshot;
+    }
+    return copy(input);
+}
+//# sourceMappingURL=input-snapshot.js.map

package/dist/input-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-snapshot.js","sourceRoot":"","sources":["../src/input-snapshot.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAI,KAAQ;IACvC,MAAM,IAAI,GAAG,IAAI,OAAO,EAAkB,CAAC;IAE3C,SAAS,IAAI,CAAC,KAAc;QAC1B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC9D,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAE9B,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,QAAgB,CAAC;QACrB,IAAI,SAAS,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;YACjC,QAAQ,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1D,CAAC;aAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,SAAS,KAAK,KAAK,CAAC,SAAS,EAAE,CAAC;YACjE,QAAQ,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACrC,CAAC;aAAM,IAAI,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YAChE,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAE1B,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,QAAQ;gBAAE,SAAS;YACvD,MAAM,UAAU,GAAG,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAC/D,IAAI,CAAC,UAAU;gBAAE,SAAS;YAC1B,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE;gBACnC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;gBACpC,UAAU,EAAE,UAAU,CAAC,UAAU;gBACjC,YAAY,EAAE,IAAI;gBAClB,QAAQ,EAAE,IAAI;aACf,CAAC,CAAC;QACL,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO,IAAI,CAAC,KAAK,CAAM,CAAC;AAC1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/react-hook-form",
-  "version": "0.0.57",
+  "version": "0.0.59",
   "type": "module",
   "description": "React Hook Form integration for Beignet with Standard Schema support",
   "main": "./dist/index.js",
@@ -28,7 +28,7 @@
     "clean": "rm -rf dist coverage .turbo",
     "test": "bun test && bun run typecheck:types",
     "test:coverage": "bun test --coverage",
-    "typecheck:types": "tsc -p tsconfig.type-tests.json",
+    "typecheck:types": "bun run build && tsc -p tsconfig.type-tests.json && tsc -p tsconfig.consumer-tests.json",
     "lint": "biome check ."
   },
   "keywords": [
@@ -69,10 +69,10 @@
     "@types/bun": "^1.4.0",
     "@types/node": "^22.0.0",
     "@types/react": "^18.2.0",
-    "happy-dom": "^20.8.9",
+    "happy-dom": "^21.0.4",
     "react": "^18.2.0",
     "react-hook-form": "^7.48.0",
     "typescript": "^5.3.0",
-    "zod": "^4.0.0"
+    "zod": "^4.6.6"
   }
 }

package/skills/forms/SKILL.md

@@ -26,14 +26,15 @@ routes, providers, infra adapters, `server/`, or `app-context.ts`.
 
 ## Contract Requirements
 
-React Hook Form binds to the contract body schema. TypeScript rejects contracts
+React Hook Form binds to the contract body schema by default. Pass
+`rhf(contract, { schema })` for a separate form schema whose parsed output is
+assignable to the contract body input. TypeScript rejects contracts
 without `.body(...)` because there are no form fields or body validation to
 infer; untyped JavaScript calls receive the same failure at runtime.
 
-The body schema input must be an object with named fields. TypeScript rejects
-scalar and array body inputs. Put scalar values or lists under a field, for
-example `.body(z.object({ tags: z.array(z.string()) }))`, when the endpoint is
-backed by a form.
+The selected form schema input must be an object with named fields. Scalar or
+array request bodies need an explicit object-input form schema that transforms
+named fields into the required body shape.
 
 Keep shared form DTOs in `features/<feature>/schemas.ts`, then reuse them from
 contracts, use cases, tests, and components.
@@ -86,17 +87,36 @@ export function CreateTodoForm() {
 ```
 
 Use `formOptions(...)` when a component or wrapper wants options without
-calling the hook directly.
+calling the hook directly. Returned options fit native `UseFormProps`, `useForm`,
+and `createFormControl` with `exactOptionalPropertyTypes` enabled.
 
 ## Input And Output Types
 
-React Hook Form field state uses the schema input type. `handleSubmit` receives
-the schema output type after validation, coercion, defaults, and transforms.
-
-For plain, defaulted, or coerced schemas, submitting `values` as the contract
-body usually works. If a schema transform changes a field's type so the parsed
-output no longer matches the contract body input, send raw field values from
-`form.getValues()` after validation instead of `values`.
+React Hook Form field state uses schema input; default `handleSubmit` values use
+parsed output, including transforms, defaults, and removal of unknown keys.
+Use `submitValues: "raw"` only when original validated input is needed. Use
+`defaultValues` for visible defaults; parsing does not replace live field state.
+
+Prefer numeric HTTP contracts (`z.number()`) and numeric field bindings
+(`valueAsNumber`) when the API accepts numbers. Use a separate form schema when
+UI values need conversion: `rhf(contract, { schema: formSchema })`. The form
+schema owns validation; derive it from shared request validators to preserve
+constraints. Its output must fit the contract's input. Keep schemas in feature
+`schemas.ts` and reusable bindings in feature `client/forms.ts`.
+
+Shared coercing schemas are appropriate when the API intentionally accepts
+those inputs. Reuse transforms only when parsed output is accepted as input and
+parsing again preserves its meaning. One-way conversions belong in a separate
+form schema, or use raw mode to submit the original contract input. Raw mode
+with a separate form schema may still need mapping into contract input.
+
+Generated resolvers snapshot plain objects, arrays, and dates. Opaque instances
+retain identity and must stay immutable during validation and submission.
+Disabled resolvers submit input; dynamic enable flags return an input/output
+union. Explicit parsed mode requires validation. Custom resolvers own output
+and cannot combine with `submitValues`. Prefer adapter `useForm` for inference;
+direct `useForm(formOptions(...))` may need explicit input, context, and output
+generics with partial defaults.
 
 ## Error Mapping
 
@@ -122,11 +142,9 @@ codes declared on the contract with `.errors(...)`.
   params, headers, tenant IDs, and auth-derived values belong in mutation
   variables or app context, not form fields.
 - Contracts without `.body(...)` are not form contracts.
-- Scalar and array request bodies are not form contracts; wrap their values in
-  an object with named fields.
-- `handleSubmit` returns parsed schema output. For transforms that change field
-  types, submit `form.getValues()` after validation when the contract client
-  expects body input.
+- Scalar and array request bodies need a separate object-input form schema.
+- `handleSubmit` returns parsed output by default. Submit callback values
+  directly rather than rereading `form.getValues()` after asynchronous validation.
 - Keep the root form helper in `client/forms.ts` unless the app already uses a
   different local convention.
 - Do not import use cases or server modules to reuse validation. Move shared
@@ -138,6 +156,15 @@ Leave the generated Standard Schema resolver enabled by default. Use
 `resolverEnabled: false` only for deliberate partial or multi-step flows, and
 keep final validation in use cases.
 
+Forwarded `UseFormProps` and optional resolver settings are supported. A missing
+custom resolver uses generated validation unless disabled; submit types include
+the custom output and any possible parsed or unparsed fallback.
+Wrappers may forward an `undefined` options object; this uses generated validation
+and parsed output, which is included in the inferred submit union.
+Returned props remain optional when the whole options object may be absent.
+Conditional configurations can select a custom resolver or a generated submit
+mode, with output inferred per branch. Do not set both in the same configuration.
+
 After form changes, run from the app root:
 
 ```bash

package/src/index.ts

@@ -16,10 +16,12 @@ import {
 import { standardSchemaResolver } from "@hookform/resolvers/standard-schema";
 import {
   type FieldValues,
+  type Resolver,
   useForm as rhfUseForm,
   type UseFormProps,
   type UseFormReturn,
 } from "react-hook-form";
+import { snapshotInput } from "./input-snapshot.js";
 
 /**
  * Keep only object-shaped React Hook Form field values. Arrays are objects in
@@ -32,95 +34,269 @@ type ObjectFieldValues<T> = [T] extends [FieldValues]
     : never
   : never;
 
-/**
- * Live form field values inferred from the contract body schema input.
- *
- * React Hook Form field values (`register`, `watch`, `setValue`,
- * `defaultValues`) hold pre-validation input, so coercing or transforming body
- * schemas type fields as what the user edits, not what the schema produces.
- */
-type FormInput<TContract extends HttpContractConfig> =
-  TContract["body"] extends StandardSchemaV1
-    ? ObjectFieldValues<InferInput<TContract["body"]>>
-    : never;
+/** Live fields and defaults use the selected schema's input. */
+type FormInput<S extends StandardSchemaV1> = ObjectFieldValues<InferInput<S>>;
 
-/**
- * Validated submit values inferred from the contract body schema output.
- *
- * `handleSubmit` callbacks receive the resolver-parsed output.
- */
-type FormOutput<TContract extends HttpContractConfig> =
-  TContract["body"] extends StandardSchemaV1
-    ? InferOutput<TContract["body"]>
-    : never;
+/** Parsed submissions use the selected schema's output. */
+type FormOutput<S extends StandardSchemaV1> = InferOutput<S>;
 
-/**
- * Contract input accepted by the React Hook Form adapter.
- */
-type ReactHookFormContract<TContractLike extends ContractLike> = [
-  FormInput<ResolveContract<TContractLike>>,
+type BodySchema<C extends HttpContractConfig> = Extract<
+  C["body"],
+  StandardSchemaV1
+>;
+
+type ReactHookFormContract<T extends ContractLike> = [
+  FormInput<BodySchema<ResolveContract<T>>>,
 ] extends [never]
   ? never
-  : TContractLike;
+  : T;
 
-/**
- * React Hook Form options accepted by the Beignet adapter.
- */
-type RhfFormOptions<TContract extends HttpContractConfig> = Omit<
-  UseFormProps<FormInput<TContract>, unknown, FormOutput<TContract>>,
+/** A form-specific schema produces the request input accepted by the contract. */
+type CompatibleFormSchema<
+  C extends HttpContractConfig,
+  S extends StandardSchemaV1,
+> = [BodySchema<C>] extends [never]
+  ? never
+  : [FormInput<S>] extends [never]
+    ? never
+    : [FormOutput<S>] extends [InferInput<BodySchema<C>>]
+      ? S
+      : never;
+
+type RhfFormOptions<S extends StandardSchemaV1, Output> = Omit<
+  UseFormProps<FormInput<S>, unknown, Output>,
   "resolver"
+>;
+
+type ParsedFormOptions<S extends StandardSchemaV1> = RhfFormOptions<
+  S,
+  FormOutput<S>
 > & {
-  /**
-   * Optional override for the resolver. If supplied, this is used instead of
-   * the default contract-based resolver.
-   */
-  resolver?: UseFormProps<
-    FormInput<TContract>,
-    unknown,
-    FormOutput<TContract>
-  >["resolver"];
-
-  /**
-   * Enables or disables automatic resolver generation from the contract body schema.
-   * Defaults to true.
-   */
+  /** Submit parsed schema output. Default: parsed. Requires the generated resolver. */
+  submitValues?: "parsed";
+  resolver?: undefined;
+  /** Generate the schema resolver. Default: true. */
+  resolverEnabled?: true;
+};
+
+type RawFormOptions<S extends StandardSchemaV1> = RhfFormOptions<
+  S,
+  FormInput<S>
+> & {
+  /** Validate with the selected schema and submit original input. */
+  submitValues: "raw";
+  resolver?: undefined;
   resolverEnabled?: boolean;
 };
 
-/**
- * React Hook Form adapter methods for one compatible contract.
- */
-type ReactHookFormContractAdapterShape<TContract extends HttpContractConfig> = {
-  /**
-   * Generate `UseFormProps` for any React Hook Form usage.
-   */
-  formOptions: (
-    props?: RhfFormOptions<TContract>,
-  ) => UseFormProps<FormInput<TContract>, unknown, FormOutput<TContract>>;
-
-  /**
-   * Convenience wrapper around `useForm(formOptions(props))`.
-   */
-  useForm: (
-    props?: RhfFormOptions<TContract>,
-  ) => UseFormReturn<FormInput<TContract>, unknown, FormOutput<TContract>>;
+type DisabledFormOptions<S extends StandardSchemaV1> = RhfFormOptions<
+  S,
+  FormInput<S>
+> & {
+  resolverEnabled: false;
+  resolver?: undefined;
+  submitValues?: "raw";
+};
+
+type VariableFormOptions<S extends StandardSchemaV1> = RhfFormOptions<
+  S,
+  FormInput<S> | FormOutput<S>
+> & { resolver?: undefined } & (
+    | { submitValues?: "raw" | "parsed" | undefined; resolverEnabled?: true }
+    | { submitValues?: "raw"; resolverEnabled?: boolean | undefined }
+  );
+
+type CustomFormOptions<S extends StandardSchemaV1, Output> = RhfFormOptions<
+  S,
+  Output
+> & {
+  /** A custom resolver owns its submit output, independently of the schema. */
+  resolver: Resolver<FormInput<S>, unknown, Output>;
+  resolverEnabled?: boolean;
+  submitValues?: never;
+};
+
+type OptionalResolverFormOptions<
+  S extends StandardSchemaV1,
+  Output,
+> = RhfFormOptions<S, Output> & {
+  resolver?: Resolver<FormInput<S>, unknown, Output> | undefined;
+  resolverEnabled?: boolean | undefined;
+  submitValues?: never;
+};
+
+type SuppliedResolverFormOptions<
+  S extends StandardSchemaV1,
+  Output,
+> = OptionalResolverFormOptions<S, Output> & {
+  resolver: Resolver<FormInput<S>, unknown, Output> | undefined;
+};
+
+/** An absent override falls back to schema parsing unless generation is disabled. */
+type ResolverFallbackOutput<S extends StandardSchemaV1, Props> = Props extends {
+  resolverEnabled: false;
+}
+  ? FormInput<S>
+  : Props extends { resolverEnabled?: infer Enabled }
+    ? false extends Enabled
+      ? FormInput<S> | FormOutput<S>
+      : FormOutput<S>
+    : FormOutput<S>;
+
+type ResolverSubmitOutput<
+  S extends StandardSchemaV1,
+  Output,
+  Props,
+> = Props extends { resolver: undefined }
+  ? ResolverFallbackOutput<S, Props>
+  : Props extends { resolver: Resolver<FormInput<S>, unknown, Output> }
+    ? Output
+    : Output | ResolverFallbackOutput<S, Props>;
+
+type ConditionalFormOptions<S extends StandardSchemaV1> =
+  | ParsedFormOptions<S>
+  | RawFormOptions<S>
+  | DisabledFormOptions<S>
+  | VariableFormOptions<S>
+  | OptionalResolverFormOptions<S, unknown>;
+
+type GeneratedSubmitOutput<S extends StandardSchemaV1, Props> = Props extends
+  | { submitValues: "raw" }
+  | { resolverEnabled: false }
+  ? FormInput<S>
+  : Props extends { submitValues?: infer Mode }
+    ? "raw" extends Mode
+      ? FormInput<S> | ResolverFallbackOutput<S, Props>
+      : ResolverFallbackOutput<S, Props>
+    : ResolverFallbackOutput<S, Props>;
+
+type CustomSubmitOutput<S extends StandardSchemaV1, R> =
+  R extends Resolver<FormInput<S>, unknown, infer Output> ? Output : never;
+
+/** Distribute over configurations so each branch contributes only its own output. */
+type ConditionalSubmitOutput<
+  S extends StandardSchemaV1,
+  Props,
+> = Props extends undefined
+  ? FormOutput<S>
+  : Props extends { resolver: infer R }
+    ? undefined extends R
+      ? CustomSubmitOutput<S, R> | GeneratedSubmitOutput<S, Props>
+      : CustomSubmitOutput<S, R>
+    : Props extends { resolver?: infer R }
+      ? CustomSubmitOutput<S, R> | GeneratedSubmitOutput<S, Props>
+      : GeneratedSubmitOutput<S, Props>;
+
+type SuppliedFormProps<Props> = undefined extends Props
+  ? Partial<Exclude<Props, undefined>>
+  : Props;
+
+// Keep only supplied props so unused React Hook Form controls do not leak across peers.
+type FormOptions<Input extends FieldValues, Output, Props> = Omit<
+  Props,
+  "resolver" | "resolverEnabled" | "submitValues"
+> &
+  Pick<UseFormProps<Input, unknown, Output>, "resolver">;
+
+/** React Hook Form methods for the selected form schema. */
+type ReactHookFormContractAdapterShape<S extends StandardSchemaV1> = {
+  /** Generate options for React Hook Form or a wrapper. */
+  formOptions: {
+    (
+      props?: undefined,
+    ): FormOptions<FormInput<S>, FormOutput<S>, Record<never, never>>;
+    <Output, Props extends SuppliedResolverFormOptions<S, Output>>(
+      props: SuppliedResolverFormOptions<S, Output> & Props,
+    ): FormOptions<FormInput<S>, ResolverSubmitOutput<S, Output, Props>, Props>;
+    <Props extends RawFormOptions<S> | DisabledFormOptions<S>>(
+      props: Props,
+    ): FormOptions<FormInput<S>, FormInput<S>, Props>;
+    <Props extends ParsedFormOptions<S>>(
+      props: Props,
+    ): FormOptions<FormInput<S>, FormOutput<S>, Props>;
+    <Props extends VariableFormOptions<S>>(
+      props: Props,
+    ): FormOptions<FormInput<S>, FormInput<S> | FormOutput<S>, Props>;
+    <Output, Props extends OptionalResolverFormOptions<S, Output>>(
+      props: OptionalResolverFormOptions<S, Output> & Props,
+    ): FormOptions<
+      FormInput<S>,
+      Output | ResolverFallbackOutput<S, Props>,
+      Props
+    >;
+    <Props extends ParsedFormOptions<S>>(
+      props?: Props,
+    ): FormOptions<FormInput<S>, FormOutput<S>, Partial<Props>>;
+    <Props extends VariableFormOptions<S>>(
+      props: Props | undefined,
+    ): FormOptions<FormInput<S>, FormInput<S> | FormOutput<S>, Partial<Props>>;
+    <Output, Props extends OptionalResolverFormOptions<S, Output>>(
+      props: (OptionalResolverFormOptions<S, Output> & Props) | undefined,
+    ): FormOptions<
+      FormInput<S>,
+      ResolverSubmitOutput<S, Output, Props> | FormOutput<S>,
+      Partial<Props>
+    >;
+    <Props extends ConditionalFormOptions<S> | undefined>(
+      props: Props,
+    ): FormOptions<
+      FormInput<S>,
+      ConditionalSubmitOutput<S, Props>,
+      SuppliedFormProps<Props>
+    >;
+  };
+
+  /** Convenience wrapper around useForm(formOptions(props)). */
+  useForm: {
+    <Output>(
+      props: CustomFormOptions<S, Output>,
+    ): UseFormReturn<FormInput<S>, unknown, Output>;
+    (
+      props: RawFormOptions<S> | DisabledFormOptions<S>,
+    ): UseFormReturn<FormInput<S>, unknown, FormInput<S>>;
+    (
+      props?: ParsedFormOptions<S>,
+    ): UseFormReturn<FormInput<S>, unknown, FormOutput<S>>;
+    (
+      props?: VariableFormOptions<S>,
+    ): UseFormReturn<FormInput<S>, unknown, FormInput<S> | FormOutput<S>>;
+    <Output, Props extends OptionalResolverFormOptions<S, Output>>(
+      props: OptionalResolverFormOptions<S, Output> & Props,
+    ): UseFormReturn<
+      FormInput<S>,
+      unknown,
+      Output | ResolverFallbackOutput<S, Props>
+    >;
+    <Output, Props extends OptionalResolverFormOptions<S, Output>>(
+      props: (OptionalResolverFormOptions<S, Output> & Props) | undefined,
+    ): UseFormReturn<
+      FormInput<S>,
+      unknown,
+      ResolverSubmitOutput<S, Output, Props> | FormOutput<S>
+    >;
+    <Props extends ConditionalFormOptions<S> | undefined>(
+      props: Props,
+    ): UseFormReturn<FormInput<S>, unknown, ConditionalSubmitOutput<S, Props>>;
+  };
 };
 
 /**
- * React Hook Form adapter for one contract whose body schema input is
- * object-shaped.
+ * Adapter for a contract body, optionally using a separate form schema.
+ * The selected schema must have object-shaped input for named form fields.
  */
-export type ReactHookFormContractAdapter<TContract extends HttpContractConfig> =
-  [FormInput<TContract>] extends [never]
+export type ReactHookFormContractAdapter<
+  TContract extends HttpContractConfig,
+  TSchema extends StandardSchemaV1 = BodySchema<TContract>,
+> = [BodySchema<TContract>] extends [never]
+  ? never
+  : [FormInput<TSchema>] extends [never]
     ? never
-    : ReactHookFormContractAdapterShape<TContract>;
-
-function createReactHookFormAdapter<TContractLike extends ContractLike>(
-  contract: ReactHookFormContract<TContractLike>,
-): ReactHookFormContractAdapter<ResolveContract<TContractLike>>;
-function createReactHookFormAdapter<TContractLike extends ContractLike>(
-  contract: ReactHookFormContract<TContractLike>,
-): ReactHookFormContractAdapterShape<ResolveContract<TContractLike>> {
+    : ReactHookFormContractAdapterShape<TSchema>;
+
+function createReactHookFormAdapter(
+  contract: ContractLike,
+  schema?: StandardSchemaV1,
+): ReactHookFormContractAdapterShape<StandardSchemaV1<FieldValues, unknown>> {
   const resolvedContract = resolveContract(contract);
 
   if (!resolvedContract.body) {
@@ -131,57 +307,101 @@ function createReactHookFormAdapter<TContractLike extends ContractLike>(
     );
   }
 
-  type Input = FormInput<ResolveContract<TContractLike>>;
-  type Output = FormOutput<ResolveContract<TContractLike>>;
-
-  function formOptions(
-    props?: RhfFormOptions<ResolveContract<TContractLike>>,
-  ): UseFormProps<Input, unknown, Output> {
-    const bodySchema = resolvedContract.body as StandardSchemaV1<Input, Output>;
+  type Input = FieldValues;
+  type Schema = StandardSchemaV1<Input, unknown>;
+  type Options = RhfFormOptions<Schema, unknown> & {
+    resolver?: Resolver<Input, unknown, unknown>;
+    resolverEnabled?: boolean;
+    submitValues?: "raw" | "parsed";
+  };
+  const formSchema = (schema ?? resolvedContract.body) as Schema;
 
+  function formOptions(props?: Options): UseFormProps<Input, unknown, unknown> {
     const {
       resolverEnabled = true,
       resolver: resolverOverride,
+      submitValues = "parsed",
       ...rest
     } = props ?? {};
 
-    const resolver =
-      resolverOverride ??
-      (resolverEnabled
-        ? standardSchemaResolver<Input, unknown, Output>(bodySchema)
-        : undefined);
+    if (resolverOverride && props?.submitValues !== undefined) {
+      throw new Error(
+        `rhf(${resolvedContract.name}): A custom resolver owns its submit values; omit submitValues.`,
+      );
+    }
+    if (
+      props?.submitValues === "parsed" &&
+      !resolverEnabled &&
+      !resolverOverride
+    ) {
+      throw new Error(
+        `rhf(${resolvedContract.name}): Parsed submit values require the generated resolver.`,
+      );
+    }
+
+    let resolver: Resolver<Input, unknown, unknown> | undefined =
+      resolverOverride;
+    if (!resolver && resolverEnabled) {
+      const generated =
+        submitValues === "parsed"
+          ? standardSchemaResolver<Input, unknown, unknown>(formSchema)
+          : standardSchemaResolver<Input, unknown, unknown>(
+              formSchema,
+              undefined,
+              { raw: true },
+            );
+      resolver = async (values, context, options) => {
+        // Capture data containers before asynchronous validation.
+        const snapshot = snapshotInput(values);
+        const result = await generated(
+          submitValues === "raw" ? snapshotInput(snapshot) : snapshot,
+          context,
+          options,
+        );
+        return submitValues === "raw" && Object.keys(result.errors).length === 0
+          ? { errors: {}, values: snapshot }
+          : result;
+      };
+    }
 
     return {
-      ...(rest as UseFormProps<Input, unknown, Output>),
+      ...rest,
+      // RHF merges options on rerender; an explicit undefined clears an old resolver.
       resolver,
     };
   }
 
-  function useForm(
-    props?: RhfFormOptions<ResolveContract<TContractLike>>,
-  ): UseFormReturn<Input, unknown, Output> {
+  function useForm(props?: Options): UseFormReturn<Input, unknown, unknown> {
     const options = formOptions(props);
-    return rhfUseForm<Input, unknown, Output>(options);
+    return rhfUseForm<Input, unknown, unknown>(options);
   }
 
-  return { formOptions, useForm };
+  return { formOptions, useForm } as ReactHookFormContractAdapterShape<Schema>;
 }
 
 /**
- * Create a React Hook Form adapter factory.
- *
- * Mirrors the React integration pattern used by `createReactQuery()` and `createNuqs()`:
- * create the adapter once, then bind individual contracts with `rhf(contract)`.
- * Contracts must declare a body schema whose input is object-shaped. After
- * binding, callers may override or disable the generated resolver through
- * `formOptions(...)` or `useForm(...)`.
+ * Create a React Hook Form adapter factory. Bind a contract with rhf(contract),
+ * or pass { schema } when the form's input differs from the request body.
+ * A separate schema must have object-shaped input and output assignable to the
+ * contract body input. Parsed submissions are the default; raw mode is opt-in.
  */
 export function createReactHookForm() {
-  return function rhf<TContractLike extends ContractLike>(
+  function rhf<TContractLike extends ContractLike>(
     contract: ReactHookFormContract<TContractLike>,
-  ): ReactHookFormContractAdapter<ResolveContract<TContractLike>> {
-    return createReactHookFormAdapter(contract);
-  };
+  ): ReactHookFormContractAdapter<ResolveContract<TContractLike>>;
+  function rhf<
+    TContractLike extends ContractLike,
+    TSchema extends StandardSchemaV1,
+  >(
+    contract: TContractLike,
+    options: {
+      schema: CompatibleFormSchema<ResolveContract<TContractLike>, TSchema>;
+    },
+  ): ReactHookFormContractAdapter<ResolveContract<TContractLike>, TSchema>;
+  function rhf(contract: ContractLike, options?: { schema: StandardSchemaV1 }) {
+    return createReactHookFormAdapter(contract, options?.schema);
+  }
+  return rhf;
 }
 
 /**