attaform 0.19.0 → 0.20.0

package/dist/shared/{attaform.BtBmfLQN.d.mts → attaform.EMzJcQci.d.mts}

@@ -1,4 +1,4 @@
-import { t as FormKey, ae as SlimPrimitiveKind, C as CoercionEntry, g as CoercionRegistry, G as GenericForm, T as PathKey, S as Path, am as ValidationError, A as AbstractSchema, x as GetDisplayState, aq as WriteMeta, D as DeepPartial, ar as WriteShape, ak as ValidateOn, Y as PersistOptInRegistry, aa as Segment, f as AttaformDefaults, aj as UseFormReturnType, a8 as RegisterValue } from './attaform.C0uGZQ4M.mjs';
+import { t as FormKey, ae as SlimPrimitiveKind, C as CoercionEntry, g as CoercionRegistry, G as GenericForm, T as PathKey, S as Path, am as ValidationError, A as AbstractSchema, x as GetDisplayState, aq as WriteMeta, D as DeepPartial, ar as WriteShape, ak as ValidateOn, Y as PersistOptInRegistry, f as AttaformDefaults, aj as UseFormReturnType, a8 as RegisterValue } from './attaform.SfhU0OEY.mjs';
 import { Ref, ComputedRef, App, InjectionKey } from 'vue';
 
 /**
@@ -61,7 +61,7 @@ type FormStatus = {
  * entry carries the formKey + path tuple so consumers can route to the
  * offending field from a wizard-wide error summary.
  */
