attaform 0.20.2 → 0.21.1

package/dist/shared/attaform.DuzQYscR.d.ts

@@ -0,0 +1,41 @@
+interface WebpackFamilyPluginOptions {
+    /**
+     * Rewrite `attaform/zod` imports at build time to the matching adapter
+     * subpath, based on the consumer's installed Zod major. Default `true`.
+     * Set to `false` to keep the runtime-dispatch unified entry (ships both
+     * adapters) when a project intentionally mixes Zod versions or resolves
+     * Zod in a non-standard way.
+     */
+    resolveZodAlias?: boolean;
+    /**
+     * Project root to resolve the installed Zod from. Defaults to the
+     * compiler's `context`, falling back to `process.cwd()`. Set this when
+     * the build runs from a directory other than the project that owns the
+     * Zod dependency (some monorepo layouts).
+     */
+    root?: string;
+}
+interface WebpackTapable<T> {
+    tap(name: string, fn: (arg: T) => void): void;
+}
+interface WebpackResolveData {
+    request: string;
+}
+interface WebpackNormalModuleFactory {
+    hooks: {
+        beforeResolve: WebpackTapable<WebpackResolveData>;
+    };
+}
+interface WebpackCompiler {
+    context?: string;
+    hooks: {
+        normalModuleFactory: WebpackTapable<WebpackNormalModuleFactory>;
+    };
+}
+/** The structural shape webpack/rspack require of a plugin: an object
+ * with an `apply(compiler)` method. */
+interface WebpackFamilyPlugin {
+    apply(compiler: WebpackCompiler): void;
+}
+
+export type { WebpackFamilyPlugin as W, WebpackFamilyPluginOptions as a };

