attaform 0.30.0 → 0.30.1

package/dist/vite.d.mts

@@ -28,9 +28,9 @@ import { Plugin } from 'vite';
  * can be called at all.
  *
  * Deliberately absent (reach for these with an explicit import):
- *   - `useAbstractForm` — the schema-agnostic escape hatch on
- *     `attaform/abstract`, an advanced surface, not the default form.
- *   - `createAttaform` — the plugin install, a setup-level one-liner that
+ *   - `useAbstractForm`, the schema-agnostic escape hatch on
+ *     `attaform/abstract`: an advanced surface, not the default form.
+ *   - `createAttaform`, the plugin install, a setup-level one-liner that
  *     belongs beside the app bootstrap, not in every component's scope.
  *   - `unset` / `isUnset` and the serialize helpers: plain values and
  *     functions with no component affinity, equally at home in a store, a
@@ -63,41 +63,14 @@ declare const attaformAutoImports: AttaformAutoImport[];
 declare const attaformAutoImportsMap: Record<string, string[]>;
 
 /**
- * `attaform/vite` — Vite plugin that wires the compile-time node
- * transforms with @vitejs/plugin-vue, binds `v-register` into each
- * compiled template that uses it (so no app-level directive
- * registration exists or is needed), AND rewrites `attaform` and
- * `attaform/zod` imports to either `attaform/zod-v3` or `attaform/zod-v4`
- * at build time, based on the consumer's installed Zod major. The result
- * is one Zod adapter shipped per bundle, with no manual subpath choice.
+ * `attaform/vite`, the Vite plugin. See {@link attaform} for what it
+ * does and how to register it.
  *
- * Usage (bare Vue 3 consumers):
- *
- *   // vite.config.ts
- *   import vue from '@vitejs/plugin-vue'
- *   import { attaform } from 'attaform/vite'
- *
- *   export default defineConfig({
- *     plugins: [vue(), attaform()],
- *   })
- *
- * The transforms inject `:value`, `:checked`, and `:selected` bindings
- * into elements that use the `v-register` directive — load-bearing for
- * SSR initial-render correctness. Omitting this plugin under CSR is
- * tolerable (one-frame flash on mount); omitting it under SSR produces
- * visibly wrong initial HTML.
- *
- * The `resolveZodAlias` option (default `true`) controls the build-time
- * rewrite of `attaform` / `attaform/zod`. Set to `false` if your project
- * intentionally mixes Zod versions or has a non-standard Zod resolution;
- * the unified entry's runtime dispatch covers that case at the cost of
- * bundling both adapters.
- *
- * Implementation note: this plugin mutates @vitejs/plugin-vue's options
- * via the documented but somewhat informal `api.options` surface used
- * by VueUse, Vite PWA, and other Vue ecosystem plugins. If you're
- * using a custom Vue plugin wrapper, fall back to `attaform/transforms`
- * and wire them yourself.
+ * It mutates @vitejs/plugin-vue's options through the documented but
+ * somewhat informal `api.options` surface that VueUse, Vite PWA and
+ * other Vue ecosystem plugins also use. Behind a custom Vue plugin
+ * wrapper, fall back to `attaform/transforms` and wire the transforms
+ * yourself.
  */
 
 /** Options for `attaform()`. */