-type AggregateError = {
+type WizardAggregateError = {
     readonly formKey: FormKey;
     readonly path: ReadonlyArray<string | number>;
     readonly message: string;
@@ -213,7 +213,7 @@ type WizardOnSubmit = (ctx: WizardSubmitContext) => void | Promise<void>;
  * validation and activation failures (`atta:activation-failed`). Sync
  * or async; the returned promise gates `wizard.submitting`.
  */
-type WizardOnError = (errors: readonly AggregateError[]) => void | Promise<void>;
+type WizardOnError = (errors: readonly WizardAggregateError[]) => void | Promise<void>;
 /**
  * Options for `useWizard({ steps, … })`. `steps` is the only required
  * field; the rest are optional and default sensibly for the common
@@ -439,7 +439,7 @@ type UseWizardReturnType<S extends ReadonlyArray<StepSlot> = ReadonlyArray<StepS
     readonly count: number;
     readonly statuses: WizardStatusesProxy<Record<string, FormStatus>>;
     readonly allValues: Readonly<Record<FormKey, unknown>>;
-    readonly allErrors: Readonly<Record<FormKey, readonly AggregateError[]>>;
+    readonly allErrors: Readonly<Record<FormKey, readonly WizardAggregateError[]>>;
     readonly progress: number;
     readonly canAdvance: boolean;
     readonly canGoBack: boolean;
@@ -701,6 +701,15 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * plain-value forms. Read by `form.rehydrate()`.
      */
     readonly defaultValuesFactory: Ref<(() => unknown | Promise<unknown>) | undefined>;
+    /**
+     * `true` when this store carries an SSR prefetch queue (server path
+     * where `state.activate()` must enqueue intent before deciding
+     * whether to fire). The flag lets `buildFormApi` skip the lazy
+     * activation gate for forms with no factory AND no SSR prefetch —
+     * the common client-side case where `gated()` is otherwise pure
+     * reactive overhead on every public method call.
+     */
+    readonly hasSsrPrefetch: boolean;
     /**
      * `true` once the form's effective defaults have been applied —
      * sync `defaultValues` at construction, or async factory whose
@@ -797,6 +806,14 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * answer.
      */
     pathHasAsyncValidation(path: Path): boolean;
+    /**
+     * Precomputed-key shortcut for `pathHasAsyncValidation`. The
+     * canonical key is required and must correspond to `segments`; the
+     * helper skips the `canonicalizePath` round-trip so descendant-walk
+     * loops (whose Map iteration already yields the canonical key) can
+     * read the async-gate verdict without a per-leaf canonicalize.
+     */
+    pathHasAsyncValidationByKey(key: PathKey, segments: Path): boolean;
     /**
      * Per-path counter of in-flight field-level validation runs.
      * `field.validating` on `FieldState` mirrors
@@ -852,14 +869,6 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
     arrayElementKey(path: Path): string;
     reset(nextDefaultValues?: DeepPartial<WriteShape<F>>): void;
     resetField(path: Path): void;
-    /**
-     * Wipe `path` (or the whole form when `path === ''`) to the
-     * schema's "appropriate nullish value" — the underlying type's
-     * empty/falsy concrete, with `.default()` / `.catch()` wrappers
-     * INTENTIONALLY skipped. Sugar for
-     * `setValueAtPath(path, schema.getEmptyValueAtPath(path))`.
-     */
-    clear(path: Path): boolean;
     setSchemaErrorsForPath(path: Path, errors: ValidationError[]): void;
     setAllSchemaErrors(errors: readonly ValidationError[]): void;
     clearSchemaErrors(path?: Path): void;
@@ -912,7 +921,6 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
     markFocused(path: Path, focused: boolean, meta?: {
         readonly instance?: WriteMeta['instance'];
     }): void;
-    markTouched(path: Path): void;
     /**
      * Flip `interacted: true` on a leaf — the sticky value-mutation flag.
      * Driven by the directive's input listeners (via the RegisterValue's
@@ -945,6 +953,14 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * isn't exposed to consumers.
      */
     isPristineAtPath(path: Path): boolean;
+    /**
+     * Precomputed-key shortcut for `isPristineAtPath`. The canonical
+     * key is required and must correspond to `segments`; the helper
+     * skips the `canonicalizePath` round-trip so descendant-walk loops
+     * (whose Map iteration already yields the canonical key) can read
+     * the pristine verdict without a per-leaf canonicalize.
+     */
+    isPristineAtPathByKey(key: PathKey, segments: Path): boolean;
     /**
      * Whether any tracked array under `path` has changed shape — a reorder,
      * insert, or removal — relative to its construction/reset baseline. The
@@ -1086,7 +1102,7 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * Resolved sensitive-path predicate for THIS form. Honors the
      * cascade (`useForm({ sensitiveNames })` > global default >
      * library `DEFAULT_SENSITIVE_NAMES`). Used by:
-     *  - persistence enforcement (`enforceSensitiveCheck` at write time);
+     *  - the persistence opt-in gate (`allowSensitivePersist`);
      *  - the multi-tab sync module (outbound strip + inbound reject);
      *  - DevTools edit rejection;
      *  - any future surface that needs to flag "this path holds
@@ -1097,14 +1113,6 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * resolved-config surface.
      */
     readonly isSensitivePath: (path: Path | PathKey | string) => boolean;
-    /**
-     * Single-segment variant of `isSensitivePath`. Used by the DevTools
-     * redact walk to short-circuit whole subtrees the moment any
-     * ancestor segment matches — saving an O(leaves × ancestors) regex
-     * sweep per timeline event. Resolved from the same `sensitiveNames`
-     * cascade as `isSensitivePath`.
-     */
-    readonly segmentMatchesSensitive: (segment: Segment) => boolean;
     /**
      * Canonical path keys explicitly opted OUT of multi-tab sync by
      * `register(path, { multiTab: false })`. The sync module's outbound
@@ -1428,6 +1436,83 @@ type InjectFormInput = {
  */
 declare function injectForm<Form extends GenericForm, GetValueFormType extends GenericForm = Form>(input?: FormKey | InjectFormInput): UseFormReturnType<Form, GetValueFormType> | null;
 
+/**
+ * Re-bind a parent's `v-register` onto an inner native element. Use
+ * inside a component that wraps a single form field whose root is
+ * NOT the input itself (e.g. a labelled-row that renders `<label>`
+ * around the input).
+ *
+ * ```vue
+ * <!-- Parent -->
+ * <MyInput v-register="form.register('email')" />
+ *
+ * <!-- MyInput.vue -->
+ * <script setup lang="ts">
+ *   import { useRegister } from 'attaform'
+ *   const rv = useRegister()
+ *   // rv.path / rv.segments / rv.formKey / rv.formInstanceId / rv.innerRef
+ *   // are all reachable directly — no `.value` unwrap.
+ * </script>
+ *
+ * <template>
+ *   <label class="field">
+ *     <span>Email</span>
+ *     <input v-register="rv" />
+ *   </label>
+ * </template>
+ * ```
+ *
+ * Returns a hybrid Proxy: it answers `__v_isRef` / `.value` like a
+ * Vue `Ref<RegisterValue | undefined>` (so templates auto-unwrap
+ * correctly and `v-register="rv"` feeds the underlying RV to the
+ * directive — preserving the directive's path-migration diff across
+ * renders), AND every other property read pierces to the captured
+ * RV's field (so `rv.path` works directly in script setup). Reads
+ * inside reactive scopes (`computed` / `watchEffect`) track the
+ * underlying `shallowRef`, so `rv.path` re-runs when the parent
+ * rebinds to a different path.
+ *
+ * Unbound state: when the parent didn't pass `v-register`, every
+ * piercing read returns `undefined` at runtime, and the return type
+ * surfaces this honestly as `UseRegisterReturn<V> | undefined`.
+ * Consumers defend with optional chaining (`rv?.formKey`,
+ * `rv?.segments`); the directive accepts `undefined` peacefully (its
+ * binding value type is already `RegisterValue<V> | undefined`), so
+ * `v-register="rv"` works whether or not a parent has bound. The
+ * composable's `onMounted` warn fires once per instance to surface
+ * the misuse case at runtime.
+ *
+ * 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
+ * binding is conclusive misuse. The warn does NOT fire on every read
+ * of the proxy, and is intentionally silent under SSR
+ * (`renderToString` skips `onMounted`); the CSR hydration pass
+ * surfaces the same diagnostic without double-counting through Nuxt's
+ * `dev:ssr-logs` channel.
+ *
+ * When the wrapper's root IS the input itself, Vue's attribute
+ * fallthrough handles the binding and `useRegister` is unnecessary.
+ * For wrappers that bind multiple fields (compound forms), use
+ * `injectForm<Form>(key?)` and call `ctx.register(...)` directly.
+ */
+
+/**
+ * Return type of `useRegister()`. Hybrid of `RegisterValue<V>` (so
+ * `rv.path` / `rv.segments` / `rv.formKey` etc. work directly in
+ * script setup) and `Ref<RegisterValue<V> | undefined>` (so Vue's
+ * template auto-unwrap surfaces the underlying RV to `v-register`
+ * and the directive's path-migration diff sees the real RV across
+ * renders).
+ *
+ * The two surfaces don't clash at the type level: `RegisterValue`
+ * doesn't carry a `value` field, and `Ref<T>`'s `value: T` becomes
+ * 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;
+
 /**
  * Multistep-form orchestrator built around an ordered list of step slots.
  * Each slot resolves to a participating form: an existing `useForm`
@@ -1543,83 +1628,6 @@ declare function injectWizard(input?: string | InjectWizardInput): UseWizardRetu
  */
 declare function lazy<Ctx = WizardCtx>(resolve: (ctx: Ctx) => AnyForm | string | undefined): LazyMarker<Ctx>;
 
-/**
- * Re-bind a parent's `v-register` onto an inner native element. Use
- * inside a component that wraps a single form field whose root is
- * NOT the input itself (e.g. a labelled-row that renders `<label>`
- * around the input).
- *
- * ```vue
- * <!-- Parent -->
- * <MyInput v-register="form.register('email')" />
- *
- * <!-- MyInput.vue -->
- * <script setup lang="ts">
- *   import { useRegister } from 'attaform'
- *   const rv = useRegister()
- *   // rv.path / rv.segments / rv.formKey / rv.formInstanceId / rv.innerRef
- *   // are all reachable directly — no `.value` unwrap.
- * </script>
- *
- * <template>
- *   <label class="field">
- *     <span>Email</span>
- *     <input v-register="rv" />
- *   </label>
- * </template>
- * ```
- *
- * Returns a hybrid Proxy: it answers `__v_isRef` / `.value` like a
- * Vue `Ref<RegisterValue | undefined>` (so templates auto-unwrap
- * correctly and `v-register="rv"` feeds the underlying RV to the
- * directive — preserving the directive's path-migration diff across
- * renders), AND every other property read pierces to the captured
- * RV's field (so `rv.path` works directly in script setup). Reads
- * inside reactive scopes (`computed` / `watchEffect`) track the
- * underlying `shallowRef`, so `rv.path` re-runs when the parent
- * rebinds to a different path.
- *
- * Unbound state: when the parent didn't pass `v-register`, every
- * piercing read returns `undefined` at runtime, and the return type
- * surfaces this honestly as `UseRegisterReturn<V> | undefined`.
- * Consumers defend with optional chaining (`rv?.formKey`,
- * `rv?.segments`); the directive accepts `undefined` peacefully (its
- * binding value type is already `RegisterValue<V> | undefined`), so
- * `v-register="rv"` works whether or not a parent has bound. The
- * composable's `onMounted` warn fires once per instance to surface
- * the misuse case at runtime.
- *
- * 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
- * binding is conclusive misuse. The warn does NOT fire on every read
- * of the proxy, and is intentionally silent under SSR
- * (`renderToString` skips `onMounted`); the CSR hydration pass
- * surfaces the same diagnostic without double-counting through Nuxt's
- * `dev:ssr-logs` channel.
- *
- * When the wrapper's root IS the input itself, Vue's attribute
- * fallthrough handles the binding and `useRegister` is unnecessary.
- * For wrappers that bind multiple fields (compound forms), use
- * `injectForm<Form>(key?)` and call `ctx.register(...)` directly.
- */
-
-/**
- * Return type of `useRegister()`. Hybrid of `RegisterValue<V>` (so
- * `rv.path` / `rv.segments` / `rv.formKey` etc. work directly in
- * script setup) and `Ref<RegisterValue<V> | undefined>` (so Vue's
- * template auto-unwrap surfaces the underlying RV to `v-register`
- * and the directive's path-migration diff sees the real RV across
- * renders).
- *
- * The two surfaces don't clash at the type level: `RegisterValue`
- * doesn't carry a `value` field, and `Ref<T>`'s `value: T` becomes
- * 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;
-
 /**
  * Stable identifiers for library-emitted `ValidationError` codes.
  *
@@ -1680,5 +1688,5 @@ declare const AttaformErrorCode: {
 };
 type AttaformErrorCode = (typeof AttaformErrorCode)[keyof typeof AttaformErrorCode];
 
-export { AttaformErrorCode as b, createRegistry as p, defaultCoercionRules as q, defineCoercion as r, getRegistryFromApp as s, injectForm as t, injectWizard as u, kAttaformRegistry as v, lazy as w, useRegister as x, useRegistry as y, useWizard as z };
-export type { AggregateError as A, CompiledStep as C, FormStatus as F, InjectWizardInput as I, LazyMarker as L, SSRDetectOptions as S, UseRegisterReturn as U, WizardCtx as W, AnyForm as a, AttaformRegistry as c, SerializedFormData as d, StepSlot as e, UseWizardReturnType as f, WizardCtxForm as g, WizardOnError as h, WizardOnSubmit as i, WizardOptions as j, WizardPersistFn as k, WizardRestoreFn as l, WizardRestoreState as m, WizardStatusesProxy as n, WizardSubmitContext as o };
+export { AttaformErrorCode as a, createRegistry as p, defaultCoercionRules as q, defineCoercion as r, getRegistryFromApp as s, injectForm as t, injectWizard as u, kAttaformRegistry as v, lazy as w, useRegister as x, useRegistry as y, useWizard as z };
+export type { AnyForm as A, CompiledStep as C, FormStatus as F, InjectWizardInput as I, LazyMarker as L, SSRDetectOptions as S, UseRegisterReturn as U, WizardAggregateError as W, AttaformRegistry as b, SerializedFormData as c, StepSlot as d, UseWizardReturnType as e, WizardCtx as f, WizardCtxForm as g, WizardOnError as h, WizardOnSubmit as i, WizardOptions as j, WizardPersistFn as k, WizardRestoreFn as l, WizardRestoreState as m, WizardStatusesProxy as n, WizardSubmitContext as o };

package/dist/shared/attaform.EZG6fOFb.mjs

@@ -0,0 +1,35 @@
+import { r as getRegistryFromApp, C as pathKeyToDotted } from './attaform.BKozEdTr.mjs';
+
+function renderAttaformState(app) {
+  const registry = getRegistryFromApp(app);
+  const forms = [];
+  for (const [key, state] of registry.forms) {
+    const transientList = [];
+    for (const pk of state.blankPaths) {
+      const d = pathKeyToDotted(pk);
+      if (d !== null) transientList.push(d);
+    }
+    forms.push([
+      key,
+      {
+        form: state.form.value,
+        schemaErrors: Array.from(state.schemaErrors.entries()),
+        userErrors: Array.from(state.userErrors.entries()),
+        fields: Array.from(state.fields.entries()),
+        ...transientList.length > 0 ? { blankPaths: transientList } : {}
+      }
+    ]);
+  }
+  return { forms };
+}
+function hydrateAttaformState(app, payload) {
+  const registry = getRegistryFromApp(app);
+  for (const [key, data] of payload.forms) {
+    registry.pendingHydration.set(key, data);
+  }
+}
+
+const DEVTOOLS_WINDOW_KEY = "__attaform_devtools__";
+
+export { DEVTOOLS_WINDOW_KEY as D, hydrateAttaformState as h, renderAttaformState as r };
+//# sourceMappingURL=attaform.EZG6fOFb.mjs.map

package/dist/shared/attaform.EZG6fOFb.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"attaform.EZG6fOFb.mjs","sources":["../../src/runtime/core/serialize.ts","../../src/runtime/core/devtools-shared.ts"],"sourcesContent":["import type { App } from 'vue'\nimport type { FormKey } from '../types/types-api'\nimport { pathKeyToDotted, type PathKey } from './paths'\nimport { getRegistryFromApp, type SerializedFormData } from './registry'\n\n/**\n * Serialised snapshot of every form in a Vue app, produced by\n * `renderAttaformState` and consumed by `hydrateAttaformState`.\n *\n * JSON-safe — pass to `JSON.stringify`, `devalue`, or any other\n * serialiser before embedding in your SSR payload.\n */\nexport type SerializedAttaformState = {\n  /** Tuples of `[formKey, snapshot]` for every form in the app. */\n  readonly forms: ReadonlyArray<readonly [FormKey, SerializedFormData]>\n}\n\n/**\n * Snapshot every form on a Vue app for SSR. Call from your server\n * entry after rendering the app:\n *\n * ```ts\n * import { renderToString } from '@vue/server-renderer'\n * import { renderAttaformState, escapeForInlineScript } from 'attaform'\n *\n * const html = await renderToString(app)\n * const state = renderAttaformState(app)\n * const payload = escapeForInlineScript(JSON.stringify(state))\n *\n * return `\n *   ${html}\n *   <script>window.__ATTAFORM_STATE__ = ${payload}</script>\n * `\n * ```\n *\n * Pair with `hydrateAttaformState` on the client to restore the\n * forms in their server-rendered state. Nuxt users don't need this —\n * `attaform/nuxt` wires SSR automatically.\n */\nexport function renderAttaformState(app: App): SerializedAttaformState {\n  const registry = getRegistryFromApp(app)\n  const forms: Array<readonly [FormKey, SerializedFormData]> = []\n  for (const [key, state] of registry.forms) {\n    // Skip the blank field when the set is empty so the\n    // wire payload stays minimal for forms that don't use it. The\n    // optional shape on the consuming side handles the absence\n    // cleanly (defaults to \"no blank paths\"). PathKey → dotted at\n    // the boundary so the wire shape matches the rest of the\n    // public path notation.\n    const transientList: string[] = []\n    for (const pk of state.blankPaths) {\n      const d = pathKeyToDotted(pk as PathKey)\n      if (d !== null) transientList.push(d)\n    }\n    forms.push([\n      key,\n      {\n        form: state.form.value,\n        schemaErrors: Array.from(state.schemaErrors.entries()),\n        userErrors: Array.from(state.userErrors.entries()),\n        fields: Array.from(state.fields.entries()),\n        ...(transientList.length > 0 ? { blankPaths: transientList } : {}),\n      },\n    ])\n  }\n  return { forms }\n}\n\n/**\n * Restore forms from a server-rendered snapshot on the client. Call\n * from your client entry before mounting:\n *\n * ```ts\n * import { createApp } from 'vue'\n * import { createAttaform, hydrateAttaformState } from 'attaform'\n *\n * const app = createApp(App).use(createAttaform())\n * hydrateAttaformState(app, window.__ATTAFORM_STATE__)\n * app.mount('#app')\n * ```\n *\n * The next `useForm({ key })` call for each serialised form picks up\n * the snapshot transparently — no further action is required.\n */\nexport function hydrateAttaformState(app: App, payload: SerializedAttaformState): void {\n  const registry = getRegistryFromApp(app)\n  for (const [key, data] of payload.forms) {\n    registry.pendingHydration.set(key, data)\n  }\n}\n","/**\n * Shared building blocks for Attaform's two devtools surfaces — the Vue\n * DevTools (Chrome-extension) inspector wired up in `./devtools.ts`, and\n * the Nuxt DevTools (overlay) panel wired up via `../../nuxt.ts` +\n * `../pages/_attaform_devtools.vue`.\n *\n * Houses the window-bridge contract both surfaces consume so a new\n * bridge field lands in one file. Both surfaces render RAW form values\n * by design — DevTools is a dev-only surface, and redaction across every\n * place a value surfaces is impractical security theater rather than a\n * real safeguard.\n */\nimport type { AttaformRegistry } from './registry'\n\n/**\n * Property key on `window` that the Nuxt-side dev plugin attaches the\n * bridge object to. The iframe-mounted overlay panel reads\n * `window.parent[DEVTOOLS_WINDOW_KEY]` to reach the host app's registry.\n *\n * Underscored + namespaced to make accidental collision with consumer\n * globals vanishingly unlikely. Stable across versions — bumping it\n * would silently disconnect older library builds from newer overlay\n * panels in the same browser tab during a library upgrade.\n */\nexport const DEVTOOLS_WINDOW_KEY = '__attaform_devtools__'\n\n/**\n * Shape of the object the host plugin attaches to `window` in dev mode.\n * The iframe overlay panel reads this to discover the live registry and\n * render its forms.\n *\n * Single-registry assumption: the latest `createAttaform()` install\n * wins. Multi-app pages (rare; typically only seen in micro-frontend\n * setups) will only see one app's forms in the panel. Documented but\n * not actively supported — the alternative (a Set of registries with\n * union-rendering) is a future call if a real consumer hits it.\n */\nexport interface AttaformDevtoolsBridge {\n  registry: AttaformRegistry\n  /**\n   * The library version, surfaced in the panel's footer for support /\n   * bug-report context. Read from `package.json` at host-plugin init.\n   */\n  version: string\n}\n\ndeclare global {\n  interface Window {\n    [DEVTOOLS_WINDOW_KEY]?: AttaformDevtoolsBridge\n  }\n}\n"],"names":[],"mappings":";;AAuCO,SAAS,oBAAoB,GAAA,EAAmC;AACrE,EAAA,MAAM,QAAA,GAAW,mBAAmB,GAAG,CAAA;AACvC,EAAA,MAAM,QAAuD,EAAC;AAC9D,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,CAAA,IAAK,SAAS,KAAA,EAAO;AAOzC,IAAA,MAAM,gBAA0B,EAAC;AACjC,IAAA,KAAA,MAAW,EAAA,IAAM,MAAM,UAAA,EAAY;AACjC,MAAA,MAAM,CAAA,GAAI,gBAAgB,EAAa,CAAA;AACvC,MAAA,IAAI,CAAA,KAAM,IAAA,EAAM,aAAA,CAAc,IAAA,CAAK,CAAC,CAAA;AAAA,IACtC;AACA,IAAA,KAAA,CAAM,IAAA,CAAK;AAAA,MACT,GAAA;AAAA,MACA;AAAA,QACE,IAAA,EAAM,MAAM,IAAA,CAAK,KAAA;AAAA,QACjB,cAAc,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,YAAA,CAAa,SAAS,CAAA;AAAA,QACrD,YAAY,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,UAAA,CAAW,SAAS,CAAA;AAAA,QACjD,QAAQ,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,MAAA,CAAO,SAAS,CAAA;AAAA,QACzC,GAAI,cAAc,MAAA,GAAS,CAAA,GAAI,EAAE,UAAA,EAAY,aAAA,KAAkB;AAAC;AAClE,KACD,CAAA;AAAA,EACH;AACA,EAAA,OAAO,EAAE,KAAA,EAAM;AACjB;AAkBO,SAAS,oBAAA,CAAqB,KAAU,OAAA,EAAwC;AACrF,EAAA,MAAM,QAAA,GAAW,mBAAmB,GAAG,CAAA;AACvC,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,IAAI,CAAA,IAAK,QAAQ,KAAA,EAAO;AACvC,IAAA,QAAA,CAAS,gBAAA,CAAiB,GAAA,CAAI,GAAA,EAAK,IAAI,CAAA;AAAA,EACzC;AACF;;ACjEO,MAAM,mBAAA,GAAsB;;;;"}

package/dist/shared/{attaform.QvygsFGh.d.cts → attaform.GbDo_lJi.d.cts}

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { G as GenericForm, q as FlatPath, B as NestedType, t as FormKey, ai as UseFormConfiguration, A as AbstractSchema, j as DefaultValuesInput, al as ValidateOnConfig, aj as UseFormReturnType } from './attaform.C0uGZQ4M.cjs';
+import { G as GenericForm, q as FlatPath, B as NestedType, t as FormKey, ai as UseFormConfiguration, A as AbstractSchema, j as DefaultValuesInput, al as ValidateOnConfig, aj as UseFormReturnType } from './attaform.SfhU0OEY.cjs';
 
 /**
  * The shape `form.values.<key>` returns at runtime.

package/dist/shared/{attaform.C0uGZQ4M.d.ts → attaform.SfhU0OEY.d.cts}

@@ -136,6 +136,28 @@ declare function isUnset(value: unknown): value is Unset;
 type GenericForm = Record<string, unknown>;
 /** Internal helper — `true` when `T` is an object or array. */
 type IsObjectOrArray<T> = T extends GenericForm ? true : T extends Array<unknown> ? true : false;
+/**
+ * Shared recursion body backing `PartialFlatPath` and `RegisterFlatPath`.
+ * One walk over `Form`; `Mode` controls whether intermediate container
+ * paths are emitted alongside their reachable leaves.
+ *
+ * - `'partial'`: emit every container path (object containers, nested-
+ *   object array roots, array-of-object element containers). Used by
+ *   `setValue` / `form.values.<path>` / every read-side API that needs
+ *   to address a container.
+ * - `'register'`: skip container paths. `v-register` binds onto a
+ *   leaf-backing native element (`<input>`, `<select>`, `<textarea>`),
+ *   so container paths aren't registrable. Primitive arrays still
+ *   admit the array-root path under both modes (multi-select and
+ *   grouped-checkbox bindings register onto the array itself).
+ *
+ * Both walkers were independent recursions before; threading `Mode`
+ * through one body keeps the surface guarded by a single source of
+ * truth, and `PartialFlatPath` / `RegisterFlatPath` stay byte-
+ * identical to the prior hand-written walks (see
+ * `test/types/flat-path-walker.test.ts`).
+ */
+type FlatPathBuilder<Form, Mode extends 'partial' | 'register', Key extends keyof Form = keyof Form> = IsObjectOrArray<Form> extends true ? Key extends string ? Form[Key] extends infer Value ? Value extends Array<infer ArrayItem> ? IsObjectOrArray<ArrayItem> extends true ? Mode extends 'partial' ? `${Key}` | `${Key}.${number}` | `${Key}.${number}.${FlatPathBuilder<ArrayItem, Mode>}` : `${Key}.${number}.${FlatPathBuilder<ArrayItem, Mode>}` : `${Key}` | `${Key}.${number}` : Value extends GenericForm ? Mode extends 'partial' ? `${Key}` | `${Key}.${FlatPathBuilder<Value, Mode>}` : `${Key}.${FlatPathBuilder<Value, Mode>}` : `${Key}` : never : Key extends number ? `${Key}` | (Form[Key] extends GenericForm ? `${Key}.${FlatPathBuilder<Form[Key], Mode>}` : Form[Key] extends Array<infer ArrayItem> ? IsObjectOrArray<ArrayItem> extends true ? Mode extends 'partial' ? `${Key}.${number}` | `${Key}.${number}.${FlatPathBuilder<ArrayItem, Mode>}` : `${Key}.${number}.${FlatPathBuilder<ArrayItem, Mode>}` : `${Key}.${number}` : never) : never : never;
 /**
  * Implementation detail backing `FlatPath` in its default
  * (partial-path) mode. Exported so `rollup-plugin-dts` preserves it
@@ -146,8 +168,7 @@ type IsObjectOrArray<T> = T extends GenericForm ? true : T extends Array<unknown
  * when multiple complex forms share a scope. Consumers should reach
  * for `FlatPath` instead; this alias is not part of the stable surface.
  */
-type PartialFlatPath<Form, Key extends keyof Form = keyof Form> = IsObjectOrArray<Form> extends true ? Key extends string ? Form[Key] extends infer Value ? Value extends Array<infer ArrayItem> ? `${Key}` | `${Key}.${number}` | `${Key}.${number}.${PartialFlatPath<ArrayItem>}` : Value extends GenericForm ? `${Key}` | `${Key}.${PartialFlatPath<Value>}` : `${Key}` : never : Key extends number ? `${Key}` | (Form[Key] extends GenericForm ? `${Key}.${PartialFlatPath<Form[Key]>}` : Form[Key] extends Array<infer ArrayItem> ? IsObjectOrArray<ArrayItem> extends true ? `${Key}.${number}` | `${Key}.${number}.${PartialFlatPath<ArrayItem>}` : `${Key}.${number}` : never) : never : never;
-type CompleteFlatPath<Form, Key extends keyof Form = keyof Form> = IsObjectOrArray<Form> extends true ? Key extends string ? Form[Key] extends infer Value ? Value extends Array<infer ArrayItem> ? `${Key}.${number}.${CompleteFlatPath<ArrayItem>}` : Value extends GenericForm ? `${Key}.${CompleteFlatPath<Value>}` : `${Key}` : never : Key extends number ? `${Key}` | (Form[Key] extends GenericForm ? `${Key}.${CompleteFlatPath<Form[Key]>}` : Form[Key] extends Array<infer ArrayItem> ? IsObjectOrArray<ArrayItem> extends true ? `${Key}.${number}.${CompleteFlatPath<ArrayItem>}` : `${Key}.${number}` : never) : never : never;
+type PartialFlatPath<Form, Key extends keyof Form = keyof Form> = FlatPathBuilder<Form, 'partial', Key>;
 /**
  * Union of dotted-string paths reachable inside `Form`, e.g. for
  * `{ user: { email: string }, items: string[] }`:
@@ -157,11 +178,8 @@ type CompleteFlatPath<Form, Key extends keyof Form = keyof Form> = IsObjectOrArr
  * Used by every path-addressed API (`setValue(path, value)`,
  * `register(path)`, `toRef(path)`, etc.) so paths autocomplete in
  * the IDE and typos compile-error.
- *
- * Set `ForceFullPath` to `true` to restrict to leaf paths only
- * (no intermediate container paths).
  */
-type FlatPath<Form, Key extends keyof Form = keyof Form, ForceFullPath extends boolean = false> = ForceFullPath extends true ? CompleteFlatPath<Form, Key> : PartialFlatPath<Form, Key>;
+type FlatPath<Form, Key extends keyof Form = keyof Form> = PartialFlatPath<Form, Key>;
 /**
  * Convert a tuple of path segments to its dotted-string equivalent.
  *
@@ -251,6 +269,31 @@ type LiftedValueShape<T> = [T] extends [
 type DeepPartial<T> = T extends Primitive ? T : T extends Array<infer ArrayItem> ? DeepPartial<ArrayItem>[] : T extends object ? {
     [Key in keyof T]?: DeepPartial<T[Key]>;
 } : T;
+/**
+ * Shared descent body backing `NestedType` and `NestedReadType`. The
+ * recursion is identical — segment-by-segment, distributing over
+ * union members via `KeyofUnion` / `ValueOfUnion`. The two walkers
+ * diverge only at the leaf:
+ *
+ * - `TaintArrayCrossings extends false` (`NestedType` mode): leaves
+ *   are returned untouched. Used by strict write-side APIs that need
+ *   the exact resolved type (`setValue`'s value parameter,
+ *   `form.fields.<path>`'s state map).
+ * - `TaintArrayCrossings extends true` (`NestedReadType` mode): leaves
+ *   are widened with `| undefined` whenever any segment in the walk
+ *   was numeric (array index). Reflects the runtime possibility of an
+ *   out-of-bounds read.
+ *
+ * `_Tainted` propagates the array-crossing under taint mode; under
+ * strict mode it stays `false` through every recursion arm. Both
+ * arms strip nullishness at the root (`_RootValue = NonNullable<…>`)
+ * — the prior `NestedType.FilterOutNullishTypesDuringRecursion` flag
+ * was vestigial, never overridden from the outside.
+ *
+ * Not part of the stable consumer surface — reach for `NestedType` or
+ * `NestedReadType` directly.
+ */
+type NestedTypeBuilder<RootValue, FlattenedPath extends string, TaintArrayCrossings extends boolean, _Tainted extends boolean = false, _RootValue = NonNullable<RootValue>> = IsObjectOrArray<_RootValue> extends false ? never : FlattenedPath extends `${infer Key}.${infer Rest}` ? Key extends `${number}` ? Key extends KeyofUnion<_RootValue> ? NestedTypeBuilder<ValueOfUnion<_RootValue, Key>, Rest, TaintArrayCrossings, TaintArrayCrossings extends true ? true : _Tainted> : Key extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? NestedTypeBuilder<ValueOfUnion<_RootValue, NumericKey>, Rest, TaintArrayCrossings, TaintArrayCrossings extends true ? true : _Tainted> : never : never : Key extends KeyofUnion<_RootValue> ? NestedTypeBuilder<ValueOfUnion<_RootValue, Key>, Rest, TaintArrayCrossings, _Tainted> : never : FlattenedPath extends `${number}` ? FlattenedPath extends KeyofUnion<_RootValue> ? TaintArrayCrossings extends true ? ValueOfUnion<_RootValue, FlattenedPath> | undefined : ValueOfUnion<_RootValue, FlattenedPath> : FlattenedPath extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? TaintArrayCrossings extends true ? ValueOfUnion<_RootValue, NumericKey> | undefined : ValueOfUnion<_RootValue, NumericKey> : never : never : FlattenedPath extends KeyofUnion<_RootValue> ? _Tainted extends true ? ValueOfUnion<_RootValue, FlattenedPath> | undefined : ValueOfUnion<_RootValue, FlattenedPath> : never;
 /**
  * Resolve the type at a dotted-string path inside `RootValue`. Used
  * by the strict (write-side) APIs to derive the type at a path:
@@ -264,11 +307,16 @@ type DeepPartial<T> = T extends Primitive ? T : T extends Array<infer ArrayItem>
  * useful value type (vs. silently collapsing to `never` because
  * `keyof (A|B|C)` would be the intersection of all variants' keys).
  *
+ * Composed over `NestedTypeBuilder` with array-crossing tainting OFF,
+ * so leaves return their exact resolved type. The companion
+ * `NestedReadType` shares the same recursion body but enables
+ * tainting for read-side APIs.
+ *
  * TypeScript caps conditional-type recursion at around 50 levels;
  * paths deeper than that resolve to `never`. Real form schemas
  * never reach this depth.
  */
-type NestedType<RootValue, FlattenedPath extends string, FilterOutNullishTypesDuringRecursion extends boolean = true, _RootValue = FilterOutNullishTypesDuringRecursion extends false ? RootValue : NonNullable<RootValue>> = IsObjectOrArray<_RootValue> extends false ? never : FlattenedPath extends `${infer Key}.${infer Rest}` ? Key extends `${number}` ? Key extends KeyofUnion<_RootValue> ? NestedType<ValueOfUnion<_RootValue, Key>, Rest, FilterOutNullishTypesDuringRecursion> : Key extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? NestedType<ValueOfUnion<_RootValue, NumericKey>, Rest, FilterOutNullishTypesDuringRecursion> : never : never : Key extends KeyofUnion<_RootValue> ? NestedType<ValueOfUnion<_RootValue, Key>, Rest, FilterOutNullishTypesDuringRecursion> : never : FlattenedPath extends `${number}` ? FlattenedPath extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, FlattenedPath> : FlattenedPath extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, NumericKey> : never : never : FlattenedPath extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, FlattenedPath> : never;
+type NestedType<RootValue, FlattenedPath extends string> = NestedTypeBuilder<RootValue, FlattenedPath, false>;
 /**
  * Implementation-detail primitive-leaf marker used by `DeepPartial`
  * and sibling structural walkers. Exported so the bundled `.d.ts`
@@ -300,7 +348,7 @@ type IsTuple<T extends readonly unknown[]> = number extends T['length'] ? false
  * `register(path).innerRef` so the compile-time type honours the
  * runtime possibility of a missing array position.
  */
-type NestedReadType<RootValue, FlattenedPath extends string, _Tainted extends boolean = false, _RootValue = NonNullable<RootValue>> = IsObjectOrArray<_RootValue> extends false ? never : FlattenedPath extends `${infer Key}.${infer Rest}` ? Key extends `${number}` ? Key extends KeyofUnion<_RootValue> ? NestedReadType<ValueOfUnion<_RootValue, Key>, Rest, true> : Key extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? NestedReadType<ValueOfUnion<_RootValue, NumericKey>, Rest, true> : never : never : Key extends KeyofUnion<_RootValue> ? NestedReadType<ValueOfUnion<_RootValue, Key>, Rest, _Tainted> : never : FlattenedPath extends `${number}` ? FlattenedPath extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, FlattenedPath> | undefined : FlattenedPath extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, NumericKey> | undefined : never : never : FlattenedPath extends KeyofUnion<_RootValue> ? _Tainted extends true ? ValueOfUnion<_RootValue, FlattenedPath> | undefined : ValueOfUnion<_RootValue, FlattenedPath> : never;
+type NestedReadType<RootValue, FlattenedPath extends string> = NestedTypeBuilder<RootValue, FlattenedPath, true>;
 /**
  * Filter FlatPath<Form> down to the subset of paths whose resolved leaf
  * is an array. Used by the typed field-array helpers (append / remove /
@@ -388,6 +436,28 @@ type WriteShape<T> = T extends string | number | boolean | bigint | symbol | nul
 } : Array<WriteShape<U>> : T extends object ? {
     [K in keyof T]: WriteShape<T[K]>;
 } : T;
+/**
+ * Walk `T` and add `| Unset` at every primitive leaf (except symbol /
+ * null / undefined), every opaque leaf (`Date`, `RegExp`, `Map`,
+ * `Set`, functions), and every container position (object, tuple,
+ * array). The recursion topology mirrors `WriteShape<T>` exactly —
+ * `DefaultValuesShape<T>` is then a 1-line composition.
+ *
+ * Symbol / null / undefined leaves pass through untouched so the
+ * runtime sentinel doesn't pollute leaf semantics it has no business
+ * carrying. Container positions widen so a single `unset` at any
+ * level recursively marks every descendant primitive blank.
+ *
+ * Not part of the stable consumer-facing surface — reach for
+ * `DefaultValuesShape` instead.
+ */
+type AugmentWithUnset<T> = T extends string | number | boolean | bigint ? T | Unset : T extends symbol | null | undefined ? T : T extends Date | RegExp | Map<unknown, unknown> | Set<unknown> | ((...args: never) => unknown) ? T | Unset : T extends readonly [unknown, ...unknown[]] ? {
+    -readonly [K in keyof T]: AugmentWithUnset<T[K]>;
+} | Unset : T extends ReadonlyArray<infer U> ? IsTuple<T> extends true ? {
+    -readonly [K in keyof T]: AugmentWithUnset<T[K]>;
+} | Unset : Array<AugmentWithUnset<U>> | Unset : T extends object ? {
+    [K in keyof T]: AugmentWithUnset<T[K]>;
+} | Unset : T;
 /**
  * Like `WriteShape<T>`, but additionally widens every primitive leaf
  * (`string`, `number`, `boolean`, `bigint`) to admit `Unset` — the
@@ -401,8 +471,10 @@ type WriteShape<T> = T extends string | number | boolean | bigint | symbol | nul
  * descendant blank, so `defaultValues: { profile: unset }` and
  * `setValue('cargo', unset)` typecheck cleanly.
  *
- * The recursion mirrors `WriteShape<T>` exactly so `defaultValues`
- * stays compatible at every nested position. Tuple positions,
+ * Composed as `AugmentWithUnset<WriteShape<T>>`: stage 1 widens
+ * primitive literals, stage 2 adds `| Unset` everywhere — the prior
+ * inline walker hand-synced this in a single body. The composition
+ * stays compatible at every nested position; tuple positions,
  * unbounded arrays, and nested records all flow through unchanged.
  *
  * Example:
@@ -413,13 +485,7 @@ type WriteShape<T> = T extends string | number | boolean | bigint | symbol | nul
  * Used by `UseFormConfiguration.defaultValues`, `setValue`'s value
  * parameter, and `reset`'s parameter.
  */
-type DefaultValuesShape<T> = T extends string | number | boolean | bigint | symbol | null | undefined ? T extends string ? string | Unset : T extends number ? number | Unset : T extends boolean ? boolean | Unset : T extends bigint ? bigint | Unset : T extends symbol ? symbol : T : T extends Date | RegExp | Map<unknown, unknown> | Set<unknown> | ((...args: never) => unknown) ? T | Unset : T extends readonly [unknown, ...unknown[]] ? {
-    -readonly [K in keyof T]: DefaultValuesShape<T[K]>;
-} | Unset : T extends ReadonlyArray<infer U> ? IsTuple<T> extends true ? {
-    -readonly [K in keyof T]: DefaultValuesShape<T[K]>;
-} | Unset : Array<DefaultValuesShape<U>> | Unset : T extends object ? {
-    [K in keyof T]: DefaultValuesShape<T[K]>;
-} | Unset : T;
+type DefaultValuesShape<T> = AugmentWithUnset<WriteShape<T>>;
 /**
  * Single-walker fusion of `DeepPartial` and `DefaultValuesShape` — the
  * type accepted at `defaultValues`, `reset()`'s parameter, and every
@@ -713,6 +779,15 @@ type MaybePromise<T> = T | Promise<T>;
 type ValidateOptions = {
     sync?: boolean;
 };
+/**
+ * Configuration passed to `AbstractSchema.getDefaultValues`. Adapters
+ * receive `useDefaultSchemaValues` (honor `.default(x)` wrappers vs.
+ * empty/falsy fallbacks), an optional `strict` mode (refinement
+ * preservation), and an optional `constraints` overlay merged into the
+ * derived defaults so the runtime can stamp user-supplied defaults at
+ * construction. Exported so adapter authors can co-implement the
+ * service contract.
+ */
 type GetDefaultValuesConfig<Form> = {
     useDefaultSchemaValues: boolean;
     /**
@@ -1092,6 +1167,32 @@ type AbstractSchema<Form, GetValueFormType> = {
      * answers without a separate top-level overload.
      */
     needsAsyncValidation?(): boolean;
+    /**
+     * Return `true` iff the schema carries a refine / check / transform
+     * at any NON-LEAF position — a container node (object / array /
+     * tuple / union / intersection / record / map / set) or the root
+     * itself. False means every check this schema runs is leaf-local,
+     * so a per-keystroke `validateAtPath(form, leafPath)` catches the
+     * same verdicts as a whole-form pass — no ancestor refine reads
+     * the form's wider state.
+     *
+     * The runtime uses this at the per-keystroke schedule to scope
+     * field-level validation to the changed subtree when it can,
+     * falling back to a whole-form pass when an ancestor refine
+     * (cross-field equality, sum constraints, etc.) could be moved
+     * by a leaf write. Optional. The runtime treats a missing
+     * implementation as `() => true` — conservative whole-form,
+     * preserving correctness for adapters that don't yet model
+     * container-refine detection.
+     *
+     * Detection is best-effort: false negatives (returning `true`
+     * when no container refine exists) only lose a perf win and
+     * still validate correctly; false positives (returning `false`
+     * when a container refine exists) would let an ancestor verdict
+     * go stale and are the real risk — implementations should bias
+     * toward returning `true` when in doubt.
+     */
+    hasContainerOrRootRefine?(): boolean;
 };
 /**
  * Adapter-returned info for a discriminated union — its discriminator
@@ -1795,8 +1896,9 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
     maxRecursionDepth?: number;
     /**
      * Override the path-segment name stems treated as sensitive for this
-     * form. Sensitive paths are excluded from persistence writes,
-     * multi-tab sync broadcasts, AND the DevTools redact walk.
+     * form. Sensitive paths are excluded from persistence writes and
+     * multi-tab sync broadcasts. (DevTools renders raw values by design;
+     * it does not redact.)
      *
      * Resolution: per-form value (this field) > global default
      * (`createAttaform({ defaults: { sensitiveNames } })`) > library
@@ -2022,9 +2124,10 @@ type AttaformDefaults = {
     maxRecursionDepth?: number;
     /**
      * Override the path-segment name stems treated as sensitive.
-     * Sensitive paths are excluded from persistence writes, multi-tab
-     * sync broadcasts, AND the DevTools redact walk — one configurable
-     * source of truth across every surface.
+     * Sensitive paths are excluded from persistence writes and multi-tab
+     * sync broadcasts — one configurable source of truth across those
+     * surfaces. (DevTools renders raw values by design; it does not
+     * redact.)
      *
      * Library default is `DEFAULT_SENSITIVE_NAMES` (exported from
      * `attaform`); compose to extend:
@@ -2235,7 +2338,7 @@ type MetaTrackerValue = {
      */
     blank: boolean;
 };
-type RegisterFlatPath<Form, Key extends keyof Form = keyof Form> = IsObjectOrArray<Form> extends true ? Key extends string ? Form[Key] extends infer Value ? Value extends Array<infer ArrayItem> ? IsObjectOrArray<ArrayItem> extends true ? `${Key}.${number}.${RegisterFlatPath<ArrayItem>}` : `${Key}` | `${Key}.${number}` : Value extends GenericForm ? `${Key}.${RegisterFlatPath<Value>}` : `${Key}` : never : Key extends number ? `${Key}` | (Form[Key] extends GenericForm ? `${Key}.${RegisterFlatPath<Form[Key]>}` : Form[Key] extends Array<infer ArrayItem> ? IsObjectOrArray<ArrayItem> extends true ? `${Key}.${number}.${RegisterFlatPath<ArrayItem>}` : `${Key}` | `${Key}.${number}` : never) : never : never;
+type RegisterFlatPath<Form, Key extends keyof Form = keyof Form> = FlatPathBuilder<Form, 'register', Key>;
 /**
  * Sync transformation applied to a field's value as user input flows
  * from DOM through the directive's assigner. Composes left-to-right
@@ -2341,9 +2444,10 @@ type RegisterOptions = {
      * If multiple inputs bind to the same path, the path keeps
      * persisting as long as any opted-in input is mounted.
      *
-     * Throws `SensitivePersistFieldError` when the path looks
-     * sensitive (password / cvv / ssn / token / etc.) unless
-     * `acknowledgeSensitive: true` is also set.
+     * When the path looks sensitive (password / cvv / ssn / token /
+     * etc.) the opt-in is skipped with a one-shot dev warning unless
+     * `acknowledgeSensitive: true` is also set — the field simply isn't
+     * persisted (the secure default). It never throws.
      */
     persist?: boolean;
     /**
@@ -2528,7 +2632,7 @@ type RegisterValue<Value = unknown> = Readonly<{
     /**
      * Resolved sensitive-path predicate honoring this form's
      * `sensitiveNames` cascade. The directive calls this through
-     * `enforceSensitiveCheck` when a `register('path', { persist: true })`
+     * `allowSensitivePersist` when a `register('path', { persist: true })`
      * binding mounts so a per-form custom list (e.g. extending with
      * `'mrn'`) gates persistence enrolment correctly.
      * @internal
@@ -4347,9 +4451,9 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * paths in the persisted draft are preserved (this is a merge,
      * not a replace).
      *
-     * Throws `SensitivePersistFieldError` for sensitive-looking paths
-     * unless you pass `{ acknowledgeSensitive: true }`. No-op when
-     * `useForm({ persist })` wasn't configured.
+     * For sensitive-looking paths, warns once and no-ops unless you pass
+     * `{ acknowledgeSensitive: true }` — it never throws. Also a no-op
+     * when `useForm({ persist })` wasn't configured.
      */
     persist: (path: FlatPath<Form>, options?: {
         acknowledgeSensitive?: boolean;