attaform 0.27.3 → 0.27.5

package/dist/shared/{attaform.BIPSHY5U.d.ts → attaform.CzL2CZ8U.d.cts}

@@ -2501,9 +2501,16 @@ type RegisterValue<Value = unknown> = Readonly<{
      * but exposes no single inner control to register -- a composite widget,
      * or none found. The directive calls it on mount / unmount; distinct from
      * the SSR-only `markConnectedOptimistically`.
+     *
+     * `hostEl` is the host root element, recorded on connect as the field's
+     * focus-first-error anchor: a no-latch host registers no control, so it
+     * would otherwise be invisible to `focusFirstError` / `scrollToFirstError`
+     * (which walk the registered-element set). On an invalid submit the error
+     * walk resolves the host root to its first focusable descendant. The
+     * directive passes the same element on both edges.
      * @internal
      */
-    markHostConnected: (connected: boolean) => void;
+    markHostConnected: (connected: boolean, hostEl: HTMLElement) => void;
     /**
      * Mark this field focused (`true`) or blurred (`false`) for a `v-register`
      * component host with no single latched control -- a composite widget whose

package/dist/shared/{attaform.BIPSHY5U.d.cts → attaform.CzL2CZ8U.d.mts}

@@ -2501,9 +2501,16 @@ type RegisterValue<Value = unknown> = Readonly<{
      * but exposes no single inner control to register -- a composite widget,
      * or none found. The directive calls it on mount / unmount; distinct from
      * the SSR-only `markConnectedOptimistically`.
+     *
+     * `hostEl` is the host root element, recorded on connect as the field's
+     * focus-first-error anchor: a no-latch host registers no control, so it
+     * would otherwise be invisible to `focusFirstError` / `scrollToFirstError`
+     * (which walk the registered-element set). On an invalid submit the error
+     * walk resolves the host root to its first focusable descendant. The
+     * directive passes the same element on both edges.
      * @internal
      */
-    markHostConnected: (connected: boolean) => void;
+    markHostConnected: (connected: boolean, hostEl: HTMLElement) => void;
     /**
      * Mark this field focused (`true`) or blurred (`false`) for a `v-register`
      * component host with no single latched control -- a composite widget whose

package/dist/shared/{attaform.BIPSHY5U.d.mts → attaform.CzL2CZ8U.d.ts}

@@ -2501,9 +2501,16 @@ type RegisterValue<Value = unknown> = Readonly<{
      * but exposes no single inner control to register -- a composite widget,
      * or none found. The directive calls it on mount / unmount; distinct from
      * the SSR-only `markConnectedOptimistically`.
+     *
+     * `hostEl` is the host root element, recorded on connect as the field's
+     * focus-first-error anchor: a no-latch host registers no control, so it
+     * would otherwise be invisible to `focusFirstError` / `scrollToFirstError`
+     * (which walk the registered-element set). On an invalid submit the error
+     * walk resolves the host root to its first focusable descendant. The
+     * directive passes the same element on both edges.
      * @internal
      */
-    markHostConnected: (connected: boolean) => void;
+    markHostConnected: (connected: boolean, hostEl: HTMLElement) => void;
     /**
      * Mark this field focused (`true`) or blurred (`false`) for a `v-register`
      * component host with no single latched control -- a composite widget whose

package/dist/shared/{attaform.C925L0WA.d.mts → attaform.DYwyM5Cp.d.cts}

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { G as GenericForm, s as FlatPath, B as NestedType, F as FormKey, U as UseFormConfiguration, A as AbstractSchema, aq as AcceptableDefaults, ae as ValidateOnConfig, a as UseFormReturnType } from './attaform.BIPSHY5U.mjs';
+import { G as GenericForm, s as FlatPath, B as NestedType, F as FormKey, U as UseFormConfiguration, A as AbstractSchema, aq as AcceptableDefaults, ae as ValidateOnConfig, a as UseFormReturnType } from './attaform.CzL2CZ8U.cjs';
 
 /**
  * The Zod v4 schema roots `useForm` accepts. A fixed-shape

package/dist/shared/{attaform.DHQjaGMP.mjs → attaform.Dc1mx48r.mjs}

@@ -1,7 +1,7 @@
-import { a as InvalidUseFormConfigError } from './attaform.CgsQZdy1.mjs';
-import { u as useForm$2 } from './attaform.DuVCclwv.mjs';
-import { u as useForm$1 } from './attaform.DDIn4fv-.mjs';
-import { f as fieldMetaStore, g as getFieldMetaForSchema } from './attaform.BKxpBJVF.mjs';
+import { a as InvalidUseFormConfigError } from './attaform.nMaz2C5P.mjs';
+import { u as useForm$2 } from './attaform.Cg_8gFQ7.mjs';
+import { u as useForm$1 } from './attaform.Dkjh_F30.mjs';
+import { f as fieldMetaStore, g as getFieldMetaForSchema } from './attaform.CTiZ9Rrv.mjs';
 
 function isZodV4SchemaShape(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -39,4 +39,4 @@ function cloneSchema(schema) {
 }
 
 export { fieldMeta as f, useForm as u, withMeta as w };
-//# sourceMappingURL=attaform.DHQjaGMP.mjs.map
+//# sourceMappingURL=attaform.Dc1mx48r.mjs.map

package/dist/shared/{attaform.DHQjaGMP.mjs.map → attaform.Dc1mx48r.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"attaform.DHQjaGMP.mjs","sources":["../../src/runtime/core/zod-shape.ts","../../src/runtime/adapters/unified/use-form.ts","../../src/runtime/adapters/unified/field-meta.ts"],"sourcesContent":["/**\n * Shape detectors for Zod schemas. Used by the unified `attaform/zod`\n * entry's runtime dispatch (`runtime/adapters/unified/use-form.ts`)\n * to route to the v3 or v4 adapter based on the schema's runtime\n * shape. Mirrors the discrimination already used by the v4\n * introspection helper (`adapters/zod-v4/introspect.ts`'s\n * `assertZodVersion`, which reads `def.type`) and the v3 wrapper's\n * legitimate-input branch (`composables/use-form.ts`'s `isZodType`,\n * which reads `_def`).\n *\n * Why this discriminator and not `_zod` / `_def`:\n * - Zod v4 retained `_def` for backward compat — reading `_def` alone\n *   misclassifies v4 schemas as v3.\n * - Zod v4's stable shape is `def.type: string` (lowercase tag like\n *   `'object'`); Zod v3's is `_def.typeName: string` (capitalised tag\n *   like `'ZodObject'`). Both are checked structurally so consumers\n *   who alias one Zod major to a non-standard import path still work.\n */\n\ninterface ZodV4Shape {\n  def: { type: unknown }\n}\n\ninterface ZodV3Shape {\n  _def: { typeName: unknown }\n}\n\n/**\n * Returns true when `value` looks like a Zod schema of either major\n * version. Convenience wrapper around the v3 / v4 detectors.\n */\nexport function isZodSchemaShape(value: unknown): boolean {\n  return isZodV4SchemaShape(value) || isZodV3SchemaShape(value)\n}\n\n/**\n * Returns true when `value` looks like a Zod v4 schema (has\n * `def.type: string`). Used by the unified entry's runtime-dispatch\n * to route to the v4 adapter.\n */\nexport function isZodV4SchemaShape(value: unknown): value is ZodV4Shape {\n  if (typeof value !== 'object' || value === null) return false\n  const def = (value as { def?: unknown }).def\n  if (typeof def !== 'object' || def === null) return false\n  return typeof (def as { type?: unknown }).type === 'string'\n}\n\n/**\n * Returns true when `value` looks like a Zod v3 schema (has\n * `_def.typeName: string`). Kept distinct from `isZodV4SchemaShape`\n * because some v4 schemas also expose `_def` for backward compat —\n * the v4 detector wins first in `isZodSchemaShape`.\n */\nexport function isZodV3SchemaShape(value: unknown): value is ZodV3Shape {\n  if (typeof value !== 'object' || value === null) return false\n  const def = (value as { _def?: unknown })._def\n  if (typeof def !== 'object' || def === null) return false\n  return typeof (def as { typeName?: unknown }).typeName === 'string'\n}\n","/**\n * Unified `useForm` for the `attaform/zod` entry. Runtime-dispatches\n * on schema shape: a Zod v4 schema (`def.type` truthy) routes to the\n * v4 adapter; a Zod v3 schema (or any other `AbstractSchema`) routes\n * to the v3 wrapper, which already accepts both Zod v3 input and\n * `AbstractSchema` directly via its built-in shape branch.\n *\n * Type-level dispatch happens via TWO typed overloads — v4 first, v3\n * second — plus an untyped impl. Each overload mirrors the matching\n * direct adapter's signature exactly, so a v4-schema call site pays\n * the same per-call depth cost as importing from `attaform/zod-v4`\n * directly. Overload resolution at concrete call sites commits to one\n * overload immediately on argument shape — no type-level dispatch tax.\n *\n * Tests and other call sites that need the equivalent of\n * `typeof useForm<X>` should reach for the `UseFormReturn<X>` /\n * `UseFormConfig<X>` helpers in `types-api.ts` — instantiation\n * expressions on overloaded functions follow brittle resolution rules,\n * and the helper types give a deterministic projection.\n *\n * This module is the FALLBACK path. Vite consumers see the\n * `attaform/vite` plugin's `resolveId` hook rewrite `attaform/zod`\n * imports to either `attaform/zod-v3` or `attaform/zod-v4` at build\n * time — in that case this dispatch never runs and the consumer\n * bundle ships only the matching adapter. Other bundlers (and\n * non-bundled ESM consumption) hit this dispatch instead, paying a\n * modest size cost for the convenience of a single hello-world import.\n *\n * Power users who want a guaranteed lean bundle on non-Vite tooling\n * can import directly from `attaform/zod-v3` or `attaform/zod-v4` —\n * those subpaths are never rewritten and never load the other\n * adapter.\n */\nimport { InvalidUseFormConfigError } from '../../core/errors'\nimport { isZodV4SchemaShape } from '../../core/zod-shape'\nimport type { ZodV4Internals } from './types-zod-major'\nimport { useForm as useFormV3 } from '../../composables/use-form'\nimport { useForm as useFormV4 } from '../zod-v4'\nimport type {\n  AbstractSchema,\n  FormKey,\n  ValidateOnConfig,\n  UseFormReturnType,\n  UseFormConfiguration,\n} from '../../types/types-api'\nimport type { AcceptableDefaults } from '../../types/types-core'\nimport type { SupportedRootSchema as SupportedRootSchemaV4 } from '../zod-v4/types-root'\nimport type { SupportedRootSchema as SupportedRootSchemaV3 } from '../zod-v3/types-root'\nimport type {\n  V3FormOf,\n  V3OutOf,\n  V3ReadOf,\n  V3SchemaInput,\n  V4FormOf,\n  V4OutOf,\n  V4ReadOf,\n  V4SchemaInput,\n} from './types-projections'\n\n/**\n * Create a form bound to a Zod v4 schema.\n *\n * ```ts\n * import { useForm } from 'attaform/zod'\n * import { z } from 'zod'\n *\n * const form = useForm({\n *   schema: z.object({\n *     username: z.string().min(2, 'At least 2 characters'),\n *     password: z.string().min(8, 'At least 8 characters'),\n *   }),\n * })\n * ```\n *\n * The constraint intersects `ZodV4Internals` (the v4-only `_zod`\n * brand) so a v3 schema can't bind this overload even when `z`\n * resolves to v3 in a single-major consumer install; v3 schemas fall\n * through to the v3 overload below. See `types-zod-major.ts`.\n */\nexport function useForm<\n  Schema extends SupportedRootSchemaV4 & ZodV4Internals,\n  K extends FormKey = FormKey,\n>(\n  configuration: Omit<\n    UseFormConfiguration<\n      V4FormOf<Schema>,\n      V4OutOf<Schema>,\n      AbstractSchema<V4FormOf<Schema>, V4OutOf<Schema>>,\n      // `defaultValues` is Omitted below and re-supplied via the\n      // `AcceptableDefaults` intersection, so this `DefaultValues` slot is\n      // inert. `never` keeps it from re-instantiating the deep\n      // `DefaultValuesInput` cascade here — that redundant instantiation,\n      // across both overloads at a concrete call site, tips the bundled\n      // `.d.ts` into TS2589.\n      never,\n      K\n    >,\n    'schema' | 'validateOn' | 'debounceMs' | 'defaultValues'\n  > & {\n    schema: Schema\n    // #422: the `AcceptableDefaults` slot adds the schema's own input\n    // (`V4SchemaInput<Schema>`) as a reflexive escape arm so a generic form\n    // wrapper forwarding `defaultValues` does not trip TS2589 / TS2769.\n    // The arm is redundant at concrete call sites (a schema's input is a\n    // subset of its `DefaultValuesInput`), so concrete checking is\n    // unchanged. The return type never references the slot, so field\n    // inference is preserved through the wrapper. See `AcceptableDefaults`.\n    defaultValues?: AcceptableDefaults<V4FormOf<Schema>, V4SchemaInput<Schema>>\n  } & ValidateOnConfig\n): UseFormReturnType<V4FormOf<Schema>, V4OutOf<Schema>, V4ReadOf<Schema>, K>\n/**\n * Create a form bound to a Zod v3 schema.\n *\n * ```ts\n * import { useForm } from 'attaform/zod'\n * import { z } from 'zod-v3'\n *\n * const form = useForm({\n *   schema: z.object({\n *     username: z.string().min(2, 'At least 2 characters'),\n *     password: z.string().min(8, 'At least 8 characters'),\n *   }),\n * })\n * ```\n *\n * v3 schemas match this overload; v4 schemas hit the v4 overload\n * above first and never reach here.\n */\nexport function useForm<Schema extends SupportedRootSchemaV3, K extends FormKey = FormKey>(\n  configuration: Omit<\n    UseFormConfiguration<\n      V3FormOf<Schema>,\n      V3OutOf<Schema>,\n      AbstractSchema<V3FormOf<Schema>, V3OutOf<Schema>>,\n      // Inert `DefaultValues` slot — see the v4 overload above.\n      never,\n      K\n    >,\n    'schema' | 'validateOn' | 'debounceMs' | 'defaultValues'\n  > & {\n    schema: Schema\n    // #422 — see the v4 overload above for the escape-arm rationale.\n    defaultValues?: AcceptableDefaults<V3FormOf<Schema>, V3SchemaInput<Schema>>\n  } & ValidateOnConfig\n): UseFormReturnType<V3FormOf<Schema>, V3OutOf<Schema>, V3ReadOf<Schema>, K>\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function useForm(configuration: any): any {\n  if (\n    configuration === undefined ||\n    configuration === null ||\n    (configuration as { schema?: unknown }).schema === undefined\n  ) {\n    throw new InvalidUseFormConfigError()\n  }\n  const { schema } = configuration as { schema: unknown }\n  if (isZodV4SchemaShape(schema)) {\n    return useFormV4(configuration as Parameters<typeof useFormV4>[0])\n  }\n  return useFormV3(configuration as Parameters<typeof useFormV3>[0])\n}\n","/**\n * Field-metadata write/read API for the unified `attaform/zod` entry.\n *\n * Storage is shared with both adapters via `field-meta-store` — a\n * payload written here is visible to whichever adapter the unified\n * `useForm` dispatches to at runtime, regardless of Zod major. No\n * `zod` runtime import; the type-only `import type` is erased at\n * build, so `attaform/zod` carries no `z.registry` reference even\n * when consumed by a Zod 3 project without the Vite plugin alias.\n *\n * The native v4 chain `schema.register(fieldMeta, payload)` continues\n * to work — Zod 4's `.register()` only calls `.add(this, payload)`\n * structurally, satisfied by the shared store.\n */\nimport type { z } from 'zod'\nimport type { FieldMetaPayload } from '../../core/field-meta'\nimport { fieldMetaStore, getFieldMetaForSchema } from '../../core/field-meta-store'\n\n// Zod v4's `$ZodRegistry` class isn't surfaced under the `z` namespace\n// of the classic external entry, but `z.registry()` returns one — so\n// `ReturnType<typeof z.registry<T>>` resolves to the registry type\n// without needing a direct import. The `import type` keeps the\n// reference type-only; nothing about `z.registry` lands in the bundle.\ntype ZodFieldMetaRegistry = ReturnType<typeof z.registry<FieldMetaPayload>>\n\n/**\n * The shared registry every Attaform-aware Zod schema can register\n * field metadata against, regardless of major. Same instance the v3\n * and v4 adapter entries expose — write in one place, read from\n * any.\n *\n * Cast to Zod 4's `$ZodRegistry<FieldMetaPayload>` so the native\n * `schema.register(fieldMeta, payload)` chain type-checks for v4\n * users; the runtime call only needs `.add` structurally, which the\n * shared store provides.\n */\nexport const fieldMeta = fieldMetaStore as unknown as ZodFieldMetaRegistry\n\n/**\n * Attach `payload` to `schema` in the shared registry and return a\n * clone of `schema` so each call gets its own identity (the registry\n * keys on schema reference, so cloning prevents last-write-wins\n * collisions for sub-schemas reused at multiple paths).\n *\n * Works on both Zod 3 and Zod 4 schemas — branches on the runtime\n * shape of the schema:\n * - Zod 4 schemas expose a public `.clone()` method; we call it.\n * - Zod 3 schemas don't, so we reconstruct via\n *   `new schema.constructor(schema._def)`.\n *\n * Both forms produce a fresh schema with the same effective\n * structure, so the registry slot is unique to this call site.\n */\nexport function withMeta<S>(schema: S, payload: FieldMetaPayload): S {\n  const target = schema as object\n  const existing = getFieldMetaForSchema(target) ?? {}\n  const cloned = cloneSchema(schema)\n  fieldMetaStore.add(cloned as object, { ...existing, ...payload })\n  return cloned\n}\n\nfunction cloneSchema<S>(schema: S): S {\n  const candidate = schema as { clone?: unknown; constructor: unknown; _def: unknown }\n  if (typeof candidate.clone === 'function') {\n    return (candidate.clone as () => S)()\n  }\n  // Zod 3 path: reconstruct via constructor + _def (no public\n  // `.clone()` on v3).\n  const Ctor = candidate.constructor as new (def: unknown) => S\n  return new Ctor(candidate._def)\n}\n"],"names":["useFormV4","useFormV3"],"mappings":";;;;;AAwCO,SAAS,mBAAmB,KAAA,EAAqC;AACtE,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,KAAA,KAAU,MAAM,OAAO,KAAA;AACxD,EAAA,MAAM,MAAO,KAAA,CAA4B,GAAA;AACzC,EAAA,IAAI,OAAO,GAAA,KAAQ,QAAA,IAAY,GAAA,KAAQ,MAAM,OAAO,KAAA;AACpD,EAAA,OAAO,OAAQ,IAA2B,IAAA,KAAS,QAAA;AACrD;;ACqGO,SAAS,QAAQ,aAAA,EAAyB;AAC/C,EAAA,IACE,kBAAkB,MAAA,IAClB,aAAA,KAAkB,IAAA,IACjB,aAAA,CAAuC,WAAW,MAAA,EACnD;AACA,IAAA,MAAM,IAAI,yBAAA,EAA0B;AAAA,EACtC;AACA,EAAA,MAAM,EAAE,QAAO,GAAI,aAAA;AACnB,EAAA,IAAI,kBAAA,CAAmB,MAAM,CAAA,EAAG;AAC9B,IAAA,OAAOA,UAAU,aAAgD,CAAA;AAAA,EACnE;AACA,EAAA,OAAOC,UAAU,aAAgD,CAAA;AACnE;;AC3HO,MAAM,SAAA,GAAY;AAiBlB,SAAS,QAAA,CAAY,QAAW,OAAA,EAA8B;AACnE,EAAA,MAAM,MAAA,GAAS,MAAA;AACf,EAAA,MAAM,QAAA,GAAW,qBAAA,CAAsB,MAAM,CAAA,IAAK,EAAC;AACnD,EAAA,MAAM,MAAA,GAAS,YAAY,MAAM,CAAA;AACjC,EAAA,cAAA,CAAe,IAAI,MAAA,EAAkB,EAAE,GAAG,QAAA,EAAU,GAAG,SAAS,CAAA;AAChE,EAAA,OAAO,MAAA;AACT;AAEA,SAAS,YAAe,MAAA,EAAc;AACpC,EAAA,MAAM,SAAA,GAAY,MAAA;AAClB,EAAA,IAAI,OAAO,SAAA,CAAU,KAAA,KAAU,UAAA,EAAY;AACzC,IAAA,OAAQ,UAAU,KAAA,EAAkB;AAAA,EACtC;AAGA,EAAA,MAAM,OAAO,SAAA,CAAU,WAAA;AACvB,EAAA,OAAO,IAAI,IAAA,CAAK,SAAA,CAAU,IAAI,CAAA;AAChC;;;;"}
+{"version":3,"file":"attaform.Dc1mx48r.mjs","sources":["../../src/runtime/core/zod-shape.ts","../../src/runtime/adapters/unified/use-form.ts","../../src/runtime/adapters/unified/field-meta.ts"],"sourcesContent":["/**\n * Shape detectors for Zod schemas. Used by the unified `attaform/zod`\n * entry's runtime dispatch (`runtime/adapters/unified/use-form.ts`)\n * to route to the v3 or v4 adapter based on the schema's runtime\n * shape. Mirrors the discrimination already used by the v4\n * introspection helper (`adapters/zod-v4/introspect.ts`'s\n * `assertZodVersion`, which reads `def.type`) and the v3 wrapper's\n * legitimate-input branch (`composables/use-form.ts`'s `isZodType`,\n * which reads `_def`).\n *\n * Why this discriminator and not `_zod` / `_def`:\n * - Zod v4 retained `_def` for backward compat — reading `_def` alone\n *   misclassifies v4 schemas as v3.\n * - Zod v4's stable shape is `def.type: string` (lowercase tag like\n *   `'object'`); Zod v3's is `_def.typeName: string` (capitalised tag\n *   like `'ZodObject'`). Both are checked structurally so consumers\n *   who alias one Zod major to a non-standard import path still work.\n */\n\ninterface ZodV4Shape {\n  def: { type: unknown }\n}\n\ninterface ZodV3Shape {\n  _def: { typeName: unknown }\n}\n\n/**\n * Returns true when `value` looks like a Zod schema of either major\n * version. Convenience wrapper around the v3 / v4 detectors.\n */\nexport function isZodSchemaShape(value: unknown): boolean {\n  return isZodV4SchemaShape(value) || isZodV3SchemaShape(value)\n}\n\n/**\n * Returns true when `value` looks like a Zod v4 schema (has\n * `def.type: string`). Used by the unified entry's runtime-dispatch\n * to route to the v4 adapter.\n */\nexport function isZodV4SchemaShape(value: unknown): value is ZodV4Shape {\n  if (typeof value !== 'object' || value === null) return false\n  const def = (value as { def?: unknown }).def\n  if (typeof def !== 'object' || def === null) return false\n  return typeof (def as { type?: unknown }).type === 'string'\n}\n\n/**\n * Returns true when `value` looks like a Zod v3 schema (has\n * `_def.typeName: string`). Kept distinct from `isZodV4SchemaShape`\n * because some v4 schemas also expose `_def` for backward compat —\n * the v4 detector wins first in `isZodSchemaShape`.\n */\nexport function isZodV3SchemaShape(value: unknown): value is ZodV3Shape {\n  if (typeof value !== 'object' || value === null) return false\n  const def = (value as { _def?: unknown })._def\n  if (typeof def !== 'object' || def === null) return false\n  return typeof (def as { typeName?: unknown }).typeName === 'string'\n}\n","/**\n * Unified `useForm` for the `attaform/zod` entry. Runtime-dispatches\n * on schema shape: a Zod v4 schema (`def.type` truthy) routes to the\n * v4 adapter; a Zod v3 schema (or any other `AbstractSchema`) routes\n * to the v3 wrapper, which already accepts both Zod v3 input and\n * `AbstractSchema` directly via its built-in shape branch.\n *\n * Type-level dispatch happens via TWO typed overloads — v4 first, v3\n * second — plus an untyped impl. Each overload mirrors the matching\n * direct adapter's signature exactly, so a v4-schema call site pays\n * the same per-call depth cost as importing from `attaform/zod-v4`\n * directly. Overload resolution at concrete call sites commits to one\n * overload immediately on argument shape — no type-level dispatch tax.\n *\n * Tests and other call sites that need the equivalent of\n * `typeof useForm<X>` should reach for the `UseFormReturn<X>` /\n * `UseFormConfig<X>` helpers in `types-api.ts` — instantiation\n * expressions on overloaded functions follow brittle resolution rules,\n * and the helper types give a deterministic projection.\n *\n * This module is the FALLBACK path. Vite consumers see the\n * `attaform/vite` plugin's `resolveId` hook rewrite `attaform/zod`\n * imports to either `attaform/zod-v3` or `attaform/zod-v4` at build\n * time — in that case this dispatch never runs and the consumer\n * bundle ships only the matching adapter. Other bundlers (and\n * non-bundled ESM consumption) hit this dispatch instead, paying a\n * modest size cost for the convenience of a single hello-world import.\n *\n * Power users who want a guaranteed lean bundle on non-Vite tooling\n * can import directly from `attaform/zod-v3` or `attaform/zod-v4` —\n * those subpaths are never rewritten and never load the other\n * adapter.\n */\nimport { InvalidUseFormConfigError } from '../../core/errors'\nimport { isZodV4SchemaShape } from '../../core/zod-shape'\nimport type { ZodV4Internals } from './types-zod-major'\nimport { useForm as useFormV3 } from '../../composables/use-form'\nimport { useForm as useFormV4 } from '../zod-v4'\nimport type {\n  AbstractSchema,\n  FormKey,\n  ValidateOnConfig,\n  UseFormReturnType,\n  UseFormConfiguration,\n} from '../../types/types-api'\nimport type { AcceptableDefaults } from '../../types/types-core'\nimport type { SupportedRootSchema as SupportedRootSchemaV4 } from '../zod-v4/types-root'\nimport type { SupportedRootSchema as SupportedRootSchemaV3 } from '../zod-v3/types-root'\nimport type {\n  V3FormOf,\n  V3OutOf,\n  V3ReadOf,\n  V3SchemaInput,\n  V4FormOf,\n  V4OutOf,\n  V4ReadOf,\n  V4SchemaInput,\n} from './types-projections'\n\n/**\n * Create a form bound to a Zod v4 schema.\n *\n * ```ts\n * import { useForm } from 'attaform/zod'\n * import { z } from 'zod'\n *\n * const form = useForm({\n *   schema: z.object({\n *     username: z.string().min(2, 'At least 2 characters'),\n *     password: z.string().min(8, 'At least 8 characters'),\n *   }),\n * })\n * ```\n *\n * The constraint intersects `ZodV4Internals` (the v4-only `_zod`\n * brand) so a v3 schema can't bind this overload even when `z`\n * resolves to v3 in a single-major consumer install; v3 schemas fall\n * through to the v3 overload below. See `types-zod-major.ts`.\n */\nexport function useForm<\n  Schema extends SupportedRootSchemaV4 & ZodV4Internals,\n  K extends FormKey = FormKey,\n>(\n  configuration: Omit<\n    UseFormConfiguration<\n      V4FormOf<Schema>,\n      V4OutOf<Schema>,\n      AbstractSchema<V4FormOf<Schema>, V4OutOf<Schema>>,\n      // `defaultValues` is Omitted below and re-supplied via the\n      // `AcceptableDefaults` intersection, so this `DefaultValues` slot is\n      // inert. `never` keeps it from re-instantiating the deep\n      // `DefaultValuesInput` cascade here — that redundant instantiation,\n      // across both overloads at a concrete call site, tips the bundled\n      // `.d.ts` into TS2589.\n      never,\n      K\n    >,\n    'schema' | 'validateOn' | 'debounceMs' | 'defaultValues'\n  > & {\n    schema: Schema\n    // #422: the `AcceptableDefaults` slot adds the schema's own input\n    // (`V4SchemaInput<Schema>`) as a reflexive escape arm so a generic form\n    // wrapper forwarding `defaultValues` does not trip TS2589 / TS2769.\n    // The arm is redundant at concrete call sites (a schema's input is a\n    // subset of its `DefaultValuesInput`), so concrete checking is\n    // unchanged. The return type never references the slot, so field\n    // inference is preserved through the wrapper. See `AcceptableDefaults`.\n    defaultValues?: AcceptableDefaults<V4FormOf<Schema>, V4SchemaInput<Schema>>\n  } & ValidateOnConfig\n): UseFormReturnType<V4FormOf<Schema>, V4OutOf<Schema>, V4ReadOf<Schema>, K>\n/**\n * Create a form bound to a Zod v3 schema.\n *\n * ```ts\n * import { useForm } from 'attaform/zod'\n * import { z } from 'zod-v3'\n *\n * const form = useForm({\n *   schema: z.object({\n *     username: z.string().min(2, 'At least 2 characters'),\n *     password: z.string().min(8, 'At least 8 characters'),\n *   }),\n * })\n * ```\n *\n * v3 schemas match this overload; v4 schemas hit the v4 overload\n * above first and never reach here.\n */\nexport function useForm<Schema extends SupportedRootSchemaV3, K extends FormKey = FormKey>(\n  configuration: Omit<\n    UseFormConfiguration<\n      V3FormOf<Schema>,\n      V3OutOf<Schema>,\n      AbstractSchema<V3FormOf<Schema>, V3OutOf<Schema>>,\n      // Inert `DefaultValues` slot — see the v4 overload above.\n      never,\n      K\n    >,\n    'schema' | 'validateOn' | 'debounceMs' | 'defaultValues'\n  > & {\n    schema: Schema\n    // #422 — see the v4 overload above for the escape-arm rationale.\n    defaultValues?: AcceptableDefaults<V3FormOf<Schema>, V3SchemaInput<Schema>>\n  } & ValidateOnConfig\n): UseFormReturnType<V3FormOf<Schema>, V3OutOf<Schema>, V3ReadOf<Schema>, K>\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function useForm(configuration: any): any {\n  if (\n    configuration === undefined ||\n    configuration === null ||\n    (configuration as { schema?: unknown }).schema === undefined\n  ) {\n    throw new InvalidUseFormConfigError()\n  }\n  const { schema } = configuration as { schema: unknown }\n  if (isZodV4SchemaShape(schema)) {\n    return useFormV4(configuration as Parameters<typeof useFormV4>[0])\n  }\n  return useFormV3(configuration as Parameters<typeof useFormV3>[0])\n}\n","/**\n * Field-metadata write/read API for the unified `attaform/zod` entry.\n *\n * Storage is shared with both adapters via `field-meta-store` — a\n * payload written here is visible to whichever adapter the unified\n * `useForm` dispatches to at runtime, regardless of Zod major. No\n * `zod` runtime import; the type-only `import type` is erased at\n * build, so `attaform/zod` carries no `z.registry` reference even\n * when consumed by a Zod 3 project without the Vite plugin alias.\n *\n * The native v4 chain `schema.register(fieldMeta, payload)` continues\n * to work — Zod 4's `.register()` only calls `.add(this, payload)`\n * structurally, satisfied by the shared store.\n */\nimport type { z } from 'zod'\nimport type { FieldMetaPayload } from '../../core/field-meta'\nimport { fieldMetaStore, getFieldMetaForSchema } from '../../core/field-meta-store'\n\n// Zod v4's `$ZodRegistry` class isn't surfaced under the `z` namespace\n// of the classic external entry, but `z.registry()` returns one — so\n// `ReturnType<typeof z.registry<T>>` resolves to the registry type\n// without needing a direct import. The `import type` keeps the\n// reference type-only; nothing about `z.registry` lands in the bundle.\ntype ZodFieldMetaRegistry = ReturnType<typeof z.registry<FieldMetaPayload>>\n\n/**\n * The shared registry every Attaform-aware Zod schema can register\n * field metadata against, regardless of major. Same instance the v3\n * and v4 adapter entries expose — write in one place, read from\n * any.\n *\n * Cast to Zod 4's `$ZodRegistry<FieldMetaPayload>` so the native\n * `schema.register(fieldMeta, payload)` chain type-checks for v4\n * users; the runtime call only needs `.add` structurally, which the\n * shared store provides.\n */\nexport const fieldMeta = fieldMetaStore as unknown as ZodFieldMetaRegistry\n\n/**\n * Attach `payload` to `schema` in the shared registry and return a\n * clone of `schema` so each call gets its own identity (the registry\n * keys on schema reference, so cloning prevents last-write-wins\n * collisions for sub-schemas reused at multiple paths).\n *\n * Works on both Zod 3 and Zod 4 schemas — branches on the runtime\n * shape of the schema:\n * - Zod 4 schemas expose a public `.clone()` method; we call it.\n * - Zod 3 schemas don't, so we reconstruct via\n *   `new schema.constructor(schema._def)`.\n *\n * Both forms produce a fresh schema with the same effective\n * structure, so the registry slot is unique to this call site.\n */\nexport function withMeta<S>(schema: S, payload: FieldMetaPayload): S {\n  const target = schema as object\n  const existing = getFieldMetaForSchema(target) ?? {}\n  const cloned = cloneSchema(schema)\n  fieldMetaStore.add(cloned as object, { ...existing, ...payload })\n  return cloned\n}\n\nfunction cloneSchema<S>(schema: S): S {\n  const candidate = schema as { clone?: unknown; constructor: unknown; _def: unknown }\n  if (typeof candidate.clone === 'function') {\n    return (candidate.clone as () => S)()\n  }\n  // Zod 3 path: reconstruct via constructor + _def (no public\n  // `.clone()` on v3).\n  const Ctor = candidate.constructor as new (def: unknown) => S\n  return new Ctor(candidate._def)\n}\n"],"names":["useFormV4","useFormV3"],"mappings":";;;;;AAwCO,SAAS,mBAAmB,KAAA,EAAqC;AACtE,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,KAAA,KAAU,MAAM,OAAO,KAAA;AACxD,EAAA,MAAM,MAAO,KAAA,CAA4B,GAAA;AACzC,EAAA,IAAI,OAAO,GAAA,KAAQ,QAAA,IAAY,GAAA,KAAQ,MAAM,OAAO,KAAA;AACpD,EAAA,OAAO,OAAQ,IAA2B,IAAA,KAAS,QAAA;AACrD;;ACqGO,SAAS,QAAQ,aAAA,EAAyB;AAC/C,EAAA,IACE,kBAAkB,MAAA,IAClB,aAAA,KAAkB,IAAA,IACjB,aAAA,CAAuC,WAAW,MAAA,EACnD;AACA,IAAA,MAAM,IAAI,yBAAA,EAA0B;AAAA,EACtC;AACA,EAAA,MAAM,EAAE,QAAO,GAAI,aAAA;AACnB,EAAA,IAAI,kBAAA,CAAmB,MAAM,CAAA,EAAG;AAC9B,IAAA,OAAOA,UAAU,aAAgD,CAAA;AAAA,EACnE;AACA,EAAA,OAAOC,UAAU,aAAgD,CAAA;AACnE;;AC3HO,MAAM,SAAA,GAAY;AAiBlB,SAAS,QAAA,CAAY,QAAW,OAAA,EAA8B;AACnE,EAAA,MAAM,MAAA,GAAS,MAAA;AACf,EAAA,MAAM,QAAA,GAAW,qBAAA,CAAsB,MAAM,CAAA,IAAK,EAAC;AACnD,EAAA,MAAM,MAAA,GAAS,YAAY,MAAM,CAAA;AACjC,EAAA,cAAA,CAAe,IAAI,MAAA,EAAkB,EAAE,GAAG,QAAA,EAAU,GAAG,SAAS,CAAA;AAChE,EAAA,OAAO,MAAA;AACT;AAEA,SAAS,YAAe,MAAA,EAAc;AACpC,EAAA,MAAM,SAAA,GAAY,MAAA;AAClB,EAAA,IAAI,OAAO,SAAA,CAAU,KAAA,KAAU,UAAA,EAAY;AACzC,IAAA,OAAQ,UAAU,KAAA,EAAkB;AAAA,EACtC;AAGA,EAAA,MAAM,OAAO,SAAA,CAAU,WAAA;AACvB,EAAA,OAAO,IAAI,IAAA,CAAK,SAAA,CAAU,IAAI,CAAA;AAChC;;;;"}

package/dist/shared/{attaform.gqOCvpSB.d.ts → attaform.DcFDQVpa.d.ts}

@@ -1,4 +1,4 @@
-import { G as GenericForm, F as FormKey, a as UseFormReturnType, a4 as RegisterValue, T as PathKey, k as DisplayCtx, w as GetDisplayState, l as DisplayMachine, S as Path, a9 as SlimPrimitiveKind, C as CoercionEntry, e as CoercionRegistry, af as ValidationError, A as AbstractSchema, aj as WriteMeta, h as DeepPartial, ak as WriteShape, as as TransformAbortHolder, ad as ValidateOn, d as AttaformDefaults, at as RegisterModelDynamicCustomDirective } from './attaform.BIPSHY5U.js';
+import { G as GenericForm, F as FormKey, a as UseFormReturnType, a4 as RegisterValue, T as PathKey, k as DisplayCtx, w as GetDisplayState, l as DisplayMachine, S as Path, a9 as SlimPrimitiveKind, C as CoercionEntry, e as CoercionRegistry, af as ValidationError, A as AbstractSchema, aj as WriteMeta, h as DeepPartial, ak as WriteShape, as as TransformAbortHolder, ad as ValidateOn, d as AttaformDefaults, at as RegisterModelDynamicCustomDirective } from './attaform.CzL2CZ8U.js';
 import { Ref, ComputedRef, App, InjectionKey, Plugin } from 'vue';
 
 /**
@@ -773,8 +773,14 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * (a composite widget, or none found). The directive calls it on mount
      * (`true`) and unmount (`false`). Distinct from the SSR-only
      * `markConnectedOptimistically`; idempotent on the leading edge.
+     *
+     * `hostEl` (the host root) is recorded on connect as this path's
+     * focus-first-error anchor, scoped to `formInstanceId` the same way a
+     * registered control is. A no-latch host enters no `elements` record, so
+     * without this it is absent from `getFirstErrorElement`'s walk; the anchor
+     * lets that walk resolve a focus target from the host subtree.
      */
-    markHostConnected(path: Path, connected: boolean): void;
+    markHostConnected(path: Path, connected: boolean, hostEl: HTMLElement, formInstanceId: string): void;
     /**
      * Leaf-only pristine check. `originals` is populated via
      * `diffAndApply`'s `added` patches, which fire only on primitive
@@ -1036,9 +1042,9 @@ type AnyForm = {
  *  - `gate`: this step's own role as a hard prerequisite. `null` when the
  *    step is not a `gate()`; `'uncleared'` while its member form is
  *    unconfirmed (so it seals every later step); `'cleared'` once
- *    confirmed by a clean member submit or a seeded-valid form gate at
- *    mount. Reflects the live compiled shape, so a conditional `gate()`
- *    that a function slot drops resolves to `null`.
+ *    confirmed by a clean member submit or seeded cleared via
+ *    `defaultStatuses`. Reflects the live compiled shape, so a conditional
+ *    `gate()` that a function slot drops resolves to `null`.
  *
  * Noop forms generated for string slots surface as default-valid
  * (`{ valid: true, dirty: false, submitted: false, errorCount: 0, locked: false, gate: null }`),
@@ -1054,12 +1060,27 @@ type FormStatus = {
     readonly gate: 'cleared' | 'uncleared' | null;
 };
 /**
- * Seed shape accepted by `useWizard({ defaultStatuses })`. Mirrors
- * `FormStatus` minus its two live-computed flags, `locked` and `gate`:
- * both are derived from the wizard's gates and overlaid on every status
- * read, so a seed never carries them (a seeded value would be ignored).
- */
-type FormStatusSeed = Omit<FormStatus, 'locked' | 'gate'>;
+ * Seed shape accepted by `useWizard({ defaultStatuses })`. Every field is
+ * optional; an omitted meta field falls back to the pending sentinel on
+ * read.
+ *
+ * `locked` is never accepted: it is purely live-derived (sealed behind an
+ * earlier uncleared gate) and overlaid on every status read, so a seeded
+ * value would be ignored.
+ *
+ * `gate` is a WRITE-only seed, not a status field echoed back on read. A
+ * seed of `'cleared'` latches the gate's cleared state once at construction
+ * (an SSR restore of a confirmed prerequisite); the live `gate` overlay
+ * then owns the read. `'uncleared'` is the default and seeds nothing. Only
+ * a step that compiles to a `gate()` honors it — other keys ignore it.
+ */
+type FormStatusSeed = {
+    readonly valid?: boolean;
+    readonly dirty?: boolean;
+    readonly submitted?: boolean;
+    readonly errorCount?: number;
+    readonly gate?: 'cleared' | 'uncleared';
+};
 /**
  * Flat error shape returned per form by `wizard.allErrors[key]`. Each
  * entry carries the formKey + path tuple so consumers can route to the
@@ -1314,12 +1335,20 @@ type WizardOptions = {
      * Status resolution priority per form:
      *   1. `store.defaultsResolved === true` → derive from `form.meta`
      *   2. else noop form → built-in always-valid status
-     *   3. else seed value for this key → frozen seed
+     *   3. else seed value for this key → seed over the pending sentinel
      *   4. else → pending sentinel
      *
-     * The `locked` flag is never seeded: it is computed live from the
-     * wizard's gates and overlaid on every status read, so the seed shape
-     * is `FormStatus` minus `locked`.
+     * `locked` is never seeded: it is computed live from the wizard's gates
+     * and overlaid on every status read. `gate: 'cleared'` IS honored, but as
+     * a one-shot seed of the gate's cleared latch at construction (an SSR
+     * restore of a confirmed prerequisite), not as a status field echoed on
+     * read — the live `gate` overlay owns the read. Only a step that compiles
+     * to a `gate()` honors it. See `FormStatusSeed`.
+     *
+     * SSR note: the async factory resolves after hydration (client-only), so
+     * a gate seeded through it clears post-hydration. For a gate that must
+     * render open on the first server byte, use the plain or sync-factory
+     * form (resolve server truth in the page's `setup` await).
      *
      * Unknown keys in the seed object dev-warn so a stale resume payload
      * surfaces at construction.
@@ -1559,7 +1588,19 @@ type WizardForms<S> = FormsRecordOf<S> & Readonly<Record<FormKey, AnyForm>>;
  *  - `reset()`     — zeros wizard lifecycle (`submissionAttempts`,
  *                    `visited`), resets every form, returns
  *                    `currentStep` to `steps[0].key`, and invokes
- *                    `persist` with the cleared state.
+ *                    `persist` with the cleared state. Re-applies the
+ *                    `defaultStatuses` gate seed, so a reboot returns to
+ *                    the seeded initial clearance, not fully sealed.
+ *  - `relock(key, commit)` — re-seal a cleared gate, contingent on
+ *                    `commit`. Awaits `commit` (a server-side revoke) and
+ *                    re-seals only if it resolves clean, so the gate reflects
+ *                    server-confirmed truth the same way a clearing submit
+ *                    does; a thrown `commit` leaves it as-is. Seal-only (never
+ *                    opens a gate), so it cannot become the leading-signal
+ *                    foot-gun `gate()` exists to prevent. `commit` is required
+ *                    (pass `() => {}` for a deliberate client-only re-seal).
+ *                    Resolves whether the gate ended up sealed; never rejects.
+ *                    Resolves `false` (dev-warn) on a non-gate key.
  */
 type UseWizardReturnType<S extends ReadonlyArray<StepSlot> = ReadonlyArray<StepSlot>> = {
     readonly key: string;
@@ -1588,6 +1629,7 @@ type UseWizardReturnType<S extends ReadonlyArray<StepSlot> = ReadonlyArray<StepS
     readonly tryNext: () => Promise<boolean>;
     readonly handleSubmit: (onSubmit: WizardOnSubmit, onError?: WizardOnError) => (event?: Event) => Promise<void>;
     readonly reset: () => void;
+    readonly relock: (key: FormKey, commit: () => void | Promise<void>) => Promise<boolean>;
 };
 
 /**

package/dist/shared/{attaform.DDIn4fv-.mjs → attaform.Dkjh_F30.mjs}

@@ -1,6 +1,6 @@
-import { r as getAtPath, p as slimKindOf, t as setAtPath, q as humanize, h as useAbstractForm } from './attaform.BqkFQ2B9.mjs';
-import { A as AttaformError, _ as __DEV__, f as canonicalizePath, a as InvalidUseFormConfigError } from './attaform.CgsQZdy1.mjs';
-import { f as fieldMetaStore, g as getFieldMetaForSchema, a as getFieldMetaListForSchema, s as slimPrimitivesWalk, w as walkPathSegments, d as deriveDefaultWalk, m as mergeDeep, c as createAbstractSchema, b as getFieldMetaPathMap } from './attaform.BKxpBJVF.mjs';
+import { r as getAtPath, p as slimKindOf, t as setAtPath, q as humanize, h as useAbstractForm } from './attaform.BypWgXRB.mjs';
+import { A as AttaformError, _ as __DEV__, f as canonicalizePath, a as InvalidUseFormConfigError } from './attaform.nMaz2C5P.mjs';
+import { f as fieldMetaStore, g as getFieldMetaForSchema, a as getFieldMetaListForSchema, s as slimPrimitivesWalk, w as walkPathSegments, d as deriveDefaultWalk, m as mergeDeep, c as createAbstractSchema, b as getFieldMetaPathMap } from './attaform.CTiZ9Rrv.mjs';
 import { z } from 'zod';
 
 const fieldMeta = fieldMetaStore;
@@ -1272,4 +1272,4 @@ function useForm(configuration) {
 }
 
 export { UnsupportedSchemaError as U, assertZodVersion as a, getIntersectionRight as b, unwrapLazy as c, unwrapInner as d, unwrapPipe as e, fieldMeta as f, getIntersectionLeft as g, getDiscriminator as h, getDiscriminatedOptions as i, getUnionOptions as j, kindOf as k, getRecordKeyType as l, getRecordValueType as m, getTupleItems as n, getSetValueType as o, getArrayElement as p, getObjectShape as q, getEnumValues as r, getLiteralValues as s, getChecks as t, useForm as u, getCatchDefault as v, withMeta as w, getDefaultValue as x, zodV4Adapter as z };
-//# sourceMappingURL=attaform.DDIn4fv-.mjs.map
+//# sourceMappingURL=attaform.Dkjh_F30.mjs.map