attaform 0.20.2 → 0.21.0

package/dist/rspack.d.mts

@@ -0,0 +1,40 @@
+import { W as WebpackFamilyPlugin, a as WebpackFamilyPluginOptions } from './shared/attaform.DuzQYscR.mjs';
+
+/**
+ * `attaform/rspack` — Rspack plugin that rewrites `attaform/zod` imports
+ * to the single matching adapter subpath (`attaform/zod-v3` or
+ * `attaform/zod-v4`) at build time, based on the consumer's installed Zod
+ * major. Without it, Rspack ships both adapters because the unified
+ * `attaform/zod` entry imports both for runtime dispatch.
+ *
+ * Usage:
+ *
+ *   // rspack.config.mjs
+ *   import { attaform } from 'attaform/rspack'
+ *
+ *   export default {
+ *     plugins: [attaform()],
+ *   }
+ *
+ * Rspack mirrors webpack's plugin API for the resolve hook attaform taps,
+ * so this shares its body with `attaform/webpack` via
+ * `createWebpackFamilyPlugin`; only the diagnostic tag differs.
+ *
+ * This plugin only does the adapter rewrite. The Vue SFC `v-register`
+ * transforms that `attaform/vite` wires (load-bearing for SSR initial
+ * render) are `@vitejs/plugin-vue`-specific and do not transfer; a
+ * non-Vite consumer that needs them wires `attaform/transforms` into
+ * their Vue compiler separately.
+ *
+ * Zero-dep: the plugin imports nothing from `@rspack/core` (it taps the
+ * resolve hook the compiler injects at the consumer's build).
+ */
+
+/** Options for the Rspack `attaform()` plugin. */
+type AttaformRspackPluginOptions = WebpackFamilyPluginOptions;
+/** The structural shape Rspack requires of the plugin. */
+type AttaformRspackPlugin = WebpackFamilyPlugin;
+declare function attaform(options?: AttaformRspackPluginOptions): AttaformRspackPlugin;
+
+export { attaform };
+export type { AttaformRspackPlugin, AttaformRspackPluginOptions };

package/dist/rspack.d.ts

@@ -0,0 +1,40 @@
+import { W as WebpackFamilyPlugin, a as WebpackFamilyPluginOptions } from './shared/attaform.DuzQYscR.js';
+
+/**
+ * `attaform/rspack` — Rspack plugin that rewrites `attaform/zod` imports
+ * to the single matching adapter subpath (`attaform/zod-v3` or
+ * `attaform/zod-v4`) at build time, based on the consumer's installed Zod
+ * major. Without it, Rspack ships both adapters because the unified
+ * `attaform/zod` entry imports both for runtime dispatch.
+ *
+ * Usage:
+ *
+ *   // rspack.config.mjs
+ *   import { attaform } from 'attaform/rspack'
+ *
+ *   export default {
+ *     plugins: [attaform()],
+ *   }
+ *
+ * Rspack mirrors webpack's plugin API for the resolve hook attaform taps,
+ * so this shares its body with `attaform/webpack` via
+ * `createWebpackFamilyPlugin`; only the diagnostic tag differs.
+ *
+ * This plugin only does the adapter rewrite. The Vue SFC `v-register`
+ * transforms that `attaform/vite` wires (load-bearing for SSR initial
+ * render) are `@vitejs/plugin-vue`-specific and do not transfer; a
+ * non-Vite consumer that needs them wires `attaform/transforms` into
+ * their Vue compiler separately.
+ *
+ * Zero-dep: the plugin imports nothing from `@rspack/core` (it taps the
+ * resolve hook the compiler injects at the consumer's build).
+ */
+
+/** Options for the Rspack `attaform()` plugin. */
+type AttaformRspackPluginOptions = WebpackFamilyPluginOptions;
+/** The structural shape Rspack requires of the plugin. */
+type AttaformRspackPlugin = WebpackFamilyPlugin;
+declare function attaform(options?: AttaformRspackPluginOptions): AttaformRspackPlugin;
+
+export { attaform };
+export type { AttaformRspackPlugin, AttaformRspackPluginOptions };

