attaform 0.20.1 → 0.21.0

package/dist/shared/{attaform.SfhU0OEY.d.cts → attaform.B1nyO4ec.d.mts}

@@ -814,6 +814,12 @@ type AbstractSchema<Form, GetValueFormType> = {
      * Structural fingerprint of the schema. Same shape → same string;
      * different shape → (best-effort) different string.
      *
+     * Resolves a `Promise` so adapters can defer the structural walk (and
+     * its `canonicalStringify` helper) onto a dynamic import. The framework
+     * only ever needs the fingerprint on opt-in async paths (the multi-tab
+     * channel name, the persistence storage key) plus a dev-only mismatch
+     * warning, so none of those bytes belong on the eager `useForm` path.
+     *
      * The library uses this to detect schema mismatches at a shared
      * form key: two `useForm({ key: 'x', schema })` calls are allowed
      * to land on the same `FormStore` (the "shared store" semantic),
@@ -841,7 +847,7 @@ type AbstractSchema<Form, GetValueFormType> = {
      *   look identical. The warning is a footgun catcher, not a
      *   soundness guarantee.
      */
-    fingerprint(): string;
+    fingerprint(): Promise<string>;
     getDefaultValues(config: GetDefaultValuesConfig<Form>): DefaultValuesResponse<Form>;
     /**
      * Return the schema-prescribed default value at the given path. The
@@ -2047,29 +2053,31 @@ type AttaformDefaults = {
      *   useForm({ getDisplayState })  >  AttaformDefaults  >  library default
      *
      * The library default opens one timing gate, then resolves by
-     * precedence: gate closed → `'idle'`; a run in flight → `'pending'`;
-     * an own-path error → `'error'`; otherwise `valid` → `'success'`, else
-     * `'idle'`. The gate opens after the first submit attempt OR once the
-     * field is touched and not currently focused:
+     * precedence: gate closed → `'idle'`; a run in flight → a delayed
+     * `'pending'` (held briefly to smooth fast validations, then held a
+     * minimum so it never flashes); an own-path error → `'error'`;
+     * otherwise earned `valid` → `'success'`, else `'idle'`. The gate opens
+     * after the first submit attempt OR once the field is edited and left:
      *
      * ```ts
-     * (field, formMeta) => {
+     * (prev, ctx) => {
      *   const gateOpen =
-     *     formMeta.submissionAttempts > 0 ||
-     *     (field.touched === true && field.focused !== true)
-     *   if (!gateOpen) return 'idle'
-     *   if (field.validating === true) return 'pending'
-     *   // ...own-path error → 'error'; valid → 'success'; else 'idle'
+     *     ctx.formMeta.submissionAttempts > 0 ||
+     *     ctx.field.blurredAfterInteraction === true
+     *   if (!gateOpen) return { display: 'idle' }
+     *   // ...timed 'pending' while validating; own-path error → 'error';
+     *   //    earned valid → 'success'; else 'idle'
      * }
      * ```
      *
      * Compose with the library default via the public `defaultDisplayState`
-     * export. The predicate runs on every field-state read, so it owns the
+     * export, or retune its timing via `makeDefaultDisplayState`. The
+     * reducer runs on every field-state read, so it owns the
      * idle / pending / error / success decision outright.
      *
-     * The predicate's args are `Omit`'d of the derived `displayState` /
-     * `show*` / `firstError` keys (see `FieldStateDerivedKey`) to prevent
-     * a self-referential predicate.
+     * The reducer's `ctx.field` / `ctx.formMeta` are `Omit`'d of the
+     * derived `displayState` / `show*` / `firstError` keys (see
+     * `FieldStateDerivedKey`) to prevent a self-referential reducer.
      */
     getDisplayState?: GetDisplayState;
     /**
@@ -2230,16 +2238,58 @@ type DisplayState = 'idle' | 'pending' | 'error' | 'success';
  */
 type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError';
 /**
- * Predicate that resolves a path's `displayState`. Receives the field's
- * reactive state plus the form's reactive meta (both minus the derived
- * `displayState` / `show*` / `firstError` keys — see `FieldStateDerivedKey`)
- * and returns the single enum verdict; the `show*` booleans derive from
- * the result. Runs unconditionally on every field-state read, so the
- * idle / pending / error / success decision lives in exactly one place
- * and the whole app's validation-display behavior flows from it.
+ * One step of the display state machine: the verdict the field should
+ * render right now (`display`, projected to `displayState` and the
+ * `show*` booleans) plus two optional timing cells the engine reads.
+ *
+ * - `reviewAt` — an absolute `Date.now()` millisecond stamp telling the
+ *   engine "re-evaluate this field no later than here." The engine keeps
+ *   a single timer per form aimed at the nearest `reviewAt` across all
+ *   active fields; when it fires, the dependent field computeds re-run
+ *   and call the reducer again. A machine with no `reviewAt` and a
+ *   non-pending `display` is terminal — the engine evicts it.
+ * - `pendingShownAt` — the stamp at which `'pending'` was first shown,
+ *   the memory the min-visible hold needs so a spinner that just appeared
+ *   is not yanked away the instant validation resolves. Opaque to the
+ *   engine; a custom reducer may carry its own extra memory fields too.
+ */
+type DisplayMachine = {
+    readonly display: DisplayState;
+    readonly reviewAt?: number;
+    readonly pendingShownAt?: number;
+};
+/**
+ * Inputs to a `getDisplayState` reducer. `field` and `formMeta` are the
+ * same reactive snapshots a predicate has always received (still minus
+ * the derived `displayState` / `show*` / `firstError` keys — see
+ * `FieldStateDerivedKey` — so a reducer can never read its own output and
+ * form a cycle), now joined by:
+ *
+ * - `validatingSince` — `Date.now()` at which the field's current
+ *   validation streak opened, or `null` when nothing is in flight. This,
+ *   not `field.validating`, is the timing anchor: the elapsed wait is
+ *   `now - validatingSince`. Pinned to the start of the streak, so
+ *   overlapping sub-runs do not reset it.
+ * - `now` — the engine's clock, injected so the reducer stays pure and
+ *   deterministic (and frozen to `0` under SSR, where there is no clock).
+ */
+type DisplayCtx = {
+    readonly field: Omit<FieldState, FieldStateDerivedKey>;
+    readonly formMeta: Omit<FormMeta, FieldStateDerivedKey>;
+    readonly validatingSince: number | null;
+    readonly now: number;
+};
+/**
+ * Pure transition reducer that resolves a path's `displayState`. Given
+ * the field's previous `DisplayMachine` and the current `DisplayCtx`, it
+ * returns the next machine; the engine owns the clock and the timers, the
+ * reducer owns the timing policy. Runs on every field-state read (and
+ * again whenever a `reviewAt` deadline fires), so the whole app's
+ * validation-display behavior flows from this one function.
  *
- * The library default — `defaultDisplayState` — is publicly exported so
- * a layered predicate can compose with it:
+ * The library default — `defaultDisplayState` — is publicly exported so a
+ * layered reducer can compose with it, and `makeDefaultDisplayState`
+ * builds a default with custom anti-flash timings:
  *
  * ```ts
  * import { defaultDisplayState } from 'attaform'
@@ -2247,14 +2297,16 @@ type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'sho
  * useForm({
  *   schema,
  *   // Defer to the default everywhere, but never show a success check on `username`.
- *   getDisplayState: (field, formMeta) => {
- *     const state = defaultDisplayState(field, formMeta)
- *     return field.path[0] === 'username' && state === 'success' ? 'idle' : state
+ *   getDisplayState: (prev, ctx) => {
+ *     const next = defaultDisplayState(prev, ctx)
+ *     return next.display === 'success' && ctx.field.path[0] === 'username'
+ *       ? { display: 'idle' }
+ *       : next
  *   },
  * })
  * ```
  */
-type GetDisplayState = (field: Omit<FieldState, FieldStateDerivedKey>, formMeta: Omit<FormMeta, FieldStateDerivedKey>) => DisplayState;
+type GetDisplayState = (prev: DisplayMachine, ctx: DisplayCtx) => DisplayMachine;
 /**
  * Submit handler returned by `handleSubmit(onSubmit, onError)`. Bind
  * it to a `<form>`:
@@ -2554,18 +2606,34 @@ type RegisterValue<Value = unknown> = Readonly<{
      * Attach an HTML element to this binding. Called by `v-register`
      * automatically; expose it to custom integrations that need to
      * register an element manually.
+     *
+     * Recording the element also enables `setValueWithInternalPath` to
+     * auto-attach per-element persist meta on writes that don't carry
+     * their own.
      */
     registerElement: (el: HTMLElement) => void;
     /**
      * Detach an HTML element from this binding. Pair with
-     * `registerElement` for custom integrations.
+     * `registerElement` for custom integrations. Clears the recorded
+     * element so subsequent writes without explicit `meta` fall back to
+     * "no auto-persist".
      */
     deregisterElement: (el: HTMLElement) => void;
     /**
      * Write the field's value programmatically. Returns `true` when the
      * write was accepted, `false` when it was rejected (e.g. wrong
-     * primitive type for the path). The optional `meta` lets custom
-     * directives signal whether the write should be persisted.
+     * primitive type for the path).
+     *
+     * When `meta` is undefined and the binding has a registered element,
+     * the rv consults the per-element opt-in (set by
+     * `register(path, { persist: true })` against that element) and
+     * auto-attaches `{ persist: true }` when opted in. Custom directives
+     * and consumer assigners can omit `meta` to participate in the same
+     * persistence channel the default assigner uses.
+     *
+     * Pass an explicit `meta` to override the auto-derivation, e.g.
+     * `{ persist: false }` to skip persistence for a transient write
+     * even when the element is opted in.
      */
     setValueWithInternalPath: (value: unknown, meta?: WriteMeta) => boolean;
     /**
@@ -2808,9 +2876,9 @@ type RegisterValue<Value = unknown> = Readonly<{
  * on the bound element.
  *
  * The directive passes the extracted value plus the `RegisterValue`
- * the directive is currently bound to. The second arg lets a
- * top-level handler write back to form state without having to
- * capture the RV via closure:
+ * the directive is currently bound to, regardless of install path.
+ * The second arg lets a top-level handler write back to form state
+ * without having to capture the RV via closure:
  *
  * ```ts
  * function upperCaseAssigner(value: unknown, rv: RegisterValue): void {
@@ -2818,9 +2886,10 @@ type RegisterValue<Value = unknown> = Readonly<{
  * }
  * ```
  *
- * `registerValue` is omitted only for assigners installed directly
- * via `el[assignKey] = fn` — those callers already have the RV in
- * scope at install time.
+ * The `registerValue` parameter is typed optional only to keep
+ * standalone invocations from outside the directive (rare; manual
+ * dispatch in tests, for example) type-checkable; the directive
+ * itself always supplies it at fire time.
  *
  * Return `true` when the write was accepted, `false` when it was
  * rejected (e.g. the value didn't match the path's expected type).
@@ -4627,5 +4696,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { ROOT_PATH_KEY as $, ROOT_PATH as _, canonicalizePath as as, isPathPrefix as at, isUnset as au, parseDottedPath as av, unset as aw };
-export type { AbstractSchema as A, NestedType as B, CoercionEntry as C, DeepPartial as D, ErrorsProxyShape as E, FieldMetaPayload as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, OnError as O, OnInvalidSubmitPolicy as P, OnSubmit as Q, PartialFlatPath as R, Path as S, PathKey as T, PendingValidationStatus as U, PersistConfig as V, PersistConfigOptions as W, PersistIncludeMode as X, PersistOptInRegistry as Y, Primitive as Z, ApiErrorDetails as a, ReactiveValidationStatus as a0, RegisterDirective as a1, RegisterFlatPath as a2, RegisterModelDynamicCustomDirective as a3, RegisterOptions as a4, RegisterSelectModifier as a5, RegisterTextModifier as a6, RegisterTransform as a7, RegisterValue as a8, SchemaFactoryOptions as a9, Segment as aa, SetValueCallback as ab, SetValuePayload as ac, SettledValidationStatus as ad, SlimPrimitiveKind as ae, SlimRuntimeOf as af, SubmitHandler as ag, Unset as ah, UseFormConfiguration as ai, UseFormReturnType as aj, ValidateOn as ak, ValidateOnConfig as al, ValidationError as am, ValidationResponse as an, ValidationResponseWithoutValue as ao, ValueOfUnion as ap, WriteMeta as aq, WriteShape as ar, ApiErrorEntry as b, ApiErrorEnvelope as c, ArrayItem as d, ArrayPath as e, AttaformDefaults as f, CoercionRegistry as g, CoercionResult as h, CustomDirectiveRegisterAssignerFn as i, DefaultValuesInput as j, DefaultValuesResponse as k, DefaultValuesShape as l, DisplayState as m, FieldState as n, FieldStateMap as o, FieldStateMapEntry as p, FlatPath as q, FormErrorRecord as r, FormErrorsSurface as s, FormKey as t, FormMeta as u, FormStorage as v, FormStorageKind as w, GetDisplayState as x, HistoryConfig as y, IsUnion as z };
+export { ROOT_PATH as a0, ROOT_PATH_KEY as a1, canonicalizePath as au, isPathPrefix as av, isUnset as aw, parseDottedPath as ax, unset as ay };
+export type { Primitive as $, AbstractSchema as A, HistoryConfig as B, CoercionEntry as C, DeepPartial as D, ErrorsProxyShape as E, FieldMetaPayload as F, GenericForm as G, HandleSubmit as H, IsTuple as I, IsUnion as J, JoinSegments as K, KeyofUnion as L, LiftedValueShape as M, MetaTrackerValue as N, NestedReadType as O, NestedType as P, OnError as Q, OnInvalidSubmitPolicy as R, OnSubmit as S, PartialFlatPath as T, Path as U, PathKey as V, PendingValidationStatus as W, PersistConfig as X, PersistConfigOptions as Y, PersistIncludeMode as Z, PersistOptInRegistry as _, ApiErrorDetails as a, ReactiveValidationStatus as a2, RegisterDirective as a3, RegisterFlatPath as a4, RegisterModelDynamicCustomDirective as a5, RegisterOptions as a6, RegisterSelectModifier as a7, RegisterTextModifier as a8, RegisterTransform as a9, RegisterValue as aa, SchemaFactoryOptions as ab, Segment as ac, SetValueCallback as ad, SetValuePayload as ae, SettledValidationStatus as af, SlimPrimitiveKind as ag, SlimRuntimeOf as ah, SubmitHandler as ai, Unset as aj, UseFormConfiguration as ak, UseFormReturnType as al, ValidateOn as am, ValidateOnConfig as an, ValidationError as ao, ValidationResponse as ap, ValidationResponseWithoutValue as aq, ValueOfUnion as ar, WriteMeta as as, WriteShape as at, ApiErrorEntry as b, ApiErrorEnvelope as c, ArrayItem as d, ArrayPath as e, AttaformDefaults as f, CoercionRegistry as g, CoercionResult as h, CustomDirectiveRegisterAssignerFn as i, DefaultValuesInput as j, DefaultValuesResponse as k, DefaultValuesShape as l, DisplayCtx as m, DisplayMachine as n, DisplayState as o, FieldState as p, FieldStateMap as q, FieldStateMapEntry as r, FlatPath as s, FormErrorRecord as t, FormErrorsSurface as u, FormKey as v, FormMeta as w, FormStorage as x, FormStorageKind as y, GetDisplayState as z };

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

@@ -814,6 +814,12 @@ type AbstractSchema<Form, GetValueFormType> = {
      * Structural fingerprint of the schema. Same shape → same string;
      * different shape → (best-effort) different string.
      *
+     * Resolves a `Promise` so adapters can defer the structural walk (and
+     * its `canonicalStringify` helper) onto a dynamic import. The framework
+     * only ever needs the fingerprint on opt-in async paths (the multi-tab
+     * channel name, the persistence storage key) plus a dev-only mismatch
+     * warning, so none of those bytes belong on the eager `useForm` path.
+     *
      * The library uses this to detect schema mismatches at a shared
      * form key: two `useForm({ key: 'x', schema })` calls are allowed
      * to land on the same `FormStore` (the "shared store" semantic),
@@ -841,7 +847,7 @@ type AbstractSchema<Form, GetValueFormType> = {
      *   look identical. The warning is a footgun catcher, not a
      *   soundness guarantee.
      */
-    fingerprint(): string;
+    fingerprint(): Promise<string>;
     getDefaultValues(config: GetDefaultValuesConfig<Form>): DefaultValuesResponse<Form>;
     /**
      * Return the schema-prescribed default value at the given path. The
@@ -2047,29 +2053,31 @@ type AttaformDefaults = {
      *   useForm({ getDisplayState })  >  AttaformDefaults  >  library default
      *
      * The library default opens one timing gate, then resolves by
-     * precedence: gate closed → `'idle'`; a run in flight → `'pending'`;
-     * an own-path error → `'error'`; otherwise `valid` → `'success'`, else
-     * `'idle'`. The gate opens after the first submit attempt OR once the
-     * field is touched and not currently focused:
+     * precedence: gate closed → `'idle'`; a run in flight → a delayed
+     * `'pending'` (held briefly to smooth fast validations, then held a
+     * minimum so it never flashes); an own-path error → `'error'`;
+     * otherwise earned `valid` → `'success'`, else `'idle'`. The gate opens
+     * after the first submit attempt OR once the field is edited and left:
      *
      * ```ts
-     * (field, formMeta) => {
+     * (prev, ctx) => {
      *   const gateOpen =
-     *     formMeta.submissionAttempts > 0 ||
-     *     (field.touched === true && field.focused !== true)
-     *   if (!gateOpen) return 'idle'
-     *   if (field.validating === true) return 'pending'
-     *   // ...own-path error → 'error'; valid → 'success'; else 'idle'
+     *     ctx.formMeta.submissionAttempts > 0 ||
+     *     ctx.field.blurredAfterInteraction === true
+     *   if (!gateOpen) return { display: 'idle' }
+     *   // ...timed 'pending' while validating; own-path error → 'error';
+     *   //    earned valid → 'success'; else 'idle'
      * }
      * ```
      *
      * Compose with the library default via the public `defaultDisplayState`
-     * export. The predicate runs on every field-state read, so it owns the
+     * export, or retune its timing via `makeDefaultDisplayState`. The
+     * reducer runs on every field-state read, so it owns the
      * idle / pending / error / success decision outright.
      *
-     * The predicate's args are `Omit`'d of the derived `displayState` /
-     * `show*` / `firstError` keys (see `FieldStateDerivedKey`) to prevent
-     * a self-referential predicate.
+     * The reducer's `ctx.field` / `ctx.formMeta` are `Omit`'d of the
+     * derived `displayState` / `show*` / `firstError` keys (see
+     * `FieldStateDerivedKey`) to prevent a self-referential reducer.
      */
     getDisplayState?: GetDisplayState;
     /**
@@ -2230,16 +2238,58 @@ type DisplayState = 'idle' | 'pending' | 'error' | 'success';
  */
 type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError';
 /**
- * Predicate that resolves a path's `displayState`. Receives the field's
- * reactive state plus the form's reactive meta (both minus the derived
- * `displayState` / `show*` / `firstError` keys — see `FieldStateDerivedKey`)
- * and returns the single enum verdict; the `show*` booleans derive from
- * the result. Runs unconditionally on every field-state read, so the
- * idle / pending / error / success decision lives in exactly one place
- * and the whole app's validation-display behavior flows from it.
+ * One step of the display state machine: the verdict the field should
+ * render right now (`display`, projected to `displayState` and the
+ * `show*` booleans) plus two optional timing cells the engine reads.
+ *
+ * - `reviewAt` — an absolute `Date.now()` millisecond stamp telling the
+ *   engine "re-evaluate this field no later than here." The engine keeps
+ *   a single timer per form aimed at the nearest `reviewAt` across all
+ *   active fields; when it fires, the dependent field computeds re-run
+ *   and call the reducer again. A machine with no `reviewAt` and a
+ *   non-pending `display` is terminal — the engine evicts it.
+ * - `pendingShownAt` — the stamp at which `'pending'` was first shown,
+ *   the memory the min-visible hold needs so a spinner that just appeared
+ *   is not yanked away the instant validation resolves. Opaque to the
+ *   engine; a custom reducer may carry its own extra memory fields too.
+ */
+type DisplayMachine = {
+    readonly display: DisplayState;
+    readonly reviewAt?: number;
+    readonly pendingShownAt?: number;
+};
+/**
+ * Inputs to a `getDisplayState` reducer. `field` and `formMeta` are the
+ * same reactive snapshots a predicate has always received (still minus
+ * the derived `displayState` / `show*` / `firstError` keys — see
+ * `FieldStateDerivedKey` — so a reducer can never read its own output and
+ * form a cycle), now joined by:
+ *
+ * - `validatingSince` — `Date.now()` at which the field's current
+ *   validation streak opened, or `null` when nothing is in flight. This,
+ *   not `field.validating`, is the timing anchor: the elapsed wait is
+ *   `now - validatingSince`. Pinned to the start of the streak, so
+ *   overlapping sub-runs do not reset it.
+ * - `now` — the engine's clock, injected so the reducer stays pure and
+ *   deterministic (and frozen to `0` under SSR, where there is no clock).
+ */
+type DisplayCtx = {
+    readonly field: Omit<FieldState, FieldStateDerivedKey>;
+    readonly formMeta: Omit<FormMeta, FieldStateDerivedKey>;
+    readonly validatingSince: number | null;
+    readonly now: number;
+};
+/**
+ * Pure transition reducer that resolves a path's `displayState`. Given
+ * the field's previous `DisplayMachine` and the current `DisplayCtx`, it
+ * returns the next machine; the engine owns the clock and the timers, the
+ * reducer owns the timing policy. Runs on every field-state read (and
+ * again whenever a `reviewAt` deadline fires), so the whole app's
+ * validation-display behavior flows from this one function.
  *
- * The library default — `defaultDisplayState` — is publicly exported so
- * a layered predicate can compose with it:
+ * The library default — `defaultDisplayState` — is publicly exported so a
+ * layered reducer can compose with it, and `makeDefaultDisplayState`
+ * builds a default with custom anti-flash timings:
  *
  * ```ts
  * import { defaultDisplayState } from 'attaform'
@@ -2247,14 +2297,16 @@ type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'sho
  * useForm({
  *   schema,
  *   // Defer to the default everywhere, but never show a success check on `username`.
- *   getDisplayState: (field, formMeta) => {
- *     const state = defaultDisplayState(field, formMeta)
- *     return field.path[0] === 'username' && state === 'success' ? 'idle' : state
+ *   getDisplayState: (prev, ctx) => {
+ *     const next = defaultDisplayState(prev, ctx)
+ *     return next.display === 'success' && ctx.field.path[0] === 'username'
+ *       ? { display: 'idle' }
+ *       : next
  *   },
  * })
  * ```
  */
-type GetDisplayState = (field: Omit<FieldState, FieldStateDerivedKey>, formMeta: Omit<FormMeta, FieldStateDerivedKey>) => DisplayState;
+type GetDisplayState = (prev: DisplayMachine, ctx: DisplayCtx) => DisplayMachine;
 /**
  * Submit handler returned by `handleSubmit(onSubmit, onError)`. Bind
  * it to a `<form>`:
@@ -2554,18 +2606,34 @@ type RegisterValue<Value = unknown> = Readonly<{
      * Attach an HTML element to this binding. Called by `v-register`
      * automatically; expose it to custom integrations that need to
      * register an element manually.
+     *
+     * Recording the element also enables `setValueWithInternalPath` to
+     * auto-attach per-element persist meta on writes that don't carry
+     * their own.
      */
     registerElement: (el: HTMLElement) => void;
     /**
      * Detach an HTML element from this binding. Pair with
-     * `registerElement` for custom integrations.
+     * `registerElement` for custom integrations. Clears the recorded
+     * element so subsequent writes without explicit `meta` fall back to
+     * "no auto-persist".
      */
     deregisterElement: (el: HTMLElement) => void;
     /**
      * Write the field's value programmatically. Returns `true` when the
      * write was accepted, `false` when it was rejected (e.g. wrong
-     * primitive type for the path). The optional `meta` lets custom
-     * directives signal whether the write should be persisted.
+     * primitive type for the path).
+     *
+     * When `meta` is undefined and the binding has a registered element,
+     * the rv consults the per-element opt-in (set by
+     * `register(path, { persist: true })` against that element) and
+     * auto-attaches `{ persist: true }` when opted in. Custom directives
+     * and consumer assigners can omit `meta` to participate in the same
+     * persistence channel the default assigner uses.
+     *
+     * Pass an explicit `meta` to override the auto-derivation, e.g.
+     * `{ persist: false }` to skip persistence for a transient write
+     * even when the element is opted in.
      */
     setValueWithInternalPath: (value: unknown, meta?: WriteMeta) => boolean;
     /**
@@ -2808,9 +2876,9 @@ type RegisterValue<Value = unknown> = Readonly<{
  * on the bound element.
  *
  * The directive passes the extracted value plus the `RegisterValue`
- * the directive is currently bound to. The second arg lets a
- * top-level handler write back to form state without having to
- * capture the RV via closure:
+ * the directive is currently bound to, regardless of install path.
+ * The second arg lets a top-level handler write back to form state
+ * without having to capture the RV via closure:
  *
  * ```ts
  * function upperCaseAssigner(value: unknown, rv: RegisterValue): void {
@@ -2818,9 +2886,10 @@ type RegisterValue<Value = unknown> = Readonly<{
  * }
  * ```
  *
- * `registerValue` is omitted only for assigners installed directly
- * via `el[assignKey] = fn` — those callers already have the RV in
- * scope at install time.
+ * The `registerValue` parameter is typed optional only to keep
+ * standalone invocations from outside the directive (rare; manual
+ * dispatch in tests, for example) type-checkable; the directive
+ * itself always supplies it at fire time.
  *
  * Return `true` when the write was accepted, `false` when it was
  * rejected (e.g. the value didn't match the path's expected type).
@@ -4627,5 +4696,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { ROOT_PATH_KEY as $, ROOT_PATH as _, canonicalizePath as as, isPathPrefix as at, isUnset as au, parseDottedPath as av, unset as aw };
-export type { AbstractSchema as A, NestedType as B, CoercionEntry as C, DeepPartial as D, ErrorsProxyShape as E, FieldMetaPayload as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, OnError as O, OnInvalidSubmitPolicy as P, OnSubmit as Q, PartialFlatPath as R, Path as S, PathKey as T, PendingValidationStatus as U, PersistConfig as V, PersistConfigOptions as W, PersistIncludeMode as X, PersistOptInRegistry as Y, Primitive as Z, ApiErrorDetails as a, ReactiveValidationStatus as a0, RegisterDirective as a1, RegisterFlatPath as a2, RegisterModelDynamicCustomDirective as a3, RegisterOptions as a4, RegisterSelectModifier as a5, RegisterTextModifier as a6, RegisterTransform as a7, RegisterValue as a8, SchemaFactoryOptions as a9, Segment as aa, SetValueCallback as ab, SetValuePayload as ac, SettledValidationStatus as ad, SlimPrimitiveKind as ae, SlimRuntimeOf as af, SubmitHandler as ag, Unset as ah, UseFormConfiguration as ai, UseFormReturnType as aj, ValidateOn as ak, ValidateOnConfig as al, ValidationError as am, ValidationResponse as an, ValidationResponseWithoutValue as ao, ValueOfUnion as ap, WriteMeta as aq, WriteShape as ar, ApiErrorEntry as b, ApiErrorEnvelope as c, ArrayItem as d, ArrayPath as e, AttaformDefaults as f, CoercionRegistry as g, CoercionResult as h, CustomDirectiveRegisterAssignerFn as i, DefaultValuesInput as j, DefaultValuesResponse as k, DefaultValuesShape as l, DisplayState as m, FieldState as n, FieldStateMap as o, FieldStateMapEntry as p, FlatPath as q, FormErrorRecord as r, FormErrorsSurface as s, FormKey as t, FormMeta as u, FormStorage as v, FormStorageKind as w, GetDisplayState as x, HistoryConfig as y, IsUnion as z };
+export { ROOT_PATH as a0, ROOT_PATH_KEY as a1, canonicalizePath as au, isPathPrefix as av, isUnset as aw, parseDottedPath as ax, unset as ay };
+export type { Primitive as $, AbstractSchema as A, HistoryConfig as B, CoercionEntry as C, DeepPartial as D, ErrorsProxyShape as E, FieldMetaPayload as F, GenericForm as G, HandleSubmit as H, IsTuple as I, IsUnion as J, JoinSegments as K, KeyofUnion as L, LiftedValueShape as M, MetaTrackerValue as N, NestedReadType as O, NestedType as P, OnError as Q, OnInvalidSubmitPolicy as R, OnSubmit as S, PartialFlatPath as T, Path as U, PathKey as V, PendingValidationStatus as W, PersistConfig as X, PersistConfigOptions as Y, PersistIncludeMode as Z, PersistOptInRegistry as _, ApiErrorDetails as a, ReactiveValidationStatus as a2, RegisterDirective as a3, RegisterFlatPath as a4, RegisterModelDynamicCustomDirective as a5, RegisterOptions as a6, RegisterSelectModifier as a7, RegisterTextModifier as a8, RegisterTransform as a9, RegisterValue as aa, SchemaFactoryOptions as ab, Segment as ac, SetValueCallback as ad, SetValuePayload as ae, SettledValidationStatus as af, SlimPrimitiveKind as ag, SlimRuntimeOf as ah, SubmitHandler as ai, Unset as aj, UseFormConfiguration as ak, UseFormReturnType as al, ValidateOn as am, ValidateOnConfig as an, ValidationError as ao, ValidationResponse as ap, ValidationResponseWithoutValue as aq, ValueOfUnion as ar, WriteMeta as as, WriteShape as at, ApiErrorEntry as b, ApiErrorEnvelope as c, ArrayItem as d, ArrayPath as e, AttaformDefaults as f, CoercionRegistry as g, CoercionResult as h, CustomDirectiveRegisterAssignerFn as i, DefaultValuesInput as j, DefaultValuesResponse as k, DefaultValuesShape as l, DisplayCtx as m, DisplayMachine as n, DisplayState as o, FieldState as p, FieldStateMap as q, FieldStateMapEntry as r, FlatPath as s, FormErrorRecord as t, FormErrorsSurface as u, FormKey as v, FormMeta as w, FormStorage as x, FormStorageKind as y, GetDisplayState as z };