package/dist/shared/{attaform.BXinSW2T.d.mts → attaform.FudOcHaa.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.99cfHcIt.mjs';
+import { G as GenericForm, s as FlatPath, P as NestedType, v as FormKey, al as UseFormConfiguration, A as AbstractSchema, j as DefaultValuesInput, ao as ValidateOnConfig, am as UseFormReturnType } from './attaform.D0dWZsJt.cjs';
 
 /**
  * The shape `form.values.<key>` returns at runtime.
@@ -143,7 +143,7 @@ type PathInput<Schema extends z.ZodType, Path extends string> = z.input<Schema>
 /**
  * Type produced at `Path` after the full parse pipeline — the schema's
  * `z.output<Schema>` shape at that path. Matches the `data` payload of
- * `form.process()` and the value handed to `handleSubmit`'s callback.
+ * `form.parse()` and the value handed to `handleSubmit`'s callback.
  *
  * ```ts
  * const schema = z.object({

package/dist/shared/attaform.LEWUFqUw.cjs

@@ -0,0 +1,54 @@
+'use strict';
+
+const node_fs = require('node:fs');
+const node_url = require('node:url');
+const node_path = require('node:path');
+
+const ZOD_UNIFIED_SPECIFIER = "attaform/zod";
+const ZOD_V3_SPECIFIER = "attaform/zod-v3";
+const ZOD_V4_SPECIFIER = "attaform/zod-v4";
+function detectZodMajor(consumerRootDir) {
+  const consumerURL = node_url.pathToFileURL(node_path.join(consumerRootDir, "package.json")).href;
+  let resolved;
+  try {
+    resolved = undefined("zod/package.json", consumerURL);
+  } catch {
+    return { major: "missing" };
+  }
+  try {
+    const pkg = JSON.parse(node_fs.readFileSync(node_url.fileURLToPath(resolved), "utf8"));
+    const version = pkg.version;
+    if (typeof version !== "string") return { major: "unknown" };
+    const major = Number.parseInt(version.split(".")[0] ?? "", 10);
+    if (major === 3) return { major: 3 };
+    if (major === 4) return { major: 4 };
+    return { major: "unknown" };
+  } catch {
+    return { major: "unknown" };
+  }
+}
+function missingZodError(tag) {
+  return `[${tag}] zod is not installed. attaform requires zod as a peer dependency. Install \`zod@^3\` or \`zod@^4\`, OR pass \`attaform({ resolveZodAlias: false })\` to keep the runtime-dispatch unified entry (and silence this check).`;
+}
+function unclassifiableZodWarning(tag) {
+  return `[${tag}] Could not classify the installed Zod major (corrupted package.json, monorepo edge case, or an unexpected version string). Falling through to runtime dispatch \u2014 both Zod adapters will ship in the bundle. Pass \`attaform({ resolveZodAlias: false })\` to silence this warning.`;
+}
+function resolveZodAliasTarget(consumerRootDir, tag, resolveZodAlias, warnState) {
+  if (!resolveZodAlias) return null;
+  const detection = detectZodMajor(consumerRootDir);
+  if (detection.major === "missing") {
+    throw new Error(missingZodError(tag));
+  }
+  if (detection.major === "unknown") {
+    if (!warnState.warned) {
+      warnState.warned = true;
+      console.warn(unclassifiableZodWarning(tag));
+    }
+    return null;
+  }
+  return detection.major === 4 ? ZOD_V4_SPECIFIER : ZOD_V3_SPECIFIER;
+}
+
+exports.ZOD_UNIFIED_SPECIFIER = ZOD_UNIFIED_SPECIFIER;
+exports.resolveZodAliasTarget = resolveZodAliasTarget;
+//# sourceMappingURL=attaform.LEWUFqUw.cjs.map

package/dist/shared/attaform.LEWUFqUw.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"attaform.LEWUFqUw.cjs","sources":["../../src/core/detect-zod-major.ts"],"sourcesContent":["/**\n * Shared build-time Zod-major detection and `attaform/zod` alias\n * resolution for the bundler plugins (`attaform/vite`, `attaform/rollup`,\n * `attaform/esbuild`, `attaform/webpack`, `attaform/rspack`).\n *\n * The unified `attaform/zod` entry runtime-dispatches between the v3 and\n * v4 adapters, so a bundler that does not rewrite the import ships BOTH.\n * Each plugin rewrites `attaform/zod` to the single matching adapter\n * subpath (`attaform/zod-v3` or `attaform/zod-v4`) based on the Zod major\n * resolved from the consumer's project, so the consumer bundle carries\n * one adapter instead of two. This module holds the detection (pure Node,\n * no bundler API) plus the shared diagnostic copy so every plugin behaves\n * and reads identically.\n *\n * Build-time only: imported by the build-tool entries at `src/*.ts`,\n * never by runtime code, so it never reaches a consumer's browser bundle.\n */\nimport { readFileSync } from 'node:fs'\nimport { fileURLToPath, pathToFileURL } from 'node:url'\nimport { join } from 'node:path'\n\nexport const ZOD_UNIFIED_SPECIFIER = 'attaform/zod'\nexport const ZOD_V3_SPECIFIER = 'attaform/zod-v3'\nexport const ZOD_V4_SPECIFIER = 'attaform/zod-v4'\n\nexport type ZodMajorDetection =\n  | { major: 3 }\n  | { major: 4 }\n  | { major: 'missing' }\n  | { major: 'unknown' }\n\n/**\n * Read the consumer's installed Zod major by resolving\n * `zod/package.json` from their project root. ESM resolution\n * (`import.meta.resolve`) is sync and stable on Node 20.6+, follows\n * pnpm symlinks, and works with attaform's ESM-only `exports` map.\n *\n * Returns:\n *  - `{ major: 3 | 4 }` when zod is resolvable AND its `version`\n *    field parses to a known major;\n *  - `{ major: 'missing' }` when zod can't be resolved at all;\n *  - `{ major: 'unknown' }` for any other failure (corrupted\n *    package.json, unexpected version string, monorepo edge case).\n */\nexport function detectZodMajor(consumerRootDir: string): ZodMajorDetection {\n  const consumerURL = pathToFileURL(join(consumerRootDir, 'package.json')).href\n  let resolved: string\n  try {\n    resolved = import.meta.resolve('zod/package.json', consumerURL)\n  } catch {\n    return { major: 'missing' }\n  }\n  try {\n    const pkg = JSON.parse(readFileSync(fileURLToPath(resolved), 'utf8')) as { version?: unknown }\n    const version = pkg.version\n    if (typeof version !== 'string') return { major: 'unknown' }\n    const major = Number.parseInt(version.split('.')[0] ?? '', 10)\n    if (major === 3) return { major: 3 }\n    if (major === 4) return { major: 4 }\n    return { major: 'unknown' }\n  } catch {\n    return { major: 'unknown' }\n  }\n}\n\n/**\n * One-shot latch so a plugin warns about an unclassifiable Zod version\n * only once, however many times its detection runs across a build.\n */\nexport interface ZodDetectionWarnState {\n  warned: boolean\n}\n\nfunction missingZodError(tag: string): string {\n  return (\n    `[${tag}] zod is not installed. attaform requires zod as a peer dependency. ` +\n    'Install `zod@^3` or `zod@^4`, OR pass `attaform({ resolveZodAlias: false })` ' +\n    'to keep the runtime-dispatch unified entry (and silence this check).'\n  )\n}\n\nfunction unclassifiableZodWarning(tag: string): string {\n  return (\n    `[${tag}] Could not classify the installed Zod major (corrupted package.json, ` +\n    'monorepo edge case, or an unexpected version string). Falling through to runtime ' +\n    'dispatch — both Zod adapters will ship in the bundle. ' +\n    'Pass `attaform({ resolveZodAlias: false })` to silence this warning.'\n  )\n}\n\n/**\n * Resolve the rewrite target for the unified `attaform/zod` specifier,\n * shared by every bundler plugin so they diagnose identically:\n *   - returns `attaform/zod-v3` / `attaform/zod-v4` when the consumer's\n *     Zod major is detected;\n *   - returns `null` to leave `attaform/zod` on its runtime-dispatch\n *     entry, either because `resolveZodAlias` is off or because the\n *     version could not be classified (warned once via `warnState`);\n *   - throws when zod is not installed at all, a fatal misconfiguration\n *     the consumer must fix.\n *\n * `tag` brands the diagnostics (`attaform/vite`, `attaform/rollup`, etc).\n * `resolveZodAlias` and `warnState` are supplied by the calling plugin:\n * its consumer-facing default and its per-instance warn latch live at the\n * plugin surface, not here.\n */\nexport function resolveZodAliasTarget(\n  consumerRootDir: string,\n  tag: string,\n  resolveZodAlias: boolean,\n  warnState: ZodDetectionWarnState\n): string | null {\n  if (!resolveZodAlias) return null\n  const detection = detectZodMajor(consumerRootDir)\n  if (detection.major === 'missing') {\n    throw new Error(missingZodError(tag))\n  }\n  if (detection.major === 'unknown') {\n    if (!warnState.warned) {\n      warnState.warned = true\n      console.warn(unclassifiableZodWarning(tag))\n    }\n    return null\n  }\n  return detection.major === 4 ? ZOD_V4_SPECIFIER : ZOD_V3_SPECIFIER\n}\n"],"names":["pathToFileURL","join","readFileSync","fileURLToPath"],"mappings":";;;;;;AAqBO,MAAM,qBAAA,GAAwB;AAC9B,MAAM,gBAAA,GAAmB,iBAAA;AACzB,MAAM,gBAAA,GAAmB,iBAAA;AAqBzB,SAAS,eAAe,eAAA,EAA4C;AACzE,EAAA,MAAM,cAAcA,sBAAA,CAAcC,cAAA,CAAK,eAAA,EAAiB,cAAc,CAAC,CAAA,CAAE,IAAA;AACzE,EAAA,IAAI,QAAA;AACJ,EAAA,IAAI;AACF,IAAA,QAAA,GAAW,SAAY,CAAQ,kBAAA,EAAoB,WAAW,CAAA;AAAA,EAChE,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,EAAE,OAAO,SAAA,EAAU;AAAA,EAC5B;AACA,EAAA,IAAI;AACF,IAAA,MAAM,GAAA,GAAM,KAAK,KAAA,CAAMC,oBAAA,CAAaC,uBAAc,QAAQ,CAAA,EAAG,MAAM,CAAC,CAAA;AACpE,IAAA,MAAM,UAAU,GAAA,CAAI,OAAA;AACpB,IAAA,IAAI,OAAO,OAAA,KAAY,QAAA,EAAU,OAAO,EAAE,OAAO,SAAA,EAAU;AAC3D,IAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,QAAA,CAAS,OAAA,CAAQ,KAAA,CAAM,GAAG,CAAA,CAAE,CAAC,CAAA,IAAK,EAAA,EAAI,EAAE,CAAA;AAC7D,IAAA,IAAI,KAAA,KAAU,CAAA,EAAG,OAAO,EAAE,OAAO,CAAA,EAAE;AACnC,IAAA,IAAI,KAAA,KAAU,CAAA,EAAG,OAAO,EAAE,OAAO,CAAA,EAAE;AACnC,IAAA,OAAO,EAAE,OAAO,SAAA,EAAU;AAAA,EAC5B,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,EAAE,OAAO,SAAA,EAAU;AAAA,EAC5B;AACF;AAUA,SAAS,gBAAgB,GAAA,EAAqB;AAC5C,EAAA,OACE,IAAI,GAAG,CAAA,2NAAA,CAAA;AAIX;AAEA,SAAS,yBAAyB,GAAA,EAAqB;AACrD,EAAA,OACE,IAAI,GAAG,CAAA,wRAAA,CAAA;AAKX;AAkBO,SAAS,qBAAA,CACd,eAAA,EACA,GAAA,EACA,eAAA,EACA,SAAA,EACe;AACf,EAAA,IAAI,CAAC,iBAAiB,OAAO,IAAA;AAC7B,EAAA,MAAM,SAAA,GAAY,eAAe,eAAe,CAAA;AAChD,EAAA,IAAI,SAAA,CAAU,UAAU,SAAA,EAAW;AACjC,IAAA,MAAM,IAAI,KAAA,CAAM,eAAA,CAAgB,GAAG,CAAC,CAAA;AAAA,EACtC;AACA,EAAA,IAAI,SAAA,CAAU,UAAU,SAAA,EAAW;AACjC,IAAA,IAAI,CAAC,UAAU,MAAA,EAAQ;AACrB,MAAA,SAAA,CAAU,MAAA,GAAS,IAAA;AACnB,MAAA,OAAA,CAAQ,IAAA,CAAK,wBAAA,CAAyB,GAAG,CAAC,CAAA;AAAA,IAC5C;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AACA,EAAA,OAAO,SAAA,CAAU,KAAA,KAAU,CAAA,GAAI,gBAAA,GAAmB,gBAAA;AACpD;;;;;"}

package/dist/shared/{attaform.CywE4y8x.d.cts → attaform.MtrpT6Ki.d.ts}

@@ -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.99cfHcIt.cjs';
+import { G as GenericForm, s as FlatPath, P as NestedType, v as FormKey, al as UseFormConfiguration, A as AbstractSchema, j as DefaultValuesInput, ao as ValidateOnConfig, am as UseFormReturnType } from './attaform.D0dWZsJt.js';
 
 /**
  * The shape `form.values.<key>` returns at runtime.
@@ -143,7 +143,7 @@ type PathInput<Schema extends z.ZodType, Path extends string> = z.input<Schema>
 /**
  * Type produced at `Path` after the full parse pipeline — the schema's
  * `z.output<Schema>` shape at that path. Matches the `data` payload of
- * `form.process()` and the value handed to `handleSubmit`'s callback.
+ * `form.parse()` and the value handed to `handleSubmit`'s callback.
  *
  * ```ts
  * const schema = z.object({

package/dist/shared/{attaform.DbRgDFa7.d.cts → attaform.NQ8mybyW.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.cjs';
+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, ap as ValidationError, A as AbstractSchema, at as WriteMeta, D as DeepPartial, au as WriteShape, aj as TransformAbortHolder, an as ValidateOn, _ as PersistOptInRegistry, f as AttaformDefaults, am as UseFormReturnType, aa as RegisterValue } from './attaform.D0dWZsJt.mjs';
 import { Ref, ComputedRef, App, InjectionKey } from 'vue';
 
 /**
@@ -414,6 +414,13 @@ type WizardForms<S> = FormsRecordOf<S> & Readonly<Record<FormKey, AnyForm>>;
  *  - `submissionAttempts` — count of `wizard.handleSubmit` invocations
  *                    (success or failure). Always bumps, including on
  *                    noop-form steps.
+ *  - `submitError` — the error thrown by the most recent
+ *                    `wizard.handleSubmit` callback (or its `onError`),
+ *                    coerced to a real `Error`. Mirrors
+ *                    `form.meta.submitError`: cleared at submit entry and
+ *                    by `reset()`, parked here rather than re-thrown, so
+ *                    the handler resolves and never manufactures a
+ *                    `window` unhandledrejection. `null` on success.
  *  - `visited`     — append-only breadcrumb of navigated step keys.
  *                    `back()` does not pop; the trail is the audit
  *                    log, not the back-stack.
@@ -447,6 +454,7 @@ type UseWizardReturnType<S extends ReadonlyArray<StepSlot> = ReadonlyArray<StepS
     readonly done: boolean;
     readonly submitting: boolean;
     readonly submissionAttempts: number;
+    readonly submitError: Error | null;
     readonly visited: readonly FormKey[];
     readonly next: () => Promise<void>;
     readonly back: () => void;
@@ -455,6 +463,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 +739,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>;
@@ -679,7 +759,7 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * alongside the rest of the submission surface.
      */
     readonly submitted: Ref<boolean>;
-    readonly submitError: Ref<unknown>;
+    readonly submitError: Ref<Error | null>;
     readonly departAttempts: Ref<number>;
     /**
      * `true` while a function-form `defaultValues` factory is in flight.
@@ -838,6 +918,61 @@ 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>;
+    /**
+     * Per-path counter of in-flight async-transform runs (the async
+     * branch of the `register({ transforms })` pipeline). `> 0` drives
+     * `field.transforming` / `field.busy`. Counter, not flag, for the
+     * same overlap reason as `fieldValidationCounts`, except a superseding
+     * input releases the prior run synchronously before incrementing the
+     * new one — so the count is the live in-flight depth at the path
+     * (effectively 0 or 1). Reactive Map, like the validation counters.
+     */
+    readonly fieldTransformCounts: Map<PathKey, number>;
+    /**
+     * Per-path `ssr ? 0 : Date.now()` stamp marking when the path's latest
+     * async transform opened; the display reducer reads it (as
+     * `ctx.transformingSince`) to time the gated busy spinner. Mirrors
+     * `fieldValidatingSince` exactly: re-anchored on each run start,
+     * deleted on the `→ 0` edge, reactive for the held-spinner reason.
+     */
+    readonly fieldTransformingSince: Map<PathKey, number>;
+    /**
+     * Per-path latest async-transform failure (a rejected transform, or a
+     * resolved value the write gate refused), surfaced as
+     * `field.transformError`. Cleared when a fresh run opens at the path
+     * and on `reset()`. A channel separate from validation `errors`.
+     */
+    readonly transformErrors: Map<PathKey, Error | null>;
+    /**
+     * Form-wide count of in-flight async-transform runs. Drives the
+     * `settleTransforms` quiescence guard and the `handleSubmit` drain
+     * barrier. `Math.max(0, …)`-clamped on release so a doubled decrement
+     * (a run's own `endTransform` after a synchronous cancel release)
+     * can't drive it negative.
+     */
+    readonly activeTransforms: Ref<number>;
     /**
      * Replace the form value wholesale. Optional `meta` is forwarded to
      * every `onFormChange` listener so they can decide whether THIS write
@@ -1005,6 +1140,41 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * at entry (submit validation is authoritative) and by `reset()`.
      */
     cancelFieldValidation(): void;
+    /**
+     * Open an async-transform run at `key` — bump the run token, increment
+     * the in-flight counters, stamp `transformingSince`, clear any prior
+     * `transformError`, register `holder` for later abort. Returns the run
+     * token. See `InternalRegisterValue.beginTransform`.
+     */
+    beginTransform(key: PathKey, holder: TransformAbortHolder): number;
+    /** `true` while `token` is the live async-transform run at `key`. */
+    isCurrentTransform(key: PathKey, token: number): boolean;
+    /**
+     * Close the run `token` at `key`: release the counters (no-op if the
+     * run was already released by a supersede / cancel) and flush settled
+     * `settleTransforms` waiters.
+     */
+    endTransform(key: PathKey, token: number): void;
+    /** Record a per-field normalization failure at `key` (`field.transformError`). */
+    setTransformError(key: PathKey, err: Error): void;
+    /**
+     * Abort + release every in-flight async-transform run (all paths) and
+     * clear `transformErrors`. Mirrors `cancelFieldValidation`; called by
+     * `reset()` and store teardown.
+     */
+    cancelTransforms(): void;
+    /**
+     * Path-scoped counterpart to `cancelTransforms`: abort + release only
+     * the runs at-or-under `prefix`, clearing their `transformError`.
+     * Called by `resetField`.
+     */
+    cancelTransformsUnder(prefix: Path): void;
+    /**
+     * Resolve once async transforms are quiescent — globally (`path`
+     * omitted) or at-or-under `path`. Resolve-never-reject. See
+     * `UseFormReturnType.settleTransforms`.
+     */
+    settleTransforms(path?: string | Path): Promise<void>;
     /**
      * Kick off (or schedule) a field-level validation run for `path`. Pass
      * `path = []` to cover the whole form; `applySchemaErrorsForSubtree`