package/dist/rspack.mjs

@@ -0,0 +1,8 @@
+import { c as createWebpackFamilyPlugin } from './shared/attaform.C3Doa9Pt.mjs';
+
+function attaform(options = {}) {
+  return createWebpackFamilyPlugin("attaform/rspack", options);
+}
+
+export { attaform };
+//# sourceMappingURL=rspack.mjs.map

package/dist/rspack.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"rspack.mjs","sources":["../src/rspack.ts"],"sourcesContent":["/**\n * `attaform/rspack` — Rspack plugin that rewrites `attaform/zod` imports\n * to the single matching adapter subpath (`attaform/zod-v3` or\n * `attaform/zod-v4`) at build time, based on the consumer's installed Zod\n * major. Without it, Rspack ships both adapters because the unified\n * `attaform/zod` entry imports both for runtime dispatch.\n *\n * Usage:\n *\n *   // rspack.config.mjs\n *   import { attaform } from 'attaform/rspack'\n *\n *   export default {\n *     plugins: [attaform()],\n *   }\n *\n * Rspack mirrors webpack's plugin API for the resolve hook attaform taps,\n * so this shares its body with `attaform/webpack` via\n * `createWebpackFamilyPlugin`; only the diagnostic tag differs.\n *\n * This plugin only does the adapter rewrite. The Vue SFC `v-register`\n * transforms that `attaform/vite` wires (load-bearing for SSR initial\n * render) are `@vitejs/plugin-vue`-specific and do not transfer; a\n * non-Vite consumer that needs them wires `attaform/transforms` into\n * their Vue compiler separately.\n *\n * Zero-dep: the plugin imports nothing from `@rspack/core` (it taps the\n * resolve hook the compiler injects at the consumer's build).\n */\nimport {\n  createWebpackFamilyPlugin,\n  type WebpackFamilyPlugin,\n  type WebpackFamilyPluginOptions,\n} from './core/webpack-family-plugin'\n\n/** Options for the Rspack `attaform()` plugin. */\nexport type AttaformRspackPluginOptions = WebpackFamilyPluginOptions\n/** The structural shape Rspack requires of the plugin. */\nexport type AttaformRspackPlugin = WebpackFamilyPlugin\n\nexport function attaform(options: AttaformRspackPluginOptions = {}): AttaformRspackPlugin {\n  return createWebpackFamilyPlugin('attaform/rspack', options)\n}\n"],"names":[],"mappings":";;AAwCO,SAAS,QAAA,CAAS,OAAA,GAAuC,EAAC,EAAyB;AACxF,EAAA,OAAO,yBAAA,CAA0B,mBAAmB,OAAO,CAAA;AAC7D;;;;"}

package/dist/runtime/plugins/attaform.cjs

@@ -1,8 +1,8 @@
 'use strict';
 
 const app = require('nuxt/app');
