attaform 0.28.0 → 0.29.0

package/dist/shared/{attaform.CJP3RkGa.mjs → attaform.D1fnTifF.mjs}

@@ -1,9 +1,7 @@
-import { s as slimPrimitivesWalk, c as createAbstractSchema, w as walkPathSegments, d as deriveDefaultWalk, b as buildFieldMetaPathMap, g as getFieldMetaForSchema, m as mergeDeep, f as fixStructuralDefaults, a as getFieldMetaListForSchema } from './attaform.C09fpdLS.mjs';
-import { o as humanize, h as useAbstractForm } from './attaform.B8k8JrmK.mjs';
-import { A as AttaformError, e as canonicalizePath, a as InvalidUseFormConfigError } from './attaform.wfY8XFvm.mjs';
-
-class UnsupportedSchemaError extends AttaformError {
-}
+import { w as walkPathSegments, s as slimPrimitivesWalk, c as createAbstractSchema, b as buildFieldMetaPathMap, g as getFieldMetaForSchema, m as mergeDeep, f as fixStructuralDefaults, d as deriveDefaultWalk, a as getFieldMetaListForSchema } from './attaform.B0dKL8ST.mjs';
+import { p as getAtPath, q as humanize, h as useAbstractForm } from './attaform.CZMAYwSK.mjs';
+import { c as callConsumerSchemaFn } from './attaform.Cvao8bW5.mjs';
+import { A as AttaformError, e as canonicalizePath, a as InvalidUseFormConfigError } from './attaform.CZYt_5N_.mjs';
 
 function isZodSchemaType(schema, expectedType) {
   if (typeof schema !== "object" || schema === null) return false;
@@ -123,6 +121,8 @@ function getRecordValueType(schema) {
   const def = readDef(schema);
   return def?.valueType;
 }
+const getMapKeyType = getRecordKeyType;
+const getMapValueType = getRecordValueType;
 function getTupleItems(schema) {
   const def = readDef(schema);
   return def?.items ?? [];
@@ -163,6 +163,10 @@ function unwrapEffectsSource(schema) {
   const def = readDef(schema);
   return def?.schema;
 }
+function getEffect(schema) {
+  const def = readDef(schema);
+  return def?.effect;
+}
 function getEffectsKind(schema) {
   const def = readDef(schema);
   const type = def?.effect?.type;
@@ -188,6 +192,9 @@ function isAsyncEffect(schema) {
 function containsAsyncRefine(schema, seen) {
   return walkForTarget(schema, "refinement", seen ?? /* @__PURE__ */ new WeakSet());
 }
+function containsMapOrSet(schema, seen) {
+  return walkForTarget(schema, "map-or-set", /* @__PURE__ */ new WeakSet());
+}
 function containsDiscriminatedUnion(schema, seen) {
   return walkForTarget(schema, "discriminated-union", seen ?? /* @__PURE__ */ new WeakSet());
 }
@@ -267,9 +274,17 @@ function walkForTarget(schema, target, visited) {
     return false;
   }
   if (isZodSchemaType(schema, "ZodSet")) {
+    if (target === "map-or-set") return true;
     const elem = getSetValueType(schema);
     return elem !== void 0 && walkForTarget(elem, target, visited);
   }
+  if (isZodSchemaType(schema, "ZodMap")) {
+    if (target === "map-or-set") return true;
+    const keyType = getMapKeyType(schema);
+    if (keyType !== void 0 && walkForTarget(keyType, target, visited)) return true;
+    const valueType = getMapValueType(schema);
+    return valueType !== void 0 && walkForTarget(valueType, target, visited);
+  }
   return false;
 }
 function unwrapPipeIn(schema) {
@@ -284,11 +299,7 @@ function unwrapLazy(schema) {
   const def = readDef(schema);
   const getter = def?.getter;
   if (typeof getter !== "function") return void 0;
-  try {
-    return getter();
-  } catch {
-    return void 0;
-  }
+  return callConsumerSchemaFn(() => getter(), void 0);
 }
 function getLazyGetter(schema) {
   const def = readDef(schema);
@@ -309,21 +320,15 @@ function getDefaultValue(schema) {
   const def = readDef(schema);
   const thunk = def?.defaultValue;
   if (typeof thunk !== "function") return void 0;
-  try {
-    return thunk();
-  } catch {
-    return void 0;
-  }
+  return callConsumerSchemaFn(() => thunk(), void 0);
 }
 function getCatchDefault(schema) {
   const def = readDef(schema);
   const cv = def?.catchValue;
   if (typeof cv !== "function") return void 0;
-  try {
-    return cv({ error: null, input: void 0 });
-  } catch {
-    return void 0;
-  }
+  return callConsumerSchemaFn(
+    () => cv({ error: null, input: void 0 }),
+    void 0);
 }
 function hasCatchValue(schema) {
   const def = readDef(schema);
@@ -424,95 +429,6 @@ function isContainerAfterWrapperPeel(schema) {
   return isZodSchemaType(cur, "ZodObject") || isZodSchemaType(cur, "ZodArray") || isZodSchemaType(cur, "ZodTuple") || isZodSchemaType(cur, "ZodIntersection") || isZodSchemaType(cur, "ZodUnion") || isZodSchemaType(cur, "ZodDiscriminatedUnion") || isZodSchemaType(cur, "ZodRecord") || isZodSchemaType(cur, "ZodSet");
 }
 
-const UNSUPPORTED_TYPE_NAMES = /* @__PURE__ */ new Set(["ZodPromise", "ZodFunction", "ZodMap", "ZodSymbol"]);
-function labelPath(path) {
-  return path.length === 0 ? "<root>" : path.join(".");
-}
-function assertSupportedKinds(schema, path = [], lazyGetters = []) {
-  const typeName = getTypeName(schema);
-  if (typeName !== void 0 && UNSUPPORTED_TYPE_NAMES.has(typeName)) {
-    throw new UnsupportedSchemaError(
-      `[attaform] AF02 attaform.dev/e/af02 '${typeName}' at '${labelPath(path)}'`
-    );
-  }
-  if (isZodSchemaType(schema, "ZodObject")) {
-    for (const [key, sub] of Object.entries(getObjectShape(schema))) {
-      assertSupportedKinds(sub, [...path, key], lazyGetters);
-    }
-    return;
-  }
-  if (isZodSchemaType(schema, "ZodArray")) {
-    const inner = getArrayElement(schema);
-    if (inner) assertSupportedKinds(inner, [...path, "*"], lazyGetters);
-    return;
-  }
-  if (isZodSchemaType(schema, "ZodSet")) {
-    const inner = getSetValueType(schema);
-    if (inner) assertSupportedKinds(inner, [...path, "*"], lazyGetters);
-    return;
-  }
-  if (isZodSchemaType(schema, "ZodRecord")) {
-    const inner = getRecordValueType(schema);
-    if (inner) assertSupportedKinds(inner, [...path, "*"], lazyGetters);
-    return;
-  }
-  if (isZodSchemaType(schema, "ZodTuple")) {
-    const items = getTupleItems(schema);
-    items.forEach((item, i) => assertSupportedKinds(item, [...path, String(i)], lazyGetters));
-    return;
-  }
-  if (isZodSchemaType(schema, "ZodUnion")) {
-    const options = getUnionOptions(schema);
-    options.forEach((opt, i) => assertSupportedKinds(opt, [...path, `|${i}`], lazyGetters));
-    return;
-  }
-  if (isZodSchemaType(schema, "ZodDiscriminatedUnion")) {
-    const options = getDiscriminatedOptions(schema);
-    options.forEach((opt, i) => assertSupportedKinds(opt, [...path, `|${i}`], lazyGetters));
-    return;
-  }
-  if (isZodSchemaType(schema, "ZodIntersection")) {
-    const left = getIntersectionLeft(schema);
-    if (left) assertSupportedKinds(left, [...path, "left"], lazyGetters);
-    const right = getIntersectionRight(schema);
-    if (right) assertSupportedKinds(right, [...path, "right"], lazyGetters);
-    return;
-  }
-  if (isZodSchemaType(schema, "ZodOptional") || isZodSchemaType(schema, "ZodNullable") || isZodSchemaType(schema, "ZodDefault") || isZodSchemaType(schema, "ZodReadonly") || isZodSchemaType(schema, "ZodCatch")) {
-    const inner = unwrapInner(schema);
-    if (inner) assertSupportedKinds(inner, path, lazyGetters);
-    return;
-  }
-  if (isZodSchemaType(schema, "ZodBranded")) {
-    const inner = unwrapBranded(schema);
-    if (inner) assertSupportedKinds(inner, path, lazyGetters);
-    return;
-  }
-  if (isZodSchemaType(schema, "ZodEffects")) {
-    const inner = unwrapEffectsSource(schema);
-    if (inner) assertSupportedKinds(inner, path, lazyGetters);
-    return;
-  }
-  if (isZodSchemaType(schema, "ZodPipeline")) {
-    const inner = unwrapPipeIn(schema);
-    if (inner) assertSupportedKinds(inner, path, lazyGetters);
-    return;
-  }
-  if (isZodSchemaType(schema, "ZodLazy")) {
-    const getter = getLazyGetter(schema);
-    if (getter !== void 0 && lazyGetters.includes(getter)) return;
-    const inner = getter?.();
-    if (inner !== void 0) {
-      assertSupportedKinds(
-        inner,
-        path,
-        getter === void 0 ? lazyGetters : [...lazyGetters, getter]
-      );
-    }
-    return;
-  }
-}
-
 const V3_INTROSPECTOR = {
   kindOf: (schema) => kindOf(schema),
   getObjectShape,
@@ -531,6 +447,8 @@ const V3_INTROSPECTOR = {
   getSetValueType,
   getRecordKeyType,
   getRecordValueType,
+  getMapKeyType: (schema) => kindOf(schema) === "map" ? getMapKeyType(schema) : void 0,
+  getMapValueType: (schema) => kindOf(schema) === "map" ? getMapValueType(schema) : void 0,
   getUnionOptions,
   getIntersectionLeft,
   getIntersectionRight,
@@ -551,14 +469,84 @@ const V3_INTROSPECTOR = {
   hasCatchValue
 };
 
+function mapKeyAt(value, index) {
+  if (!(value instanceof Map)) return void 0;
+  if (typeof index !== "number" || !Number.isInteger(index) || index < 0) return void 0;
+  let i = 0;
+  for (const key of value.keys()) {
+    if (i === index) return key;
+    i += 1;
+  }
+  return void 0;
+}
+function stepSchema(schema, segment, maxRecursionDepth) {
+  if (schema === void 0) return void 0;
+  return walkPathSegments(schema, [String(segment)], V3_INTROSPECTOR, maxRecursionDepth, 0)[0];
+}
+function normalizeIssuePaths(issues, rootSchema, data, maxRecursionDepth, peel) {
+  let out = null;
+  for (let i = 0; i < issues.length; i++) {
+    const issue = issues[i];
+    const next = normalizeOne(issue.path, rootSchema, data, maxRecursionDepth, peel);
+    if (next === null) continue;
+    out ?? (out = [...issues]);
+    out[i] = { ...issue, path: next };
+  }
+  return out ?? issues;
+}
+function normalizeOne(path, rootSchema, data, maxRecursionDepth, peel) {
+  const out = [];
+  let schema = rootSchema;
+  let value = data;
+  let changed = false;
+  let i = 0;
+  while (i < path.length) {
+    const peeled = schema === void 0 ? void 0 : peel(schema);
+    const kind = peeled === void 0 ? void 0 : V3_INTROSPECTOR.kindOf(peeled);
+    if (kind === "set") {
+      changed = true;
+      break;
+    }
+    if (kind === "map") {
+      const key = mapKeyAt(value, path[i]);
+      if (key === void 0) {
+        changed = true;
+        break;
+      }
+      if (typeof key !== "string" && typeof key !== "number") {
+        changed = true;
+        break;
+      }
+      out.push(key);
+      value = value.get(key);
+      schema = V3_INTROSPECTOR.getMapValueType(peeled);
+      changed = true;
+      const half = path[i + 1];
+      i += half === "key" || half === "value" ? 2 : 1;
+      continue;
+    }
+    const segment = path[i];
+    out.push(segment);
+    value = getAtPath(value, [segment]);
+    schema = stepSchema(schema, segment, maxRecursionDepth);
+    i += 1;
+  }
+  return changed ? out : null;
+}
+
 function slimPrimitivesV3(schema) {
   return new Set(slimPrimitivesWalk(schema, V3_INTROSPECTOR, 64));
 }
 
 function rebuildWithDef(original, defPatch) {
-  const node = Object.create(Object.getPrototypeOf(original));
-  node._def = { ...original._def, ...defPatch };
-  return node;
+  return Object.create(Object.getPrototypeOf(original), {
+    _def: {
+      value: { ...original._def, ...defPatch },
+      writable: true,
+      enumerable: true,
+      configurable: true
+    }
+  });
 }
 function rebuildObject(original, shape) {
   const node = rebuildWithDef(original, { shape: () => shape, unknownKeys: "strip" });
@@ -613,8 +601,20 @@ function rebuildDiscriminatedUnion(original, options) {
   }
   return rebuildWithDef(original, { options, optionsMap });
 }
+function rebuildEffects(original, source, effect) {
+  return rebuildWithDef(original, { schema: source, effect });
+}
 
 function stripAsyncChecks(schema) {
+  return walkEffects(schema, "strip");
+}
+function wrapAsyncSafeRefinements(schema) {
+  return walkEffects(schema, "wrap");
+}
+function isThenable(value) {
+  return value !== null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+}
+function walkEffects(schema, policy) {
   const seen = /* @__PURE__ */ new WeakSet();
   function recurse(s) {
     const candidate = s;
@@ -623,7 +623,26 @@ function stripAsyncChecks(schema) {
     seen.add(candidate);
     if (isZodSchemaType(s, "ZodEffects")) {
       const inner = unwrapEffectsSource(s);
-      return inner === void 0 ? s : recurse(inner);
+      if (inner === void 0) return s;
+      if (policy === "strip") return recurse(inner);
+      const effect = getEffect(s);
+      const rebuiltInner = recurse(inner);
+      const original = effect?.["refinement"];
+      if (effect === void 0 || typeof original !== "function") {
+        return rebuildEffects(s, rebuiltInner, effect);
+      }
+      const refine = original;
+      const safeEffect = {
+        ...effect,
+        refinement: (value, ctx) => {
+          const result = refine(value, ctx);
+          if (isThenable(result)) {
+            void result.catch(() => void 0);
+          }
+          return result;
+        }
+      };
+      return rebuildEffects(s, rebuiltInner, safeEffect);
     }
     if (isZodSchemaType(s, "ZodOptional")) {
       const inner = unwrapInner(s);
@@ -771,18 +790,17 @@ function carryObjectChecks(rebuilt, original) {
 
 const MAX_UNWRAP_STEPS = 64;
 function zodAdapter(zodSchema) {
-  assertSupportedKinds(zodSchema);
   const peeledRoot = peelAllV3Wrappers(zodSchema);
   if (!isZodSchemaType(peeledRoot, "ZodObject") && !isZodSchemaType(peeledRoot, "ZodRecord") && !isZodSchemaType(peeledRoot, "ZodDiscriminatedUnion")) {
-    const name = getTypeName(peeledRoot);
-    throw new Error(
-      `Attaform: useForm schema root must be a ZodObject, ZodRecord, or ZodDiscriminatedUnion (got ${name}). Wrap other shapes under a key.`
+    const name = getTypeName(peeledRoot) ?? "unknown";
+    throw new AttaformError(
+      `[attaform] AF15 attaform.dev/e/af15 '${name}'`
     );
   }
   return (formKey, options) => createAbstractSchema(
     zodSchema,
     V3_INTROSPECTOR,
-    buildV3Services(),
+    buildV3Services(options.maxRecursionDepth),
     formKey,
     options
   );
@@ -791,10 +809,28 @@ async function lazyFingerprint(schema) {
   const { fingerprintZodSchema } = await import('../chunks/fingerprint.mjs');
   return fingerprintZodSchema(schema);
 }
-function buildV3Services() {
+const syncSafeCache = /* @__PURE__ */ new WeakMap();
+function syncSafe(schema) {
+  const cached = syncSafeCache.get(schema);
+  if (cached !== void 0) return cached;
+  const wrapped = wrapAsyncSafeRefinements(schema);
+  syncSafeCache.set(schema, wrapped);
+  return wrapped;
+}
+function buildV3Services(maxRecursionDepth) {
+  const mapOrSetBySchema = /* @__PURE__ */ new WeakMap();
+  const refileIssues = (schema, data, issues) => {
+    let hasMapOrSet = mapOrSetBySchema.get(schema);
+    if (hasMapOrSet === void 0) {
+      hasMapOrSet = containsMapOrSet(schema);
+      mapOrSetBySchema.set(schema, hasMapOrSet);
+    }
+    if (!hasMapOrSet) return issues;
+    return normalizeIssuePaths(issues, schema, data, maxRecursionDepth, peelAllV3Wrappers);
+  };
   return {
     fingerprint: (schema) => lazyFingerprint(schema),
-    getNestedSchemasAtPath: (schema, path, maxRecursionDepth) => getNestedZodSchemasAtPath(schema, path, maxRecursionDepth),
+    getNestedSchemasAtPath: (schema, path, maxRecursionDepth2) => getNestedZodSchemasAtPath(schema, path, maxRecursionDepth2),
     // v3 pre-strips refinements / defaults / wrappers off the root for
     // slim-mode walks — `getSlimPrimitiveTypesAtPath` and
     // `getSchemasAtPath` both consume this variant so the yielded
@@ -802,34 +838,34 @@ function buildV3Services() {
     // The slim-root projection is gone (size-teardown P7): the shared
     // path walker peels wrappers / effects inline, so the slim and
     // unstripped walks coincide — same aliasing v4 always had.
-    getNestedSchemasInSlimMode: (schema, path, maxRecursionDepth) => getNestedZodSchemasAtPath(schema, path, maxRecursionDepth),
+    getNestedSchemasInSlimMode: (schema, path, maxRecursionDepth2) => getNestedZodSchemasAtPath(schema, path, maxRecursionDepth2),
     slimPrimitivesOf: (schema, _maxRecursionDepth) => slimPrimitivesV3(schema),
     deriveDefault: (schema, useDefault, _maxRecursionDepth, formKey) => getDefaultValuesFromZodSchema(schema, useDefault, formKey),
-    runStrictGetDefaults: (schema, config, formKey, maxRecursionDepth) => runStrictGetDefaultsV3(schema, config, formKey, maxRecursionDepth),
+    runStrictGetDefaults: (schema, config, formKey, maxRecursionDepth2) => runStrictGetDefaultsV3(schema, config, formKey, maxRecursionDepth2),
     unwrapStructuralWrappers: (schema) => unwrapStructuralLeafV3(schema),
     unwrapToDiscriminatedUnion: (schema) => unwrapToDiscriminatedUnion(schema),
     peelAllWrappers: (schema) => peelAllV3Wrappers(schema),
     isLeafRequired: (schema) => isLeafRequiredV3(schema),
-    resolveFieldMetaAtPath: (schema, path, maxRecursionDepth) => resolveFieldMetaAtPathV3(schema, path, maxRecursionDepth),
+    resolveFieldMetaAtPath: (schema, path, maxRecursionDepth2) => resolveFieldMetaAtPathV3(schema, path, maxRecursionDepth2),
     issuesToValidationErrors: (issues) => zodIssuesToValidationErrors(issues),
     safeParseSync: (schema, data) => {
-      const result = schema.safeParse(data);
-      return result.success ? { success: true, data: result.data } : { success: false, issues: result.error.issues };
+      const result = syncSafe(schema).safeParse(data);
+      return result.success ? { success: true, data: result.data } : { success: false, issues: refileIssues(schema, data, result.error.issues) };
     },
     safeParseAsync: async (schema, data) => {
       const result = await schema.safeParseAsync(data);
-      return result.success ? { success: true, data: result.data } : { success: false, issues: result.error.issues };
+      return result.success ? { success: true, data: result.data } : { success: false, issues: refileIssues(schema, data, result.error.issues) };
     },
     // v3 returns the full recursive AbstractSchema for sub-schemas (the
     // historical shape) — `getSchemasAtPath` consumers may probe any
     // method on the result. The factory call rebuilds the full surface
     // against the sub-schema with its own per-form caches.
-    makeSubSchema: (sub, formKey, maxRecursionDepth) => createAbstractSchema(
+    makeSubSchema: (sub, formKey, maxRecursionDepth2) => createAbstractSchema(
       sub,
       V3_INTROSPECTOR,
-      buildV3Services(),
+      buildV3Services(maxRecursionDepth2),
       formKey,
-      { maxRecursionDepth }
+      { maxRecursionDepth: maxRecursionDepth2 }
     )
   };
 }
@@ -1098,7 +1134,7 @@ function runStrictGetDefaultsV3(rootSchema, config, formKey, maxRecursionDepth)
       };
     }
     try {
-      const strictResult = rootSchema.safeParse(rawDefaultValues);
+      const strictResult = syncSafe(rootSchema).safeParse(rawDefaultValues);
       if (strictResult.success) {
         return {
           data: rawDefaultValues,
@@ -1117,7 +1153,7 @@ function runStrictGetDefaultsV3(rootSchema, config, formKey, maxRecursionDepth)
       const isAsyncDetect = err instanceof Error && err.message.includes("Async refinement encountered");
       if (isAsyncDetect) {
         try {
-          const strippedResult = stripAsyncChecks(rootSchema).safeParse(rawDefaultValues);
+          const strippedResult = syncSafe(stripAsyncChecks(rootSchema)).safeParse(rawDefaultValues);
           if (strippedResult.success) {
             return {
               data: rawDefaultValues,

package/dist/shared/{attaform.D5V4tZWq.d.mts → attaform.DDtqHYv1.d.mts}

@@ -1,4 +1,4 @@
-import { G as GenericForm, F as FormKey, a as UseFormReturnType, a5 as RegisterValue, V as PathKey, k as DisplayCtx, w as GetDisplayState, l as DisplayMachine, aa as SlimPrimitiveKind, C as CoercionEntry, e as CoercionRegistry, au as FieldRecord, av as ErrorCell, ag as ValidationError, aw as OriginalsRecord, A as AbstractSchema, T as Path, ak as WriteMeta, h as DeepPartial, al as WriteShape, ax as AttaformDomBinding, ay as TransformAbortHolder, ae as ValidateOn, d as AttaformDefaults } from './attaform.Cgu-hdSb.mjs';
+import { G as GenericForm, F as FormKey, a as UseFormReturnType, a7 as RegisterValue, V as PathKey, k as DisplayCtx, w as GetDisplayState, l as DisplayMachine, ac as SlimPrimitiveKind, C as CoercionEntry, e as CoercionRegistry, aw as FieldRecord, ax as ErrorCell, ai as ValidationError, ay as OriginalsRecord, A as AbstractSchema, T as Path, am as WriteMeta, h as DeepPartial, an as WriteShape, az as AttaformDomBinding, aA as TransformAbortHolder, ag as ValidateOn, d as AttaformDefaults } from './attaform.CsoeRi3P.mjs';
 import { Ref, ComputedRef, ShallowRef, App, InjectionKey, Plugin } from 'vue';
 
 /**
@@ -121,6 +121,22 @@ declare function injectForm<Form extends GenericForm, GetValueFormType extends G
  * composable's `onMounted` warn fires once per instance to surface
  * the misuse case at runtime.
  *
+ * A wrapper meant to work both ways says so with
+ * `useRegister({ optional: true })`, which silences the unbound
+ * diagnostic and changes nothing else. Without it the diagnostic still
+ * earns its keep: a single-mode wrapper whose parent forgot
+ * `v-register` renders a field that looks fine and stores nothing.
+ *
+ * `rv?.isBound` is the test for "did a parent bind me", and it is the
+ * one to reach for: script-setup code holds the Proxy, which is an
+ * object and so always truthy, while a template holds the unwrapped
+ * ref, which is `undefined` when unbound. Those two disagree, and
+ * `isBound` reads the same on both. A dual-mode wrapper (one used
+ * both `v-register`-bound and plain `v-model`-bound) branches on it,
+ * and does not need to duplicate its element to do so: the
+ * compile-time value injection keeps an author-written `:value` /
+ * `:checked` as its unbound leg, so one element serves both (#620).
+ *
  * Diagnostic: in dev mode, a single `console.warn` fires per instance
  * at `onMounted` if the captured value is still `undefined` — by then
  * the parent has had its full mount lifecycle to bind, so a missing
@@ -149,8 +165,48 @@ declare function injectForm<Form extends GenericForm, GetValueFormType extends G
  * the hybrid's only `.value`. Older code that read `rv.value?.path`
  * keeps working; new code can write `rv.path` directly.
  */
-type UseRegisterReturn<V = unknown> = RegisterValue<V> & Ref<RegisterValue<V> | undefined>;
-declare function useRegister<V = unknown>(): UseRegisterReturn<V> | undefined;
+type UseRegisterReturn<V = unknown> = RegisterValue<V> & Ref<RegisterValue<V> | undefined> & {
+    /**
+     * Whether a parent has actually bound this wrapper. `false` until a
+     * `RegisterValue` lands, `true` once one has, and reactive in both
+     * directions: a parent that binds on a later render flips it, and
+     * so does one that stops binding.
+     *
+     * This is the test a dual-mode wrapper reaches for, and the reason
+     * it exists as a field rather than a truthiness check on the
+     * return: the composable cannot answer "is this bound" at setup
+     * time. A parent is free to bind on a later render
+     * (`v-register="ready ? form.register('x') : undefined"`), and
+     * `useRegister` has to keep serving that, so it can never return a
+     * plain `undefined` for "unbound right now". Script-setup code
+     * reading `rv` directly sees the hybrid Proxy, which is an object
+     * and therefore always truthy; a template sees the unwrapped ref,
+     * which IS `undefined` when unbound. `rv?.isBound` reads the same
+     * on both sides (#620).
+     */
+    readonly isBound: boolean;
+};
+/**
+ * Options for `useRegister`.
+ */
+type UseRegisterOptions = {
+    /**
+     * Declares that this wrapper is used both with and without a form, so
+     * a render with no parent binding is intended rather than a mistake.
+     * Silences the unbound diagnostic; nothing else changes.
+     *
+     * The diagnostic exists because a single-mode wrapper whose parent
+     * forgot `v-register` renders a field that looks fine and stores
+     * nothing, which is an expensive afternoon. Once a wrapper is
+     * deliberately dual-mode, the same signal fires on correct code and
+     * tells the author to do something wrong, so this is the one fact
+     * that separates the two cases and only the author has it (#620).
+     *
+     * Pair it with `rv?.isBound` to branch on what actually happened.
+     */
+    readonly optional?: boolean;
+};
+declare function useRegister<V = unknown>(options?: UseRegisterOptions): UseRegisterReturn<V> | undefined;
 
 /**
  * Per-form display engine: owns the clock and the timers that the pure
@@ -466,10 +522,22 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * Resolves after `hydrating` flips back to `false`; consumers can
      * `await form.rehydrate()` to gate UI on the fresh load.
      *
-     * Does NOT touch dirty / touched / submit state — chain
-     * `form.reset()` if you want a clean baseline.
+     * Does NOT touch touched / submit state; chain `form.reset()` if you
+     * want a clean surface. It DOES re-seat the defaults (see
+     * `adoptResolvedDefaults`), so dirty afterwards means "differs from
+     * what the factory just returned", and `form.reset()` lands on the
+     * fresh values rather than throwing them away.
      */
     rehydrate(): Promise<void>;
+    /**
+     * Adopt a resolved async-defaults value as the form's durable
+     * defaults and re-seed the dirty baseline from it. Called by the
+     * activate / rehydrate orchestrator once its factory settles.
+     * Exposed on the store (rather than imported) because
+     * `form-activation` is imported BY this module; a value import back
+     * the other way would close a cycle.
+     */
+    adoptResolvedDefaults(value: unknown): void;
     /**
      * Incremented by every `reset()` call. The submit wrapper captures
      * this at entry and skips writing `submitError` from a catch that
@@ -1486,6 +1554,12 @@ type WizardForms<S> = FormsRecordOf<S> & Readonly<Record<FormKey, AnyForm>>;
  *                    `back()` does not pop; the trail is the audit
  *                    log, not the back-stack.
  *  - `next/back/goTo` — pure navigation. Refuses while `submitting`.
+ *                    The one exception is `next()` on an UNCLEARED
+ *                    `gate()` step, which behaves as `tryNext()` so
+ *                    wiring Next straight to it can never skip the
+ *                    gate's confirmation. Once that gate clears, `next()`
+ *                    is plain navigation again and does not re-submit to
+ *                    re-confirm.
  *  - `tryNext()`   — submit the active step, and once that submit
  *                    resolves clean, advance; invalid input keeps the pin
  *                    put under the form's standard error reveal (first
@@ -1495,6 +1569,13 @@ type WizardForms<S> = FormsRecordOf<S> & Readonly<Record<FormKey, AnyForm>>;
  *                    (`@click="wizard.tryNext()"`); resolves to whether
  *                    the pin moved. No-ops to `false` on a degenerate or
  *                    final-step wizard (finish via `handleSubmit`).
+ *                    Called while the active step's form already has a
+ *                    submit in flight (the usual case being from inside
+ *                    that form's own callback), it rides that submit
+ *                    rather than starting a second one, so one action
+ *                    costs one submission. The pin has not moved by the
+ *                    time it resolves, so the answer is `false`; the
+ *                    advance lands with the in-flight submit.
  *  - `handleSubmit(onSubmit, onError?)` — always validates the entire
  *                    step list, from any step, and never advances the
  *                    pin: on success it latches `done`; on any error it
@@ -2380,5 +2461,5 @@ declare function makeDefaultDisplayState({ showDelay, minVisible, }: DisplayTimi
  */
 declare const defaultDisplayState: GetDisplayState;
 
-export { renderAttaformState as $, createAttaform as B, DEFAULT_TIMINGS as D, createRegistry as E, defaultCoercionRules as H, defaultDisplayState as J, defineCoercion as K, escapeForInlineScript as M, gate as N, OutsideSetupError as O, getRegistryFromApp as P, hydrateAttaformState as Q, RegistryNotInstalledError as R, injectForm as T, injectWizard as V, isRegisterValue as X, kAttaformRegistry as Y, lazy as Z, makeDefaultDisplayState as _, useRegister as a0, useRegistry as a1, useWizard as a2, AttaformError as c, AttaformErrorCode as d, DEVTOOLS_WINDOW_KEY as f, InvalidPathError as i, InvalidUseFormConfigError as j, ReservedFormKeyError as k, SubmitErrorHandlerError as n, assignKey as z };
-export type { AttaformRegistry as A, CompiledStep as C, FormStatus as F, GateMarker as G, InjectWizardInput as I, LazyMarker as L, SerializedAttaformState as S, UseRegisterReturn as U, WizardAggregateError as W, AnyForm as a, AttaformDevtoolsBridge as b, AttaformPluginOptions as e, DisplayTimings as g, FormStatusSeed as h, SerializedFormData as l, StepSlot as m, UseWizardReturnType as o, WizardCtx as p, WizardCtxForm as q, WizardOnError as r, WizardOnSubmit as s, WizardOptions as t, WizardPersistFn as u, WizardRestoreFn as v, WizardRestoreState as w, WizardStatusesProxy as x, WizardSubmitContext as y };
+export { makeDefaultDisplayState as $, assignKey as B, DEFAULT_TIMINGS as D, createAttaform as E, createRegistry as H, defaultCoercionRules as J, defaultDisplayState as K, defineCoercion as M, escapeForInlineScript as N, OutsideSetupError as O, gate as P, getRegistryFromApp as Q, RegistryNotInstalledError as R, hydrateAttaformState as T, injectForm as V, injectWizard as X, isRegisterValue as Y, kAttaformRegistry as Z, lazy as _, renderAttaformState as a0, useRegister as a1, useRegistry as a2, useWizard as a3, AttaformError as c, AttaformErrorCode as d, DEVTOOLS_WINDOW_KEY as f, InvalidPathError as i, InvalidUseFormConfigError as j, ReservedFormKeyError as k, SubmitErrorHandlerError as n };
+export type { AttaformRegistry as A, CompiledStep as C, FormStatus as F, GateMarker as G, InjectWizardInput as I, LazyMarker as L, SerializedAttaformState as S, UseRegisterOptions as U, WizardAggregateError as W, AnyForm as a, AttaformDevtoolsBridge as b, AttaformPluginOptions as e, DisplayTimings as g, FormStatusSeed as h, SerializedFormData as l, StepSlot as m, UseRegisterReturn as o, UseWizardReturnType as p, WizardCtx as q, WizardCtxForm as r, WizardOnError as s, WizardOnSubmit as t, WizardOptions as u, WizardPersistFn as v, WizardRestoreFn as w, WizardRestoreState as x, WizardStatusesProxy as y, WizardSubmitContext as z };

package/dist/shared/{attaform.uLbun31C.mjs → attaform.DffRL5pP.mjs}

@@ -1,6 +1,6 @@
 import { reactive, markRaw, effectScope, watch, nextTick } from 'vue';
 import { i as isRegisterValue, a as isTransforming, S as SSR_COMPONENT_HOST_MODIFIER, R as REGISTER_OWNER_MARKER, b as V_REGISTER_MARKER } from './attaform.KvlEedlF.mjs';
-import { e as canonicalizePath } from './attaform.wfY8XFvm.mjs';
+import { e as canonicalizePath } from './attaform.CZYt_5N_.mjs';
 
 const INTERACTIVE_TAG_NAMES = /* @__PURE__ */ new Set(["INPUT", "SELECT", "TEXTAREA"]);
 
@@ -1107,6 +1107,14 @@ function setSelected(el, value) {
   const externalValue = value.innerRef.value;
   const isMultiple = el.multiple;
   const isArrayValue = isArray(externalValue);
+  const isUnset = externalValue === null || externalValue === void 0;
+  if (isMultiple && isUnset) {
+    for (let i = 0, l = el.options.length; i < l; i++) {
+      const option = el.options[i];
+      if (option !== void 0) option.selected = false;
+    }
+    return;
+  }
   if (isMultiple && !isArrayValue && !isSet(externalValue)) {
     return;
   }
@@ -1134,10 +1142,11 @@ function setSelected(el, value) {
     }
     return;
   }
+  const target = value.displayValue.value === "" ? "" : externalValue;
   for (let i = 0, l = el.options.length; i < l; i++) {
     const option = el.options[i];
     if (!option) continue;
-    if (looseEqual(applyCoerce(getValue(option), value), externalValue)) {
+    if (looseEqual(applyCoerce(getValue(option), value), target)) {
       if (el.selectedIndex !== i) el.selectedIndex = i;
       return;
     }
@@ -1221,8 +1230,7 @@ function observeForLateHostControl(el, rv) {
   hostHealObservers.set(el, observer);
 }
 function activateComponentHost(el, rv) {
-  if (rv.hasRegisteredDescendant(el))
-    return;
+  if (rv.hasRegisteredDescendant(el)) return;
   el[REGISTER_OWNER_MARKER] = true;
   if (!el.tagName.includes("-")) {
     el.removeAttribute("registerValue");

package/dist/shared/{attaform.JfSWdEcb.d.mts → attaform.axHXVQO7.d.mts}

@@ -1,5 +1,5 @@
 import { App } from 'vue';
-import { ar as RegisterModelDynamicCustomDirective } from './attaform.Cgu-hdSb.mjs';
+import { at as RegisterModelDynamicCustomDirective } from './attaform.CsoeRi3P.mjs';
 
 /**
  * The `v-register` directive. Bind a form field to a native input,