attaform 0.26.0 → 0.27.1

package/dist/index.d.cts

@@ -1,337 +1,249 @@
-import { Plugin, App } from 'vue';
-import { S as SSRDetectOptions, a as SerializedFormData, A as AttaformRegistry } from './shared/attaform.MgaYKlPP.cjs';
-export { b as AnyForm, c as AttaformErrorCode, C as CompiledStep, F as FormStatus, I as InjectWizardInput, L as LazyMarker, d as StepSlot, U as UseRegisterReturn, e as UseWizardReturnType, W as WizardAggregateError, f as WizardCtx, g as WizardCtxForm, h as WizardOnError, i as WizardOnSubmit, j as WizardOptions, k as WizardPersistFn, l as WizardRestoreFn, m as WizardRestoreState, n as WizardStatusesProxy, o as WizardSubmitContext, p as createRegistry, q as defaultCoercionRules, r as defineCoercion, s as getRegistryFromApp, t as injectForm, u as injectWizard, v as kAttaformRegistry, w as lazy, x as useRegister, y as useRegistry, z as useWizard } from './shared/attaform.MgaYKlPP.cjs';
-import { A as AttaformDefaults, F as FormKey, G as GenericForm, U as UseFormConfiguration, a as AbstractSchema, D as DefaultValuesInput, b as UseFormReturnType, R as RegisterModelDynamicCustomDirective, c as RegisterValue, d as GetDisplayState } from './shared/attaform.DBNjHgNj.cjs';
-export { e as ArrayItem, f as ArrayPath, C as CoercionEntry, g as CoercionRegistry, h as CoercionResult, i as CustomDirectiveRegisterAssignerFn, j as DeepPartial, k as DefaultValuesResponse, l as DefaultValuesShape, m as DisplayCtx, n as DisplayMachine, o as DisplayState, E as ErrorInput, p as ErrorsProxyShape, q as FieldMetaPayload, r as FieldState, s as FieldStateMap, t as FieldStateMapEntry, u as FlatPath, v as FormErrorRecord, w as FormErrorsSurface, x as FormMeta, H as HandleSubmit, y as HistoryConfig, I as IsTuple, z as IsUnion, J as JoinSegments, B as Json, K as KeyofUnion, L as LiftedValueShape, M as MetaTrackerValue, N as NestedReadType, O as NestedType, P as OnError, Q as OnInvalidSubmitPolicy, S as OnSubmit, T as PartialFlatPath, V as Path, W as PathKey, X as PendingValidationStatus, Y as Primitive, Z as ROOT_PATH, _ as ROOT_PATH_KEY, $ as ReactiveValidationStatus, a0 as RegisterDirective, a1 as RegisterFlatPath, a2 as RegisterOptions, a3 as RegisterSelectModifier, a4 as RegisterTextModifier, a5 as RegisterTransform, a6 as Segment, a7 as SetValueCallback, a8 as SetValuePayload, a9 as SettledValidationStatus, aa as SlimPrimitiveKind, ab as SlimRuntimeOf, ac as SubmitHandler, ad as Unset, ae as ValidateOn, af as ValidateOnConfig, ag as ValidationError, ah as ValidationResponse, ai as ValidationResponseWithoutValue, aj as ValueOfUnion, ak as WriteMeta, al as WriteShape, am as canonicalizePath, an as isPathPrefix, ao as isUnset, ap as parseDottedPath, aq as unset } from './shared/attaform.DBNjHgNj.cjs';
-export { A as AttaformError, I as InvalidPathError, a as InvalidUseFormConfigError, O as OutsideSetupError, R as RegistryNotInstalledError, b as ReservedFormKeyError, S as SubmitErrorHandlerError } from './shared/attaform.DJRz_bzM.cjs';
+export { a as AnyForm, b as AttaformDevtoolsBridge, c as AttaformError, d as AttaformErrorCode, e as AttaformPluginOptions, A as AttaformRegistry, C as CompiledStep, D as DEFAULT_TIMINGS, f as DEVTOOLS_WINDOW_KEY, g as DisplayTimings, F as FormStatus, I as InjectWizardInput, h as InvalidPathError, i as InvalidUseFormConfigError, L as LazyMarker, O as OutsideSetupError, R as RegistryNotInstalledError, j as ReservedFormKeyError, S as SerializedAttaformState, k as SerializedFormData, l as StepSlot, m as SubmitErrorHandlerError, U as UseRegisterReturn, n as UseWizardReturnType, W as WizardAggregateError, o as WizardCtx, p as WizardCtxForm, q as WizardOnError, r as WizardOnSubmit, s as WizardOptions, t as WizardPersistFn, u as WizardRestoreFn, v as WizardRestoreState, w as WizardStatusesProxy, x as WizardSubmitContext, y as assignKey, z as createAttaform, B as createRegistry, E as defaultCoercionRules, G as defaultDisplayState, H as defineCoercion, J as escapeForInlineScript, K as getRegistryFromApp, M as hydrateAttaformState, N as injectForm, P as injectWizard, Q as isRegisterValue, T as kAttaformRegistry, V as lazy, X as makeDefaultDisplayState, Y as renderAttaformState, Z as useRegister, _ as useRegistry, $ as useWizard, a0 as vRegister } from './shared/attaform.D99pd7JG.cjs';
+import { G as GenericForm, F as FormKey, U as UseFormConfiguration, A as AbstractSchema, aq as AcceptableDefaults, ae as ValidateOnConfig, a as UseFormReturnType, D as DefaultValuesInput, o as FieldMetaPayload } from './shared/attaform.C3WnCDXz.cjs';
+export { b as ArrayItem, c as ArrayPath, d as AttaformDefaults, C as CoercionEntry, e as CoercionRegistry, f as CoercionResult, g as CustomDirectiveRegisterAssignerFn, h as DeepPartial, i as DefaultValuesResponse, j as DefaultValuesShape, k as DisplayCtx, l as DisplayMachine, m as DisplayState, E as ErrorInput, n as ErrorsProxyShape, p as FieldState, q as FieldStateMap, r as FieldStateMapEntry, s as FlatPath, t as FormErrorRecord, u as FormErrorsSurface, v as FormMeta, w as GetDisplayState, H as HandleSubmit, x as HistoryConfig, I as IsTuple, y as IsUnion, J as JoinSegments, z as Json, K as KeyofUnion, L as LiftedValueShape, M as MetaTrackerValue, N as NestedReadType, B as NestedType, O as OnError, P as OnInvalidSubmitPolicy, Q as OnSubmit, R as PartialFlatPath, S as Path, T as PathKey, V as PendingValidationStatus, W as Primitive, X as ROOT_PATH, Y as ROOT_PATH_KEY, Z as ReactiveValidationStatus, _ as RegisterDirective, $ as RegisterFlatPath, a0 as RegisterOptions, a1 as RegisterSelectModifier, a2 as RegisterTextModifier, a3 as RegisterTransform, a4 as RegisterValue, a5 as Segment, a6 as SetValueCallback, a7 as SetValuePayload, a8 as SettledValidationStatus, a9 as SlimPrimitiveKind, aa as SlimRuntimeOf, ab as SubmitHandler, ac as Unset, ad as ValidateOn, af as ValidationError, ag as ValidationResponse, ah as ValidationResponseWithoutValue, ai as ValueOfUnion, aj as WriteMeta, ak as WriteShape, al as canonicalizePath, am as isPathPrefix, an as isUnset, ao as parseDottedPath, ap as unset } from './shared/attaform.C3WnCDXz.cjs';
+import { S as SupportedRootSchema, b as StorageShape } from './shared/attaform.CpXHK60W.cjs';
+export { P as PathInput, a as PathOutput } from './shared/attaform.CpXHK60W.cjs';
+import { S as SupportedRootSchema$1, U as UnwrapZodRoot, a as StorageShape$1 } from './shared/attaform.DRUT703x.cjs';
+import { z } from 'zod';
+import 'vue';
 
 /**
- * Options for `createAttaform()`.
- */
-type AttaformPluginOptions = SSRDetectOptions & {
-    /**
-     * Whether to install the Vue DevTools integration. Default `true`.
-     * The integration is dev-only: the `import('./devtools')` sits behind
-     * the `__DEV__` flag, so a consumer's production build folds it out
-     * entirely (no devtools chunk shipped, no fetch attempted). In
-     * development the DevTools peer is loaded lazily and a missing peer
-     * fails silently. Pass `false` to skip the integration even in dev.
-     */
-    devtools?: boolean;
-    /**
-     * App-level defaults applied to every `useForm` call in this app.
-     * Per-form options always win. See `AttaformDefaults` for
-     * the supported option set and the merge rules.
-     *
-     * ```ts
-     * app.use(
-     *   createAttaform({
-     *     defaults: { debounceMs: 100 },
-     *   })
-     * )
-     * ```
-     */
-    defaults?: AttaformDefaults;
+ * Type-level Zod-major discriminator for the unified `attaform/zod`
+ * entry. The runtime dispatch (`use-form.ts`'s impl) already routes on
+ * the schema's shape via `isZodV4SchemaShape`; this is the type-level
+ * mirror so the overloads and projection helpers discriminate the same
+ * way.
+ *
+ * Why a structural marker instead of `z.ZodObject`: the unified entry's
+ * overloads constrain on `z.ZodObject`, but the published `.d.mts`
+ * resolves `z` against whichever single Zod major the consumer
+ * installed. In a v3-only install `z.ZodObject` is v3's `ZodObject`
+ * (and, lacking its required type arguments, degrades to an `any`-like
+ * error type under `skipLibCheck`), so a v3 schema satisfies the v4
+ * overload's constraint and binds it — collapsing the read slot to
+ * `never`. A Zod v4 schema carries the `_zod` internals brand; a v3
+ * schema never does.
+ * Intersecting a v4-only constraint or conditional branch with this
+ * marker keeps it unreachable for a v3 schema regardless of how `zod`
+ * resolves, so v3 schemas fall through to the v3 overload.
+ *
+ * Distinct from `core/zod-shape.ts`'s runtime `ZodV4Shape` (which reads
+ * the public `def` getter): at the type level the stable v4 brand is
+ * `_zod.def`, the same internals `StorageShape` (v4) already reads.
+ *
+ * Pairing requirement: a v4 overload/branch must constrain on
+ * `z.ZodObject<z.ZodRawShape> & ZodV4Internals`, NOT bare
+ * `z.ZodObject & ZodV4Internals`. In a v3-only install `z.ZodObject`
+ * with no type argument is `ZodObject<T, ...>` missing its required
+ * arguments — an error type that behaves like `any` under
+ * `skipLibCheck`, so `any & ZodV4Internals` collapses back to `any` and
+ * the marker stops excluding v3 schemas. Supplying `z.ZodRawShape`
+ * keeps it a concrete object type in both majors, so the intersection
+ * stays meaningful.
+ */
+type ZodV4Internals = {
+    _zod: {
+        def: unknown;
+    };
 };
+
 /**
- * Create the Vue plugin that installs the form library on a Vue
- * application. Required only when you want app-wide options
- * (`defaults`, `devtools: false`, `ssr: true`) — for the default
- * setup, `useForm` / `injectForm` / `useRegister` lazy-install the
- * registry on first use.
- *
- * ```ts
- * import { createApp } from 'vue'
- * import { createAttaform } from 'attaform'
+ * Per-major projection helpers shared by the unified `attaform/zod`
+ * entry. Each maps an arbitrary Zod v4 OR v3 object schema to the
+ * `GenericForm`-shaped input / output / storage-read projections the
+ * form types are parameterised over. The constraint on each alias scopes
+ * `S` to one Zod major, so the projection is a direct read with no
+ * dispatch in the type body.
  *
- * createApp(App)
- *   .use(createAttaform({ defaults: { debounceMs: 100 } }))
- *   .mount('#app')
- * ```
- *
- * Under SSR with bare Vue 3, install explicitly with `{ ssr: true }`
- * from your server entry — the SSR serialization helpers
- * (`renderAttaformState` / `hydrateAttaformState`) require an
- * already-attached registry and don't trigger lazy install. Under
- * Nuxt, install via `attaform/nuxt` instead — the Nuxt module wires
- * both server and client automatically.
- *
- * Installing more than once on the same app is a no-op (the second
- * call logs a dev-mode warning).
+ * Hoisted out of `types-unified.ts` and `use-form.ts` so the two entry
+ * points share one definition. Internal — consumer code never reaches
+ * for these; the overloaded `useForm` already gives full inference at
+ * call sites.
  */
-declare function createAttaform(options?: AttaformPluginOptions): Plugin;
 
 /**
- * Serialised snapshot of every form in a Vue app, produced by
- * `renderAttaformState` and consumed by `hydrateAttaformState`.
- *
- * JSON-safe — pass to `JSON.stringify`, `devalue`, or any other
- * serialiser before embedding in your SSR payload.
- */
-type SerializedAttaformState = {
-    /** Tuples of `[formKey, snapshot]` for every form in the app. */
-    readonly forms: ReadonlyArray<readonly [FormKey, SerializedFormData]>;
-};
+ * The schema's own input type, exactly as a consumer would reference it
+ * (`z.input<S>`) — NOT routed through `GenericForm` / `UnwrapZodRoot`. This
+ * is the reflexive escape arm `AcceptableDefaults` adds to the
+ * `defaultValues` slot so a generic form wrapper forwarding `z.input<S>`
+ * type-checks under a free `S` (#422). It must stay syntactically identical
+ * to what the wrapper forwards: wrapping it in a conditional makes it a
+ * deferred conditional that no longer matches the forwarded value under a
+ * generic. Wrong-major schemas can't actually bind the slot — they are
+ * rejected at the overload's `schema` constraint — so the raw input never
+ * widens the slot for the wrong major.
+ */
+type V4SchemaInput<S extends SupportedRootSchema> = z.input<S>;
+type V3SchemaInput<S extends SupportedRootSchema$1> = z.input<S>;
+type V4FormOf<S extends SupportedRootSchema> = z.input<S> extends GenericForm ? z.input<S> : never;
+type V4OutOf<S extends SupportedRootSchema> = z.output<S> extends GenericForm ? z.output<S> : never;
+type V4ReadOf<S extends SupportedRootSchema> = StorageShape<S> extends GenericForm ? StorageShape<S> : never;
+type V3FormOf<S extends SupportedRootSchema$1> = z.input<UnwrapZodRoot<S>> extends GenericForm ? z.input<UnwrapZodRoot<S>> : never;
+type V3OutOf<S extends SupportedRootSchema$1> = z.output<UnwrapZodRoot<S>> extends GenericForm ? z.output<UnwrapZodRoot<S>> : never;
+type V3ReadOf<S extends SupportedRootSchema$1> = StorageShape$1<UnwrapZodRoot<S>> extends GenericForm ? StorageShape$1<UnwrapZodRoot<S>> : never;
+
 /**
- * Snapshot every form on a Vue app for SSR. Call from your server
- * entry after rendering the app:
+ * Create a form bound to a Zod v4 schema.
  *
  * ```ts
- * import { renderToString } from '@vue/server-renderer'
- * import { renderAttaformState, escapeForInlineScript } from 'attaform'
- *
- * const html = await renderToString(app)
- * const state = renderAttaformState(app)
- * const payload = escapeForInlineScript(JSON.stringify(state))
+ * import { useForm } from 'attaform/zod'
+ * import { z } from 'zod'
  *
- * return `
- *   ${html}
- *   <script>window.__ATTAFORM_STATE__ = ${payload}</script>
- * `
+ * const form = useForm({
+ *   schema: z.object({
+ *     username: z.string().min(2, 'At least 2 characters'),
+ *     password: z.string().min(8, 'At least 8 characters'),
+ *   }),
+ * })
  * ```
  *
- * Pair with `hydrateAttaformState` on the client to restore the
- * forms in their server-rendered state. Nuxt users don't need this —
- * `attaform/nuxt` wires SSR automatically.
+ * The constraint intersects `ZodV4Internals` (the v4-only `_zod`
+ * brand) so a v3 schema can't bind this overload even when `z`
+ * resolves to v3 in a single-major consumer install; v3 schemas fall
+ * through to the v3 overload below. See `types-zod-major.ts`.
  */
-declare function renderAttaformState(app: App): SerializedAttaformState;
+declare function useForm<Schema extends SupportedRootSchema & ZodV4Internals, K extends FormKey = FormKey>(configuration: Omit<UseFormConfiguration<V4FormOf<Schema>, V4OutOf<Schema>, AbstractSchema<V4FormOf<Schema>, V4OutOf<Schema>>, never, K>, 'schema' | 'validateOn' | 'debounceMs' | 'defaultValues'> & {
+    schema: Schema;
+    defaultValues?: AcceptableDefaults<V4FormOf<Schema>, V4SchemaInput<Schema>>;
+} & ValidateOnConfig): UseFormReturnType<V4FormOf<Schema>, V4OutOf<Schema>, V4ReadOf<Schema>, K>;
 /**
- * Restore forms from a server-rendered snapshot on the client. Call
- * from your client entry before mounting:
+ * Create a form bound to a Zod v3 schema.
  *
  * ```ts
- * import { createApp } from 'vue'
- * import { createAttaform, hydrateAttaformState } from 'attaform'
+ * import { useForm } from 'attaform/zod'
+ * import { z } from 'zod-v3'
  *
- * const app = createApp(App).use(createAttaform())
- * hydrateAttaformState(app, window.__ATTAFORM_STATE__)
- * app.mount('#app')
+ * const form = useForm({
+ *   schema: z.object({
+ *     username: z.string().min(2, 'At least 2 characters'),
+ *     password: z.string().min(8, 'At least 8 characters'),
+ *   }),
+ * })
  * ```
  *
- * The next `useForm({ key })` call for each serialised form picks up
- * the snapshot transparently — no further action is required.
+ * v3 schemas match this overload; v4 schemas hit the v4 overload
+ * above first and never reach here.
  */
-declare function hydrateAttaformState(app: App, payload: SerializedAttaformState): void;
+declare function useForm<Schema extends SupportedRootSchema$1, K extends FormKey = FormKey>(configuration: Omit<UseFormConfiguration<V3FormOf<Schema>, V3OutOf<Schema>, AbstractSchema<V3FormOf<Schema>, V3OutOf<Schema>>, never, K>, 'schema' | 'validateOn' | 'debounceMs' | 'defaultValues'> & {
+    schema: Schema;
+    defaultValues?: AcceptableDefaults<V3FormOf<Schema>, V3SchemaInput<Schema>>;
+} & ValidateOnConfig): UseFormReturnType<V3FormOf<Schema>, V3OutOf<Schema>, V3ReadOf<Schema>, K>;
 
 /**
- * Escape a JSON string so it's safe to embed inside an inline
- * `<script>` tag during SSR. Plain `JSON.stringify` is not safe — a
- * form value containing the literal substring `</script>` would
- * break out of the script tag.
+ * Type-level helpers for the unified `attaform/zod` entry. These give
+ * tests and other type-query call sites a deterministic projection
+ * over an arbitrary v4 OR v3 schema, sidestepping the brittle
+ * instantiation-expression resolution rules TypeScript applies to
+ * overloaded functions (`typeof useForm<X>` can pick the wrong
+ * overload or the impl signature, depending on whether the type
+ * argument is a concrete schema, a generic, or a constraint).
  *
- * ```ts
- * const payload = escapeForInlineScript(JSON.stringify(renderAttaformState(app)))
- * // `<script>window.__ATTAFORM_STATE__ = ${payload}</script>` is safe.
- * ```
+ * The helpers dispatch ONCE per use site via a binary conditional —
+ * no stacking, no amplification across the return type. Equivalent
+ * to writing `ReturnType<typeof useForm<S>>` but cache-stable across
+ * call patterns.
  *
- * Output remains valid JSON — `JSON.parse` round-trips back to the
- * original value on the client.
+ * Per `inference-first DX`, these helpers are test- and
+ * internal-facing. Consumer code shouldn't reach for them — the
+ * overloaded `useForm` already gives full inference at call sites.
  */
-declare function escapeForInlineScript(json: string): string;
 
 /**
- * Schema-agnostic `useForm`. Accepts any object that implements
- * `AbstractSchema` — useful when integrating a custom schema
- * adapter or a third-party validation library.
- *
- * ```ts
- * import { useForm } from 'attaform'
- *
- * const form = useForm({
- *   schema: myCustomAdapter,
- *   defaultValues: { name: '' },
- * })
- * ```
- *
- * Most consumers prefer a typed entry point that wraps the underlying
- * library's schema with the matching adapter automatically; see the
- * subpath documentation for the available adapters.
- *
- * Returns the same form API as the typed entry points; see
- * `UseFormReturnType` for the full surface.
+ * Direct V4 projection — no major-dispatch. Use when the schema's
+ * Zod major is known statically (typical for V4 generic helpers like
+ * `function setup<S extends z.ZodObject>(s: S)`). TS simplifies the
+ * helper cleanly under generic constraints because no conditional
+ * is present.
  */
-declare function useAbstractForm<Form extends GenericForm, GetValueFormType extends GenericForm = Form, ReadForm extends GenericForm = Form, K extends FormKey = FormKey>(configuration: UseFormConfiguration<Form, GetValueFormType, AbstractSchema<Form, GetValueFormType>, DefaultValuesInput<Form>, K>, 
+type UseFormReturnV4<Schema extends z.ZodObject, K extends FormKey = FormKey> = UseFormReturnType<V4FormOf<Schema>, V4OutOf<Schema>, V4ReadOf<Schema>, K>;
 /**
- * Internal escape hatch for callers that already hold a registry
- * reference and need to construct a form outside Vue's setup context
- * (e.g. the wizard's lazy noop builder, which runs inside a
- * `computed` re-eval). Passing this skips the strict `useRegistry()`
- * call; everything else (FormStore allocation, registry presence,
- * consumer ref-counting via `onScopeDispose`) goes through the same
- * path eager calls follow. Not part of the public surface.
+ * Direct V4 configuration projection. Mirrors `UseFormReturnV4`.
  */
-options?: {
-    readonly registry?: AttaformRegistry;
-}): UseFormReturnType<Form, GetValueFormType, ReadForm, K>;
-
+type UseFormConfigV4<Schema extends z.ZodObject, K extends FormKey = FormKey> = Omit<UseFormConfiguration<V4FormOf<Schema>, V4OutOf<Schema>, AbstractSchema<V4FormOf<Schema>, V4OutOf<Schema>>, DefaultValuesInput<V4FormOf<Schema>>, K>, 'schema' | 'validateOn' | 'debounceMs'> & {
+    schema: Schema;
+} & ValidateOnConfig;
 /**
- * Symbol slot used by custom directive integrations to install an
- * assigner on the bound element. Read by the v-register directive
- * when a DOM event fires:
- *
- * ```ts
- * import { assignKey } from 'attaform'
- * el[assignKey] = (value) => myCustomWriter(value)
- * ```
- *
- * Most consumers never need this — the built-in directives wire
- * default assigners for text inputs, checkboxes, radios, and selects.
+ * Direct V3 projection — no major-dispatch. Use when the schema's
+ * Zod major is known statically.
  */
-declare const assignKey: unique symbol;
-
+type UseFormReturnV3<Schema extends z.ZodObject<z.ZodRawShape>, K extends FormKey = FormKey> = UseFormReturnType<V3FormOf<Schema>, V3OutOf<Schema>, V3ReadOf<Schema>, K>;
 /**
- * The `v-register` directive. Bind a form field to a native input,
- * select, textarea, checkbox, or radio:
- *
- * ```vue
- * <input v-register="form.register('email')" />
- * <select v-register="form.register('country')">
- *   <option value="us">US</option>
- *   <option value="uk">UK</option>
- * </select>
- * ```
- *
- * The directive picks the right binding strategy automatically based
- * on the element's `tagName` and `type`. Registered globally by
- * `createAttaform()`. Most consumers never import it directly, but
- * it's exposed for advanced integrations that wire directives
- * manually.
+ * Direct V3 configuration projection. Mirrors `UseFormReturnV3`.
  */
-declare const vRegister: RegisterModelDynamicCustomDirective;
-
+type UseFormConfigV3<Schema extends z.ZodObject<z.ZodRawShape>, K extends FormKey = FormKey> = Omit<UseFormConfiguration<V3FormOf<Schema>, V3OutOf<Schema>, AbstractSchema<V3FormOf<Schema>, V3OutOf<Schema>>, DefaultValuesInput<V3FormOf<Schema>>, K>, 'schema' | 'validateOn' | 'debounceMs'> & {
+    schema: Schema;
+} & ValidateOnConfig;
 /**
- * Type guard for a `RegisterValue`. Returns `true` when `val` looks
- * like the object returned from `form.register(path)`.
+ * The return shape of `useForm` for a given Zod schema. Dispatches
+ * once on the schema's major version and projects to the matching
+ * adapter's `Form` / `Out` / `Read` slots. The dispatch matches the
+ * full `SupportedRootSchema` per major, so an object, record, or
+ * discriminated-union root all resolve here exactly as the runtime
+ * `useForm` overloads accept them.
  *
- * ```ts
- * if (isRegisterValue(slotValue)) {
- *   // slotValue.innerRef is now a Ref<unknown>
- * }
- * ```
- *
- * Useful when building wrapper components that accept either a
- * `RegisterValue` or a plain ref via the same prop.
+ * Replaces `ReturnType<typeof useForm<Schema, K>>` in test code with
+ * concrete schemas. For generic helpers (`<S extends z.ZodObject>`),
+ * use `UseFormReturnV4<S>` directly — TS doesn't simplify
+ * conditional types under generic constraints, so the dispatch in
+ * this helper stays deferred and TS can't prove return-type
+ * compatibility.
  */
-declare function isRegisterValue<Value = unknown>(val: unknown): val is RegisterValue<Value>;
-
+type UseFormReturn<Schema, K extends FormKey = FormKey> = Schema extends SupportedRootSchema & ZodV4Internals ? UseFormReturnType<V4FormOf<Schema>, V4OutOf<Schema>, V4ReadOf<Schema>, K> : Schema extends SupportedRootSchema$1 ? UseFormReturnType<V3FormOf<Schema>, V3OutOf<Schema>, V3ReadOf<Schema>, K> : never;
 /**
- * Shared building blocks for Attaform's two devtools surfaces — the Vue
- * DevTools (Chrome-extension) inspector wired up in `./devtools.ts`, and
- * the Nuxt DevTools (overlay) panel wired up via `../../nuxt.ts` +
- * `../pages/_attaform_devtools.vue`.
- *
- * Houses the window-bridge contract both surfaces consume so a new
- * bridge field lands in one file. Both surfaces render RAW form values
- * by design — DevTools is a dev-only surface, and redaction across every
- * place a value surfaces is impractical security theater rather than a
- * real safeguard.
+ * The configuration parameter shape of `useForm` for a given Zod
+ * schema. Mirrors `UseFormReturn`'s dispatch — replaces
+ * `Parameters<typeof useForm<Schema, K>>[0]` in test code.
  */
+type UseFormConfig<Schema, K extends FormKey = FormKey> = Schema extends SupportedRootSchema & ZodV4Internals ? Omit<UseFormConfiguration<V4FormOf<Schema>, V4OutOf<Schema>, AbstractSchema<V4FormOf<Schema>, V4OutOf<Schema>>, DefaultValuesInput<V4FormOf<Schema>>, K>, 'schema' | 'validateOn' | 'debounceMs'> & {
+    schema: Schema;
+} & ValidateOnConfig : Schema extends SupportedRootSchema$1 ? Omit<UseFormConfiguration<V3FormOf<Schema>, V3OutOf<Schema>, AbstractSchema<V3FormOf<Schema>, V3OutOf<Schema>>, DefaultValuesInput<V3FormOf<Schema>>, K>, 'schema' | 'validateOn' | 'debounceMs'> & {
+    schema: Schema;
+} & ValidateOnConfig : never;
 
 /**
- * Property key on `window` that the Nuxt-side dev plugin attaches the
- * bridge object to. The iframe-mounted overlay panel reads
- * `window.parent[DEVTOOLS_WINDOW_KEY]` to reach the host app's registry.
+ * Field-metadata write/read API for the unified `attaform/zod` entry.
  *
- * Underscored + namespaced to make accidental collision with consumer
- * globals vanishingly unlikely. Stable across versions — bumping it
- * would silently disconnect older library builds from newer overlay
- * panels in the same browser tab during a library upgrade.
- */
-declare const DEVTOOLS_WINDOW_KEY = "__attaform_devtools__";
-/**
- * Shape of the object the host plugin attaches to `window` in dev mode.
- * The iframe overlay panel reads this to discover the live registry and
- * render its forms.
+ * Storage is shared with both adapters via `field-meta-store` — a
+ * payload written here is visible to whichever adapter the unified
+ * `useForm` dispatches to at runtime, regardless of Zod major. No
+ * `zod` runtime import; the type-only `import type` is erased at
+ * build, so `attaform/zod` carries no `z.registry` reference even
+ * when consumed by a Zod 3 project without the Vite plugin alias.
  *
- * Single-registry assumption: the latest `createAttaform()` install
- * wins. Multi-app pages (rare; typically only seen in micro-frontend
- * setups) will only see one app's forms in the panel. Documented but
- * not actively supported — the alternative (a Set of registries with
- * union-rendering) is a future call if a real consumer hits it.
+ * The native v4 chain `schema.register(fieldMeta, payload)` continues
+ * to work — Zod 4's `.register()` only calls `.add(this, payload)`
+ * structurally, satisfied by the shared store.
  */
-interface AttaformDevtoolsBridge {
-    registry: AttaformRegistry;
-    /**
-     * The library version, surfaced in the panel's footer for support /
-     * bug-report context. Read from `package.json` at host-plugin init.
-     */
-    version: string;
-}
-declare global {
-    interface Window {
-        [DEVTOOLS_WINDOW_KEY]?: AttaformDevtoolsBridge;
-    }
-}
 
+type ZodFieldMetaRegistry = ReturnType<typeof z.registry<FieldMetaPayload>>;
 /**
- * Anti-flash timing for the library-default display reducer.
- *
- * - `showDelay` — how long in-flight work (a validation run or an async
- *   register transform) may run before its spinner is allowed to show. Work
- *   that settles inside this window never reveals `'pending'` at all, so a
- *   fast (often synchronous) check does not flash a spinner on every keystroke.
- * - `minVisible` — once shown, the minimum time the spinner stays up. Work
- *   that lands just past `showDelay` is held here so the spinner does not
- *   itself flash on and immediately off.
+ * The shared registry every Attaform-aware Zod schema can register
+ * field metadata against, regardless of major. Same instance the v3
+ * and v4 adapter entries expose — write in one place, read from
+ * any.
  *
- * Both are milliseconds.
+ * Cast to Zod 4's `$ZodRegistry<FieldMetaPayload>` so the native
+ * `schema.register(fieldMeta, payload)` chain type-checks for v4
+ * users; the runtime call only needs `.add` structurally, which the
+ * shared store provides.
  */
-type DisplayTimings = {
-    readonly showDelay: number;
-    readonly minVisible: number;
-};
-/**
- * Library-default anti-flash timings. `showDelay: 120` cleanly swallows
- * synchronous, microtask-resolved, and tiny-async work (validation runs and
- * async register transforms alike) so none of them flash a spinner;
- * `minVisible: 120` keeps a shown spinner snappy once one does land.
- * Retune via {@link makeDefaultDisplayState} without touching the engine.
- */
-declare const DEFAULT_TIMINGS: DisplayTimings;
-/**
- * Build a default `getDisplayState` reducer with custom anti-flash timing.
- * Power users who want a tighter or looser spinner than {@link DEFAULT_TIMINGS}
- * pass their own `{ showDelay, minVisible }`:
- *
- * ```ts
- * import { makeDefaultDisplayState } from 'attaform'
- *
- * useForm({
- *   schema,
- *   getDisplayState: makeDefaultDisplayState({ showDelay: 50, minVisible: 200 }),
- * })
- * ```
- *
- * The returned reducer is pure: the engine injects `now` and threads the
- * previous machine, so the same `(prev, ctx)` always yields the same next
- * machine. It shapes only the display projection — `errors`, `valid`,
- * `validating`, and the underlying validation run exactly as before.
- */
-declare function makeDefaultDisplayState({ showDelay, minVisible, }: DisplayTimings): GetDisplayState;
+declare const fieldMeta: ZodFieldMetaRegistry;
 /**
- * Library-default `getDisplayState` reducer. Resolves every path's
- * `field.displayState` — and thus `field.show*` and the `form.meta`
- * rollups — whenever the consumer has not configured an override at the
- * per-form or plugin level. Built from {@link DEFAULT_TIMINGS}; publicly
- * re-exported so an override can compose with it (a layered reducer that
- * special-cases a subtree but otherwise defers picks up future
- * refinements for free):
+ * Attach `payload` to `schema` in the shared registry and return a
+ * clone of `schema` so each call gets its own identity (the registry
+ * keys on schema reference, so cloning prevents last-write-wins
+ * collisions for sub-schemas reused at multiple paths).
  *
- * ```ts
- * import { defaultDisplayState } from 'attaform'
+ * Works on both Zod 3 and Zod 4 schemas — branches on the runtime
+ * shape of the schema:
+ * - Zod 4 schemas expose a public `.clone()` method; we call it.
+ * - Zod 3 schemas don't, so we reconstruct via
+ *   `new schema.constructor(schema._def)`.
  *
- * useForm({
- *   schema,
- *   getDisplayState: (prev, ctx) => {
- *     const next = defaultDisplayState(prev, ctx)
- *     return next.display === 'success' && ctx.field.path[0] === 'username'
- *       ? { display: 'idle' }
- *       : next
- *   },
- * })
- * ```
+ * Both forms produce a fresh schema with the same effective
+ * structure, so the registry slot is unique to this call site.
  */
-declare const defaultDisplayState: GetDisplayState;
+declare function withMeta<S>(schema: S, payload: FieldMetaPayload): S;
 
-export { AbstractSchema, AttaformDefaults, AttaformRegistry, DEFAULT_TIMINGS, DEVTOOLS_WINDOW_KEY, DefaultValuesInput, FormKey, GenericForm, GetDisplayState, RegisterValue, SerializedFormData, UseFormConfiguration, UseFormReturnType, assignKey, createAttaform, defaultDisplayState, escapeForInlineScript, hydrateAttaformState, isRegisterValue, makeDefaultDisplayState, renderAttaformState, useAbstractForm as useForm, vRegister };
-export type { AttaformDevtoolsBridge, AttaformPluginOptions, DisplayTimings, SerializedAttaformState };
+export { DefaultValuesInput, FieldMetaPayload, FormKey, GenericForm, UseFormConfiguration, UseFormReturnType, ValidateOnConfig, fieldMeta, useForm, withMeta };
+export type { UseFormConfig, UseFormConfigV3, UseFormConfigV4, UseFormReturn, UseFormReturnV3, UseFormReturnV4 };