-const devtoolsShared = require('../../shared/attaform.D2SCCd4O.cjs');
-const paths = require('../../shared/attaform.z5j3LwJz.cjs');
+const devtoolsShared = require('../../shared/attaform.CEf6wYfD.cjs');
+const paths = require('../../shared/attaform.BA3vRDos.cjs');
 
 var attaform_default = app.defineNuxtPlugin({
   // `enforce: 'pre'` makes the "we run before any component's setup" claim

package/dist/runtime/plugins/attaform.mjs

@@ -1,6 +1,6 @@
 import { defineNuxtPlugin, useRuntimeConfig, useRoute } from 'nuxt/app';
-import { r as renderAttaformState, h as hydrateAttaformState, D as DEVTOOLS_WINDOW_KEY } from '../../shared/attaform.CnrxbkB6.mjs';
-import { m as createAttaform, y as kAttaformWizardActiveStepResolver, s as getRegistryFromApp } from '../../shared/attaform.QG5TG8lB.mjs';
+import { r as renderAttaformState, h as hydrateAttaformState, D as DEVTOOLS_WINDOW_KEY } from '../../shared/attaform.ezb5Nh2t.mjs';
+import { m as createAttaform, y as kAttaformWizardActiveStepResolver, s as getRegistryFromApp } from '../../shared/attaform.Y_Mgg0Yp.mjs';
 
 var attaform_default = defineNuxtPlugin({
   // `enforce: 'pre'` makes the "we run before any component's setup" claim

package/dist/shared/{attaform.ceGEAEMk.d.ts → attaform.7lzO9pdM.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, f as AttaformDefaults, aj as UseFormReturnType, a8 as RegisterValue } from './attaform.99cfHcIt.js';
+import { v as FormKey, V as PathKey, m as DisplayCtx, z as GetDisplayState, n as DisplayMachine, ag as SlimPrimitiveKind, C as CoercionEntry, g as CoercionRegistry, G as GenericForm, U as Path, ao as ValidationError, A as AbstractSchema, as as WriteMeta, D as DeepPartial, at as WriteShape, am as ValidateOn, _ as PersistOptInRegistry, f as AttaformDefaults, al as UseFormReturnType, aa as RegisterValue } from './attaform.B1nyO4ec.mjs';
 import { Ref, ComputedRef, App, InjectionKey } from 'vue';
 
 /**
@@ -455,6 +455,68 @@ type UseWizardReturnType<S extends ReadonlyArray<StepSlot> = ReadonlyArray<StepS
     readonly reset: () => void;
 };
 
+/**
+ * Per-form display engine: owns the clock and the timers that the pure
+ * `getDisplayState` reducer policy needs, so the reducer itself stays a
+ * deterministic `(prev, ctx) => next` function.
+ *
+ * It keeps a `Map` of the machines that are still *active* (a spinner is
+ * showing, a verdict is being held, or a `reviewAt` deadline is pending),
+ * a single reactive `tick` ref, and a single `setTimeout` aimed at the
+ * nearest `reviewAt` across every active field. When a field-state
+ * computed reads `resolve`, it subscribes to `tick`; when the timer
+ * fires, `tick` bumps and every dependent computed re-runs the reducer,
+ * so a field whose deadline elapsed transitions (verdict → spinner, or
+ * spinner → settled verdict) without any per-field watcher.
+ *
+ * Eviction: a machine is dropped once it reaches a terminal *idle* state
+ * with no pending review. Error / success / pending machines are retained
+ * so the reducer can hold the prior verdict under the show-delay window of
+ * the *next* validation streak (no success → idle → success flicker). The
+ * retained set is bounded by the rendered non-idle fields; none of them
+ * arm a timer, so retention costs memory, never CPU.
+ *
+ * Untrusted reducer: `getDisplayState` is consumer-overridable, so the
+ * engine treats the returned `reviewAt` as untrusted. A non-finite deadline
+ * (NaN / ±Infinity from a custom predicate's bad arithmetic) is ignored
+ * rather than handed to `setTimeout`, where it coerces to 0 and spins; an
+ * over-large finite deadline is clamped below the 32-bit `setTimeout`
+ * overflow; and the timer refuses to re-arm for the exact deadline it just
+ * fired, so a predicate re-emitting a fixed or past `reviewAt` can't drive an
+ * infinite fire loop. None of these arise from the library default, which
+ * always advances its deadline or drops it.
+ *
+ * Background tabs: `setTimeout` is throttled to >= 1s while a tab is hidden,
+ * so a min-visible hold can overshoot. A `visibilitychange` listener bumps
+ * the clock on return to the foreground, so any overdue deadline resolves at
+ * once instead of lingering.
+ *
+ * SSR: no clock, no timers, no listener. With `now` frozen and nothing
+ * validating at render, the reducer returns the plain verdict (never
+ * pending) and the engine stores nothing, so the server HTML and the
+ * client's first render agree — no hydration mismatch on the display
+ * projection.
+ */
+type DisplayEngine = {
+    /**
+     * Resolve a path's next `DisplayMachine`. Subscribes the calling
+     * computed to the engine clock, threads the path's previous machine
+     * through `reducer`, persists or evicts the result, and re-arms the
+     * single timer to the nearest deadline.
+     */
+    resolve(key: PathKey, ctx: DisplayCtx, reducer: GetDisplayState): DisplayMachine;
+    /** Drop every retained machine and cancel the timer (used by `reset()`). */
+    clear(): void;
+    /** Tear down for good: `clear()` plus detaching the visibility listener. */
+    dispose(): void;
+    /** Introspection for tests: count of retained machines. */
+    size(): number;
+    /** Introspection for tests: whether a path currently has a retained machine. */
+    has(key: PathKey): boolean;
+    /** Introspection for tests: whether a deadline timer is currently armed. */
+    hasTimer(): boolean;
+};
+
 /**
  * Schema-driven coercion of user-typed DOM values at the v-register
  * directive layer. When the slim schema declares a numeric or
@@ -669,6 +731,16 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * read.
      */
     readonly getDisplayState: GetDisplayState;
+    /**
+     * Per-form display engine: owns the clock and the single timer the timed
+     * `getDisplayState` reducer policy needs, keeping the reducer itself a
+     * pure `(prev, ctx) => next` function. The field-state computeds route
+     * every `displayState` read through `displayEngine.resolve(...)`, which
+     * threads the path's previous machine, persists or evicts the result, and
+     * re-arms the nearest-deadline timer. Constructed once at form
+     * construction; torn down via `registerCleanup` on store eviction.
+     */
+    readonly displayEngine: DisplayEngine;
     readonly submitting: Ref<boolean>;
     readonly activeSubmissions: Ref<number>;
     readonly submissionAttempts: Ref<number>;
@@ -838,6 +910,28 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * computed only re-runs when the count for ITS key changes.
      */
     readonly fieldValidationCounts: Map<PathKey, number>;
+    /**
+     * Per-path `Date.now()` stamp marking when the field's LATEST validation
+     * run started, re-anchored on every run start (every increment), deleted
+     * on the `→ 0` edge. The display reducer reads it as `ctx.validatingSince`
+     * to time the anti-flash spinner, which measures `now - validatingSince`:
+     * re-anchoring on each run means a burst of keystrokes (each aborting the
+     * prior run and starting a new one) keeps pushing the stamp forward, so the
+     * spinner stays suppressed until the user pauses rather than surfacing
+     * mid-typing. Anchoring only at the streak start would pin it to the first
+     * keystroke, because with `debounceMs: 0` the aborted run's decrement lands
+     * after the next run's increment and the count never returns to 0 between
+     * fast keystrokes. The field-state container walk takes the descendant-min
+     * so a row spinner anchors at its earliest still-active leaf. Runtime-only,
+     * never hydrated, like the counts. REACTIVE: the display computed reads this
+     * (as `ctx.validatingSince`) but not the `validating` flag, and a long
+     * validation that settles with an unchanged verdict (same error, still
+     * invalid) leaves `errors` / `valid` untouched — so a non-reactive map would
+     * leave a held `pending` spinner stranded after the run ends, until some
+     * unrelated reactive change happened to re-run the computed. Reactivity ties
+     * the computed to both the streak start (set) and end (delete).
+     */
+    readonly fieldValidatingSince: Map<PathKey, number>;
     /**
      * Replace the form value wholesale. Optional `meta` is forwarded to
      * every `onFormChange` listener so they can decide whether THIS write

package/dist/shared/{attaform.99cfHcIt.d.cts → attaform.B1nyO4ec.d.cts}

@@ -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>`:
@@ -4644,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.99cfHcIt.d.mts → 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>`:
@@ -4644,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 };