@@ -105,8 +78,8 @@ interface AttaformVitePluginOptions {
     /**
      * Rewrite `attaform` and `attaform/zod` imports at build time to
      * either `attaform/zod-v3` or `attaform/zod-v4`, based on the
-     * consumer's installed Zod major. Default `true` — produces a leaner
-     * bundle for the common case of one Zod version per project.
+     * consumer's installed Zod major. Default `true`, which produces a
+     * leaner bundle for the common case of one Zod version per project.
      *
      * Set to `false` to fall through to the unified entry's runtime
      * dispatch. Useful when:
@@ -120,12 +93,10 @@ interface AttaformVitePluginOptions {
     resolveZodAlias?: boolean;
 }
 /**
- * Vite plugin that wires the form library's compile-time template
- * transforms into `@vitejs/plugin-vue`, binds the `v-register`
- * directive into each compiled template that uses it, and rewrites the
- * bare `attaform` barrel and the unified `attaform/zod` import to the
- * matching adapter subpath. Required for SSR and for hydration
- * accuracy under bare Vue 3.
+ * Vite plugin that wires Attaform's compile-time template transforms
+ * into `@vitejs/plugin-vue`, binds `v-register` into each compiled
+ * template that uses it, and rewrites the bare `attaform` barrel and
+ * the unified `attaform/zod` import to the matching adapter subpath.
  *
  * ```ts
  * // vite.config.ts
@@ -137,14 +108,20 @@ interface AttaformVitePluginOptions {
  * })
  * ```
  *
- * Place the call after `vue()` in the plugins array. Nuxt projects
- * don't need this — `attaform/nuxt` handles it.
+ * Place the call after `vue()`. Nuxt projects do not need it;
+ * `attaform/nuxt` handles this.
+ *
+ * The transforms inject `:value`, `:checked` and `:selected` onto
+ * elements using `v-register`, which is load-bearing for SSR
+ * initial-render correctness. Omitting the plugin under CSR costs a
+ * one-frame flash on mount; omitting it under SSR produces visibly
+ * wrong initial HTML.
  *
- * Returns a two-plugin array (Vite flattens nested plugin arrays): the
- * main pre-plugin above, plus a post-plugin that rewrites each compiled
- * SFC's `resolveDirective("register")` to a static import from
- * `attaform/directive`. The rewrite is why no app-level directive
- * registration exists or is needed here — see
+ * Returns a two-plugin array, since Vite flattens nested plugin arrays:
+ * the main pre-plugin, plus a post-plugin rewriting each compiled SFC's
+ * `resolveDirective("register")` to a static import from
+ * `attaform/directive`. That rewrite is why no app-level directive
+ * registration is needed here; see
  * `runtime/lib/core/transforms/directive-delivery-transform.ts` for the
  * mechanism and its scope.
  */

package/dist/vite.mjs

@@ -1,5 +1,5 @@
-import { r as resolveZodAliasTarget, i as isRewritableZodSpecifier } from './shared/attaform.DhnPb6nK.mjs';
-import { a as vRegisterPreambleTransform, r as redundantBindingWarnTransform, c as componentBridgeTransform, i as inputTextAreaNodeTransform, v as vRegisterHintTransform } from './shared/attaform.BK0cgu2K.mjs';
+import { r as resolveZodAliasTarget, i as isRewritableZodSpecifier } from './shared/attaform.BAf3UNn4.mjs';
+import { a as vRegisterPreambleTransform, r as redundantBindingWarnTransform, c as componentBridgeTransform, i as inputTextAreaNodeTransform, v as vRegisterHintTransform } from './shared/attaform.ZYn2ahzJ.mjs';
 import { parse, babelParse } from '@vue/compiler-sfc';
 import { NodeTypes } from '@vue/compiler-core';
 
@@ -308,7 +308,7 @@ function attaform(options = {}) {
 
       // The panel runs inside Nuxt DevTools' overlay iframe, which itself
       // is nested in the consumer's main page. \`window.parent\` only
-      // crosses one frame boundary \u2014 the overlay UI \u2014 which doesn't have
+      // crosses one frame boundary (the overlay UI), which doesn't have
       // the bridge attached. The bridge lives on the consumer's main
       // page, which sits at the top of the frame hierarchy. Walk the
       // chain checking each ancestor frame so the same code works whether

package/dist/webpack.d.mts

@@ -1,13 +1,14 @@
 import { W as WebpackFamilyPlugin, a as WebpackFamilyPluginOptions } from './shared/attaform.C9fPTxjB.mjs';
 
 /**
- * `attaform/webpack` — webpack plugin that rewrites `attaform/zod`
+ * `attaform/webpack`, the webpack plugin that rewrites `attaform/zod`
  * imports to the single matching adapter subpath (`attaform/zod-v3` or
  * `attaform/zod-v4`) at build time, based on the consumer's installed Zod
  * major. Without it, webpack ships both adapters because the unified
  * `attaform/zod` entry imports both for runtime dispatch.
  *
- * Usage (ESM config — the plugin is ESM-only, matching attaform's package):
+ * Usage, in an ESM config, since the plugin is ESM-only like the rest of
+ * the package:
  *
  *   // webpack.config.mjs
  *   import { attaform } from 'attaform/webpack'
@@ -16,16 +17,12 @@ import { W as WebpackFamilyPlugin, a as WebpackFamilyPluginOptions } from './sha
  *     plugins: [attaform()],
  *   }
  *
- * This plugin only does the adapter rewrite. The Vue SFC `v-register`
- * transforms that `attaform/vite` wires (load-bearing for SSR initial
- * render) are `@vitejs/plugin-vue`-specific and do not transfer; a
- * non-Vite consumer that needs them wires `attaform/transforms` into
- * their Vue compiler separately. The `v-register` directive itself is
- * also delivered by the Vite plugin's compile-time binding, so outside
- * that pipeline register it once per app:
- *
- *   import { installVRegister } from 'attaform/directive'
- *   installVRegister(app)
+ * The adapter rewrite is all this plugin does. Two things
+ * `attaform/vite` also provides do NOT transfer, because both are
+ * `@vitejs/plugin-vue`-specific: wire `attaform/transforms` into your
+ * Vue compiler for the SSR-critical template transforms, and register
+ * the directive once per app with `installVRegister(app)` from
+ * `attaform/directive`.
  *
  * Zero-dep: the plugin imports nothing from `webpack` (it taps the resolve
  * hook the compiler injects at the consumer's build). Shares its body with
@@ -36,6 +33,17 @@ import { W as WebpackFamilyPlugin, a as WebpackFamilyPluginOptions } from './sha
 type AttaformWebpackPluginOptions = WebpackFamilyPluginOptions;
 /** The structural shape webpack requires of the plugin. */
 type AttaformWebpackPlugin = WebpackFamilyPlugin;
+/**
+ * webpack plugin that resolves `attaform/zod` to the one adapter subpath
+ * matching the installed Zod major, so the build ships a single adapter
+ * instead of both.
+ *
+ * ```js
+ * const { attaform } = require('attaform/webpack')
+ *
+ * module.exports = { plugins: [attaform()] }
+ * ```
+ */
 declare function attaform(options?: AttaformWebpackPluginOptions): AttaformWebpackPlugin;
 
 export { attaform };

package/dist/webpack.mjs

@@ -1,4 +1,4 @@
-import { c as createWebpackFamilyPlugin } from './shared/attaform.v0fQtWyA.mjs';
+import { c as createWebpackFamilyPlugin } from './shared/attaform.B1rH9ht6.mjs';
 
 function attaform(options = {}) {
   return createWebpackFamilyPlugin("attaform/webpack", options);

package/dist/zod-v3.d.mts

@@ -1,22 +1,21 @@
 import { z } from 'zod';
-import { G as GenericForm, F as FormKey, U as UseFormConfiguration, aq as AcceptableDefaults, a as UseFormReturnType, ac as ValidateOnConfig, ap as SchemaFactoryOptions, h as FieldMetaPayload } from './shared/attaform.bKLzMU0o.mjs';
+import { G as GenericForm, F as FormKey, U as UseFormConfiguration, aq as AcceptableDefaults, a as UseFormReturnType, ac as ValidateOnConfig, ap as SchemaFactoryOptions, h as FieldMetaPayload } from './shared/attaform.Br8EBn5B.mjs';
 import { AbstractSchema } from './abstract.mjs';
-export { b as ArrayItem, c as ArrayPath, C as CustomDirectiveRegisterAssignerFn, d as DeepPartial, D as DefaultValuesInput, e as DefaultValuesShape, f as DisplayState, E as ErrorInput, g as ErrorsProxyShape, i as FieldState, j as FieldStateMap, k as FieldStateMapEntry, l as FlatPath, m as FormErrorRecord, n as FormErrorsSurface, o as FormMeta, H as HandleSubmit, p as HistoryPlugin, I as IsTuple, q as IsUnion, J as JoinSegments, r as Json, K as KeyofUnion, L as LiftedValueShape, M as MetaTrackerValue, N as NestedReadType, s as NestedType, O as OnError, t as OnSubmit, P as ParseOptions, u as PartialFlatPath, v as Path, w as PathKey, x as PendingValidationStatus, y as Primitive, R as ROOT_PATH, z as ROOT_PATH_KEY, B as ReactiveValidationStatus, Q as RecordPath, S as RecordValue, T as RegisterDirective, V as RegisterFlatPath, W as RegisterOptions, X as RegisterSelectModifier, Y as RegisterTextModifier, Z as RegisterTransform, _ as RegisterValue, $ as SchemaDefaultsResult, a0 as SchemaParseErrorWithData, a1 as SchemaParseErrorWithoutData, a2 as SchemaParseResult, a3 as SchemaParseSuccess, a4 as Segment, a5 as SetValueCallback, a6 as SetValuePayload, a7 as SettledValidationStatus, a8 as SlimPrimitiveKind, a9 as SubmitHandler, aa as Unset, ab as ValidateOn, ad as ValidationError, ae as ValidationResponse, af as ValidationResponseWithoutValue, ag as ValueOfUnion, ah as WriteMeta, ai as WriteShape, aj as canonicalizePath, ak as isPathPrefix, al as isUnset, am as parseDottedPath, an as unset } from './shared/attaform.bKLzMU0o.mjs';
-import { S as SupportedRootSchema, U as UnwrapZodRoot, a as StorageShape } from './shared/attaform.DRUT703x.mjs';
-export { a as AnyForm, b as AttaformDevtoolsBridge, c as AttaformError, d as AttaformErrorCode, e as AttaformPluginOptions, A as AttaformRegistry, C as CompiledStep, D as DEVTOOLS_WINDOW_KEY, F as FormStatus, f as FormStatusSeed, G as GateMarker, I as InjectWizardInput, g as InvalidPathError, h as InvalidUseFormConfigError, L as LazyMarker, O as OutsideSetupError, R as RegistryNotInstalledError, i as ReservedFormKeyError, S as SerializedAttaformState, j as SerializedFormData, k as StepSlot, l as SubmitErrorHandlerError, U as UseRegisterOptions, m 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 escapeForInlineScript, H as gate, J as getRegistryFromApp, K as hydrateAttaformState, M as injectForm, N as injectWizard, P as isRegisterValue, Q as kAttaformRegistry, T as lazy, V as renderAttaformState, X as useRegister, Y as useRegistry, Z as useWizard } from './shared/attaform.UGyOK83T.mjs';
-export { v as vRegister } from './shared/attaform.Clz0ArIi.mjs';
+export { b as ArrayItem, c as ArrayPath, C as CustomDirectiveRegisterAssignerFn, d as DeepPartial, D as DefaultValuesInput, e as DefaultValuesShape, f as DisplayState, E as ErrorInput, g as ErrorsProxyShape, i as FieldState, j as FieldStateMap, k as FieldStateMapEntry, l as FlatPath, m as FormErrorRecord, n as FormErrorsSurface, o as FormMeta, H as HandleSubmit, p as HistoryPlugin, I as IsTuple, q as IsUnion, J as JoinSegments, r as Json, K as KeyofUnion, L as LiftedValueShape, M as MetaTrackerValue, N as NestedReadType, s as NestedType, O as OnError, t as OnSubmit, P as ParseOptions, u as PartialFlatPath, v as Path, w as PathKey, x as PendingValidationStatus, y as Primitive, R as ROOT_PATH, z as ROOT_PATH_KEY, B as ReactiveValidationStatus, Q as RecordPath, S as RecordValue, T as RegisterDirective, V as RegisterFlatPath, W as RegisterOptions, X as RegisterSelectModifier, Y as RegisterTextModifier, Z as RegisterTransform, _ as RegisterValue, $ as SchemaDefaultsResult, a0 as SchemaParseErrorWithData, a1 as SchemaParseErrorWithoutData, a2 as SchemaParseResult, a3 as SchemaParseSuccess, a4 as Segment, a5 as SetValueCallback, a6 as SetValuePayload, a7 as SettledValidationStatus, a8 as SlimPrimitiveKind, a9 as SubmitHandler, aa as Unset, ab as ValidateOn, ad as ValidationError, ae as ValidationResponse, af as ValidationResponseWithoutValue, ag as ValueOfUnion, ah as WriteMeta, ai as WriteShape, aj as canonicalizePath, ak as isPathPrefix, al as isUnset, am as parseDottedPath, an as unset } from './shared/attaform.Br8EBn5B.mjs';
+import { S as SupportedRootSchema, U as UnwrapZodRoot, a as StorageShape } from './shared/attaform.B-Tb62qV.mjs';
+export { a as AnyForm, b as AttaformDevtoolsBridge, c as AttaformError, d as AttaformErrorCode, e as AttaformPluginOptions, A as AttaformRegistry, C as CompiledStep, D as DEVTOOLS_WINDOW_KEY, F as FormStatus, f as FormStatusSeed, G as GateMarker, I as InjectWizardInput, g as InvalidPathError, h as InvalidUseFormConfigError, L as LazyMarker, O as OutsideSetupError, R as RegistryNotInstalledError, i as ReservedFormKeyError, S as SerializedAttaformState, j as SerializedFormData, k as StepSlot, l as SubmitErrorHandlerError, U as UseRegisterOptions, m 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 escapeForInlineScript, H as gate, J as getRegistryFromApp, K as hydrateAttaformState, M as injectForm, N as injectWizard, P as isRegisterValue, Q as kAttaformRegistry, T as lazy, V as renderAttaformState, X as useRegister, Y as useRegistry, Z as useWizard } from './shared/attaform.BcQwgWaq.mjs';
+export { v as vRegister } from './shared/attaform.L0kUn3vL.mjs';
 import 'vue';
 
 /**
- * `FormOf` / `OutOf` / `ReadOf` factor the three identical-shape
- * conditionals out of the zod-typed `useForm` signature. The bundled
- * `.d.ts` then carries one alias per shape rather than re-inlining
- * `z.input<UnwrapZodObject<Schema>> extends GenericForm ? … : never`
- * four times — the pattern that produces TS2589 ("Type instantiation
- * is excessively deep") on consumer call sites with complex schemas
- * (discriminated unions, refines, deep `.register()` chains). Mirrors
- * the v4 adapter's own `FormOf`/`OutOf`/`ReadOf` aliases verbatim so
- * v3 and v4 carry the same per-call depth cost.
+ * Factor the three identical-shape conditionals out of the zod-typed
+ * `useForm` signature, so the bundled `.d.ts` carries one alias per
+ * shape instead of re-inlining `z.input<UnwrapZodRoot<Schema>> extends
+ * GenericForm ? ... : never` four times. That inlining is what produces
+ * TS2589 ("Type instantiation is excessively deep") at a consumer call
+ * site holding a discriminated union, a refine, or a deep `.register()`
+ * chain. The v4 adapter declares the same three aliases, so both lines
+ * carry the same per-call depth cost.
  */
 type FormOf<Schema extends SupportedRootSchema> = z.input<UnwrapZodRoot<Schema>> extends GenericForm ? z.input<UnwrapZodRoot<Schema>> : never;
 type OutOf<Schema extends SupportedRootSchema> = z.output<UnwrapZodRoot<Schema>> extends GenericForm ? z.output<UnwrapZodRoot<Schema>> : never;
@@ -27,39 +26,39 @@ type ReadOf<Schema extends SupportedRootSchema> = StorageShape<UnwrapZodRoot<Sch
  * ```ts
  * import { useForm } from 'attaform/zod-v3'
  *
- * const form = useForm({ schema: myAdapter, defaultValues: { … } })
+ * const form = useForm({ schema: myAdapter, defaultValues: { name: '' } })
  * ```
  *
- * For Zod schemas, prefer the overload that accepts a `ZodObject`
- * directly — it wraps the adapter automatically. For Zod v4, import
- * from `attaform/zod` instead.
+ * For a Zod schema, prefer the overload that takes the schema directly:
+ * it attaches the adapter for you. For Zod v4, import from
+ * `attaform/zod`.
  */
 declare function useForm<Form extends GenericForm, GetValueFormType extends GenericForm = Form, K extends FormKey = FormKey>(configuration: Omit<UseFormConfiguration<Form, GetValueFormType, AbstractSchema<Form, GetValueFormType>, never, K>, 'defaultValues'> & {
     defaultValues?: AcceptableDefaults<Form, Form>;
 }): UseFormReturnType<Form, GetValueFormType, Form, K>;
 /**
- * Create a form bound to a Zod v3 `ZodObject` schema.
+ * Create a form bound to a Zod v3 schema.
  *
  * ```ts
  * import { useForm } from 'attaform/zod-v3'
  * import { z } from 'zod'
  *
+ * const schema = z.object({
+ *   email: z.string().email(),
+ *   password: z.string().min(8),
+ * })
+ *
  * const form = useForm({
- *   schema: z.object({
- *     email: z.string().email(),
- *     password: z.string().min(8),
- *   }),
+ *   schema,
  *   defaultValues: { email: '' },
  *   validateOn: 'blur',
  * })
  * ```
  *
- * 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 v4, import from `attaform/zod` instead.
+ * The returned form carries `register`, `values`, `errors`, `fields`,
+ * `setValue`, `handleSubmit`, `meta` and the field-array helpers; see
+ * `UseFormReturnType` for the whole surface. For Zod v4, import from
+ * `attaform/zod`.
  */
 declare function useForm<Schema extends SupportedRootSchema, K extends FormKey = FormKey>(configuration: Omit<UseFormConfiguration<FormOf<Schema>, OutOf<Schema>, AbstractSchema<FormOf<Schema>, OutOf<Schema>>, never, K>, 'schema' | 'validateOn' | 'debounceMs' | 'defaultValues'> & {
     schema: Schema;
@@ -78,9 +77,9 @@ interface ZodTypeWithInnerType extends z.ZodTypeAny {
     };
 }
 /**
- * The "honest read shape" of a Zod v3 schema — fields under records,
- * arrays, and dynamic boundaries are tagged optional/undefined to
- * reflect the runtime reality that those slots may be missing.
+ * The honest read shape of a Zod v3 schema: a field under a record, an
+ * array or a dynamic boundary is tagged optional or undefined, matching
+ * the runtime reality that the slot may be missing.
  *
  * Used internally by the v3 adapter as the read-side type for
  * `getValue` / `getFieldState`. Not commonly needed in consumer code.
@@ -95,15 +94,12 @@ type TypeWithNullableDynamicKeys<Schema extends z.ZodSchema, CrossedBoundary ext
 z.infer<Schema> | (CrossedBoundary extends true ? undefined : never);
 
 /**
- * Wrap a Zod v3 form-root schema (`ZodObject` or `ZodRecord`) in an
+ * Wrap a Zod v3 form-root schema, a `ZodObject` or `ZodRecord`, in an
  * `AbstractSchema` factory.
  *
- * Most consumers never call this directly — `useForm` from
- * `attaform/zod-v3` does the wrapping automatically. Reach
- * for it only when integrating with a custom code path that needs
- * the adapter outside of `useForm`.
- *
- * Throws if the underlying schema isn't a supported form root.
+ * `useForm` from `attaform/zod-v3` does this for you, so reach for it
+ * only to use the adapter outside `useForm`. Throws if the schema is not
+ * a supported form root.
  */
 declare function zodAdapter<FormSchema extends z.ZodSchema, Form extends z.input<FormSchema>, GetValueFormType extends TypeWithNullableDynamicKeys<FormSchema>>(zodSchema: FormSchema): (formKey: FormKey, options: SchemaFactoryOptions) => AbstractSchema<Form, GetValueFormType>;
 
@@ -163,44 +159,29 @@ type ZodTypeMap = {
 declare function isZodSchemaType<K extends keyof ZodTypeMap>(schema: unknown, expectedType: K): schema is ZodTypeMap[K];
 
 /**
- * Field-metadata write/read API for the Zod v3 adapter.
- *
- * Storage lives in the shared `field-meta-store` core — every entry
- * (`attaform/zod`, `attaform/zod-v3`, `attaform/zod-v4`) writes to and
- * reads from the same `WeakMap`s, so a payload registered via any
- * entry surfaces at lookup regardless of which adapter actually runs.
- *
- * Zod 3 has no `z.registry()` mechanism, so `fieldMeta` is the
- * shared registry-shaped object exposing `add` / `get` / `has` /
- * `remove`. The public `withMeta(schema, payload)` write API matches
- * `attaform/zod`'s so schema authoring reads identically across the
- * two adapters.
- *
- * **Registration patterns:** both styles work — register on whatever
- * schema reference you assign into the parent's shape, OR on the
- * inner schema before wrapping. The adapter's resolver tries the
- * walker-returned schema first, then falls back to the peeled
- * inner so either ordering hits:
- *
- *     // both equivalent — registry hits at lookup time
+ * Field-metadata write and read API for the Zod v3 adapter.
+ *
+ * Storage lives in the shared `core/field-meta-store`, where every entry
+ * (`attaform/zod`, `attaform/zod-v3`, `attaform/zod-v4`) reads and
+ * writes the same `WeakMap`s, so a payload registered through any of
+ * them surfaces at lookup whichever adapter runs.
+ *
+ * **Registration order does not matter.** Register on the schema
+ * reference assigned into the parent's shape, or on the inner schema
+ * before wrapping:
+ *
+ *     // equivalent; both hit at lookup time
  *     withMeta(z.string(), { label: 'Email' }).optional()
  *     withMeta(z.string().optional(), { label: 'Email' })
  *
- * The path walker returns the wrapper at terminal positions and
- * peels at intermediate descent. The two-stage lookup covers both
- * leaf and container registrations symmetrically.
+ * The path walker returns the wrapper at a terminal position and peels
+ * at intermediate descent, and the resolver tries the walker's schema
+ * before the peeled inner, so the two-stage lookup covers leaf and
+ * container registrations symmetrically.
  */
 
-/**
- * The shared registry every Attaform-aware Zod 3 schema can register
- * field metadata against. Backed by the cross-adapter store — a
- * payload registered here is visible to the v4 adapter and the
- * unified `attaform/zod` entry, and vice versa. Every `add` also
- * installs the path-walking resolver into the shared store's builder
- * slot, so the walk's bytes ride this module's import instead of the
- * adapter — a consumer that never registers metadata never ships the
- * walk.
- */
+/** The `add` / `get` / `has` / `remove` shape of `fieldMeta`, matching
+ *  Zod 4's `$ZodRegistry` closely enough to read the same either way. */
 type FieldMetaRegistryV3 = {
     /**
      * Register `payload` against `schema`. Returns the registry to
@@ -220,32 +201,45 @@ type FieldMetaRegistryV3 = {
      */
     remove(schema: z.ZodTypeAny): FieldMetaRegistryV3;
 };
+/**
+ * The shared registry an Attaform-aware Zod 3 schema registers field
+ * metadata against.
+ *
+ * ```ts
+ * import { fieldMeta } from 'attaform/zod-v3'
+ *
+ * const email = z.string().email()
+ * fieldMeta.add(email, { label: 'Email address' })
+ * ```
+ *
+ * It is backed by the cross-adapter store, so a payload registered here
+ * is visible to the v4 adapter and to the unified `attaform/zod` entry,
+ * and the reverse. Every `add` also installs the path-walking resolver
+ * into the shared store's builder slot, which is what makes the walk's
+ * bytes ride this module's import rather than the adapter: a consumer
+ * who never registers metadata never ships the walk.
+ */
 declare const fieldMeta: FieldMetaRegistryV3;
 /**
- * Attach `payload` to `schema` in the shared `fieldMeta` registry
- * and return a clone of `schema` (chainable, with the new metadata).
- * Cross-version with `attaform/zod`'s `withMeta()`.
- *
- * **Why clone, not mutate.** The shared store keys metadata on the
- * schema reference. Calling `withMeta` twice on the same instance
- * would overwrite (last-write-wins) — so a sub-schema reused at
- * multiple form paths (e.g. an address schema shared between pickup
- * and delivery) couldn't carry distinct metadata per path.
- *
- * `withMeta` sidesteps the footgun by reconstructing `schema` via
- * its constructor + `_def` — Zod 3 schemas don't expose `.clone()`,
- * but `new schema.constructor(schema._def)` is the equivalent. Each
- * call gets a fresh identity and a fresh registry slot. Existing
- * metadata on the original is merged through, so chaining
- * `withMeta` accumulates payload fields rather than replacing.
- *
- * Inner field schemas (e.g. an object's `.shape.city`) are shared
- * across clones — the def is held by reference — so leaf metadata
- * registers once and surfaces at every path.
- *
- * `schema.register()` does NOT exist on Zod 3 — `withMeta` is the
- * only fluent write API. Register on the inner schema before
- * wrapping; see the "Registration rule" note in this file's header.
+ * Attach `payload` to `schema` in the shared `fieldMeta` registry and
+ * return a chainable CLONE of `schema` carrying the new metadata. Zod 3
+ * has no `schema.register()`, so this is its only fluent write API, and
+ * it matches `attaform/zod`'s `withMeta()`.
+ *
+ * It clones rather than mutates because the store keys metadata on the
+ * schema reference: calling `withMeta` twice on one instance would
+ * overwrite last-write-wins, and a sub-schema reused at several paths,
+ * an address shared between pickup and delivery say, could then carry
+ * only one payload. Zod 3 exposes no `.clone()`, so the reconstruction
+ * goes through `new schema.constructor(schema._def)`. Each call gets a
+ * fresh identity and a fresh registry slot, and existing metadata merges
+ * through, so chaining accumulates payload fields rather than replacing
+ * them.
+ *
+ * An inner field schema, an object's `.shape.city` for instance, is
+ * shared across clones, the def being held by reference, so leaf
+ * metadata registers once and surfaces at every path. See this file's
+ * header for the two equivalent registration orderings.
  */
 declare function withMeta<S extends z.ZodTypeAny>(schema: S, payload: FieldMetaPayload): S;
 

package/dist/zod-v3.mjs

@@ -1,9 +1,9 @@
-export { i as isZodSchemaType, u as useForm, z as zodAdapter } from './shared/attaform.CJ8DpRGj.mjs';
-import { i as installingFieldMetaStore, g as getFieldMetaForSchema } from './shared/attaform.CUfrMK7t.mjs';
+export { i as isZodSchemaType, u as useForm, z as zodAdapter } from './shared/attaform.D_pt1gOj.mjs';
+import { i as installingFieldMetaStore, g as getFieldMetaForSchema } from './shared/attaform.DRsANMok.mjs';
 export { A as AttaformError, I as InvalidPathError, a as InvalidUseFormConfigError, O as OutsideSetupError, R as ROOT_PATH, b as ROOT_PATH_KEY, c as RegistryNotInstalledError, d as ReservedFormKeyError, S as SubmitErrorHandlerError, e as canonicalizePath, i as isPathPrefix, p as parseDottedPath } from './shared/attaform.CdZIEf7_.mjs';
-export { A as AttaformErrorCode, e as escapeForInlineScript, g as gate, i as injectForm, a as injectWizard, b as isUnset, l as lazy, u as unset, d as useRegister, f as useWizard } from './shared/attaform.DNJOWjQw.mjs';
+export { A as AttaformErrorCode, e as escapeForInlineScript, g as gate, i as injectForm, a as injectWizard, b as isUnset, l as lazy, u as unset, d as useRegister, f as useWizard } from './shared/attaform.BIWicztt.mjs';
 export { D as DEVTOOLS_WINDOW_KEY, c as createAttaform, a as createRegistry, g as getRegistryFromApp, h as hydrateAttaformState, k as kAttaformRegistry, r as renderAttaformState, u as useRegistry } from './shared/attaform.WiGdIqgx.mjs';
-export { a as assignKey, v as vRegister } from './shared/attaform.B3resMQ1.mjs';
+export { a as assignKey, v as vRegister } from './shared/attaform.D_f1WgYf.mjs';
 export { i as isRegisterValue } from './shared/attaform.KvlEedlF.mjs';
 
 const fieldMeta = installingFieldMetaStore;