attaform 0.23.0 → 0.24.1

package/dist/shared/{attaform.BibT5AS_.cjs.map → attaform.BOi6n2Pn.cjs.map}

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

package/dist/shared/{attaform.DCkSNnPr.d.mts → attaform.Bk7vnQhG.d.cts}

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { G as GenericForm, w as FlatPath, P as NestedType, F as FormKey, U as UseFormConfiguration, a as AbstractSchema, D as DefaultValuesInput, ah as ValidateOnConfig, b as UseFormReturnType } from './attaform.BJnNK75Y.mjs';
+import { G as GenericForm, u as FlatPath, O as NestedType, F as FormKey, U as UseFormConfiguration, a as AbstractSchema, D as DefaultValuesInput, af as ValidateOnConfig, b as UseFormReturnType } from './attaform.DBhrKb2j.cjs';
 
 /**
  * The shape `form.values.<key>` returns at runtime.
@@ -120,6 +120,38 @@ type StorageLeaf<L> = InputIsUnknown<L> extends true ? unknown : L extends {
     };
 } ? Out : never;
 
+/**
+ * The Zod v4 schema roots `useForm` accepts. A fixed-shape
+ * `z.object({ … })` is the common case; `z.record(K, V)` admits a
+ * dictionary form (a homogeneous map with runtime-known keys);
+ * `z.discriminatedUnion(disc, [...])` admits a variant form (one of
+ * several object shapes, picked by a discriminator). Each projects to
+ * a `GenericForm`-shaped value the form engine drives: an object root
+ * descends into its fixed keys, a record root treats its entries as an
+ * open live-keyed container, a variant root lifts the active variant's
+ * keys into one addressable surface.
+ *
+ * Other roots (a bare `z.union`, a root `z.array`, primitives,
+ * `z.map` / `z.set`) are not form roots; wrap them under a key. The
+ * adapter's runtime construction rejects them with a legible error.
+ *
+ * `z.ZodObject` MUST keep its `z.ZodRawShape` argument, and the
+ * discriminated-union arm MUST stay fully applied. The unified entry's
+ * v4 overload constrains on `SupportedRootSchema & ZodV4Internals` to
+ * keep v3 schemas out (see `../unified/types-zod-major.ts`). In a
+ * single-major (v3-only) consumer install, the published `.d.mts`
+ * resolves this `z` to v3, where a bare or under-applied Zod class is
+ * missing its required arguments and degrades to an `any`-like error
+ * type; `any` then absorbs the union and `any & ZodV4Internals`
+ * collapses back to `any`, so the marker stops excluding v3 schemas and
+ * the read slot poisons to `never`. `z.ZodRecord` carries defaults for
+ * both arguments, so it stays concrete in either major.
+ * `z.ZodDiscriminatedUnion` does NOT (v3 requires both arguments, and
+ * its parameter order is the reverse of v4's), so the arm is written
+ * fully applied; the v3-only bundled-types fixture guards it.
+ */
+type SupportedRootSchema = z.ZodObject<z.ZodRawShape> | z.ZodRecord | z.ZodDiscriminatedUnion<readonly z.ZodObject<z.ZodRawShape>[], string>;
+
 /**
  * Zod v4 adapter entry point. Re-exports the adapter + the useForm
  * wrapper that threads zod-v4-specific schema types through
@@ -188,12 +220,12 @@ type PathOutput<Schema extends z.ZodType, Path extends string> = z.output<Schema
  * generics ride on the alias rather than re-evaluating the
  * conditional from scratch.
  */
-type FormOf<Schema extends z.ZodObject> = z.input<Schema> extends GenericForm ? z.input<Schema> : never;
-type OutOf<Schema extends z.ZodObject> = z.output<Schema> extends GenericForm ? z.output<Schema> : never;
-type ReadOf<Schema extends z.ZodObject> = StorageShape<Schema> extends GenericForm ? StorageShape<Schema> : never;
-declare function useForm<Schema extends z.ZodObject, K extends FormKey = FormKey>(configuration: Omit<UseFormConfiguration<FormOf<Schema>, OutOf<Schema>, AbstractSchema<FormOf<Schema>, OutOf<Schema>>, DefaultValuesInput<FormOf<Schema>>, K>, 'schema' | 'validateOn' | 'debounceMs'> & {
+type FormOf<Schema extends SupportedRootSchema> = z.input<Schema> extends GenericForm ? z.input<Schema> : never;
+type OutOf<Schema extends SupportedRootSchema> = z.output<Schema> extends GenericForm ? z.output<Schema> : never;
+type ReadOf<Schema extends SupportedRootSchema> = StorageShape<Schema> extends GenericForm ? StorageShape<Schema> : never;
+declare function useForm<Schema extends SupportedRootSchema, K extends FormKey = FormKey>(configuration: Omit<UseFormConfiguration<FormOf<Schema>, OutOf<Schema>, AbstractSchema<FormOf<Schema>, OutOf<Schema>>, DefaultValuesInput<FormOf<Schema>>, K>, 'schema' | 'validateOn' | 'debounceMs'> & {
     schema: Schema;
 } & ValidateOnConfig): UseFormReturnType<FormOf<Schema>, OutOf<Schema>, ReadOf<Schema>, K>;
 
 export { useForm as u };
-export type { PathInput as P, StorageShape as S, PathOutput as a };
+export type { PathInput as P, SupportedRootSchema as S, PathOutput as a, StorageShape as b };

package/dist/shared/{attaform.BGMRvckW.d.ts → attaform.Bq6Copxn.d.cts}

@@ -1,4 +1,4 @@
-import { F as FormKey, Y as PathKey, p as DisplayCtx, d as GetDisplayState, q as DisplayMachine, X as Path, ac as SlimPrimitiveKind, C as CoercionEntry, j as CoercionRegistry, G as GenericForm, V as ValidationError, a as AbstractSchema, al as WriteMeta, m as DeepPartial, am as WriteShape, at as TransformAbortHolder, ag as ValidateOn, A as AttaformDefaults, b as UseFormReturnType, c as RegisterValue } from './attaform.BJnNK75Y.js';
+import { F as FormKey, W as PathKey, m as DisplayCtx, d as GetDisplayState, n as DisplayMachine, V as Path, aa as SlimPrimitiveKind, C as CoercionEntry, g as CoercionRegistry, G as GenericForm, ag as ValidationError, a as AbstractSchema, ak as WriteMeta, j as DeepPartial, al as WriteShape, as as TransformAbortHolder, ae as ValidateOn, A as AttaformDefaults, b as UseFormReturnType, c as RegisterValue } from './attaform.DBhrKb2j.cjs';
 import { Ref, ComputedRef, App, InjectionKey } from 'vue';
 
 /**
@@ -209,9 +209,11 @@ type WizardSubmitContext = {
 type WizardOnSubmit = (ctx: WizardSubmitContext) => void | Promise<void>;
 /**
  * Optional `onError` callback registered via `wizard.handleSubmit`.
- * Receives the aggregate error list — entries originate from per-form
- * validation and activation failures (`atta:activation-failed`). Sync
- * or async; the returned promise gates `wizard.submitting`.
+ * Receives the aggregate error list. Entries originate from per-form
+ * validation, activation failures (`atta:activation-failed`), and a
+ * submit callback that left errors on a processed step (the
+ * `setErrors(...); return` server-rejection path). Sync or async; the
+ * returned promise gates `wizard.submitting`.
  */
 type WizardOnError = (errors: readonly WizardAggregateError[]) => void | Promise<void>;
 /**
@@ -402,25 +404,32 @@ type WizardForms<S> = FormsRecordOf<S> & Readonly<Record<FormKey, AnyForm>>;
  *                    Forward-looking; reactive to current form
  *                    validity. Gates "Finish button enable" style UI.
  *  - `done`        — monotonic latch: flips `true` the first time a
- *                    final-step `handleSubmit` resolves without
- *                    throwing, and stays `true` through subsequent
- *                    edits or invalidations. Only `reset()` flips it
- *                    back. Gates "show success card" style UI that
- *                    should reflect submission history rather than
- *                    current validity.
+ *                    final-step `handleSubmit` resolves without throwing
+ *                    AND leaves no errors set on any step, and stays
+ *                    `true` through subsequent edits or invalidations. A
+ *                    callback that calls `setErrors` and returns (the
+ *                    documented server-rejection path) is a failed submit,
+ *                    so it does not flip `done`. Only `reset()` flips it
+ *                    back. Gates "show success card" style UI that should
+ *                    reflect submission history rather than current
+ *                    validity.
  *  - `submitting`  — `true` while a `wizard.handleSubmit` call is in
  *                    flight. Global re-entrance guard: every
  *                    navigation method also refuses while this is on.
  *  - `submissionAttempts` — count of `wizard.handleSubmit` invocations
  *                    (success or failure). Always bumps, including on
  *                    noop-form steps.
- *  - `submitError` — the error thrown by the most recent
+ *  - `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.
+ *                    `form.meta.submitError`: this is the unexpected-throw
+ *                    channel, so an expected rejection handled via
+ *                    `setErrors` (no throw) surfaces through the error
+ *                    surface and `onError` instead, leaving this `null`.
+ *                    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.
@@ -643,12 +652,12 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * Schema-driven errors. Written ONLY by the schema validation pipeline:
      * `scheduleFieldValidation`, `handleSubmit`, the construction-time seed,
      * history restore, and hydration. Cleared by `reset` / `resetField` and by
-     * a successful submit. `setFieldErrors*` APIs do NOT touch this Map.
+     * a successful submit. `setErrors` / `clearErrors` do NOT touch this Map.
      */
     readonly schemaErrors: Map<PathKey, ValidationError[]>;
     /**
-     * User-injected errors. Written ONLY by the `setFieldErrors*` API surfaces
-     * (and history / hydration replay). Survives schema revalidation and
+     * User-injected errors. Written ONLY by the `setErrors` / `clearErrors`
+     * API surface (and history / hydration replay). Survives schema revalidation and
      * successful submits — the consumer owns its lifetime explicitly.
      */
     readonly userErrors: Map<PathKey, ValidationError[]>;
@@ -1005,7 +1014,7 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      */
     applySchemaErrorsForSubtree(path: Path, errors: ValidationError[]): void;
     setAllUserErrors(errors: readonly ValidationError[]): void;
-    addUserErrors(errors: readonly ValidationError[]): void;
+    setUserErrorsForPath(path: Path, errors: readonly ValidationError[]): void;
     clearUserErrors(path?: Path): void;
     /**
      * Merged read — returns `[...schemaErrors[path], ...userErrors[path]]`.
@@ -1311,9 +1320,8 @@ type SerializedFormData = {
      */
     readonly schemaErrors: ReadonlyArray<readonly [string, unknown]>;
     /**
-     * Errors set explicitly via `setFieldErrors` / `addFieldErrors`
-     * (typically from a server response parsed via `parseApiErrors`)
-     * at snapshot time. Replayed at hydration; persists across
+     * Errors set explicitly via `setErrors` (typically a server
+     * response) at snapshot time. Replayed at hydration; persists across
      * client-side re-validation.
      */
     readonly userErrors: ReadonlyArray<readonly [string, unknown]>;
@@ -1741,9 +1749,9 @@ declare function lazy<Ctx = WizardCtx>(resolve: (ctx: Ctx) => AnyForm | string |
  *   `issue.code` (e.g. `zod:too_small`). No enum here because
  *   Zod's code list evolves.
  * - consumer-defined — anything the consumer's backend / app stamps
- *   onto a `ValidationError` (via the `parseApiErrors` wire payload
- *   or `setFieldErrors` directly). Pick a scope (`api:`, `auth:`,
- *   etc.) and stay consistent.
+ *   onto a `ValidationError` (a server response handed to `setErrors`,
+ *   or a code passed inline). Pick a scope (`api:`, `auth:`, etc.) and
+ *   stay consistent.
  *
  * Use these constants in tests and error-routing UI:
  *
@@ -1787,6 +1795,14 @@ declare const AttaformErrorCode: {
      * `form.hydrateError` for retry UX.
      */
     readonly ActivationFailed: "atta:activation-failed";
+    /**
+     * Default code stamped on a manual error set through `form.setErrors`
+     * when the caller omits an explicit `code`. The `setErrors` input is
+     * lenient (`code` optional), so this is the fallback that keeps every
+     * produced `ValidationError` carrying a stable, branchable identifier.
+     * Override it per error by passing your own `code` (`api:…`, `auth:…`).
+     */
+    readonly UserError: "atta:user-error";
 };
 type AttaformErrorCode = (typeof AttaformErrorCode)[keyof typeof AttaformErrorCode];
 

package/dist/shared/{attaform.DuPneYR0.d.cts → attaform.BrFPMFgi.d.ts}

@@ -1,4 +1,4 @@
-import { F as FormKey, Y as PathKey, p as DisplayCtx, d as GetDisplayState, q as DisplayMachine, X as Path, ac as SlimPrimitiveKind, C as CoercionEntry, j as CoercionRegistry, G as GenericForm, V as ValidationError, a as AbstractSchema, al as WriteMeta, m as DeepPartial, am as WriteShape, at as TransformAbortHolder, ag as ValidateOn, A as AttaformDefaults, b as UseFormReturnType, c as RegisterValue } from './attaform.BJnNK75Y.cjs';
+import { F as FormKey, W as PathKey, m as DisplayCtx, d as GetDisplayState, n as DisplayMachine, V as Path, aa as SlimPrimitiveKind, C as CoercionEntry, g as CoercionRegistry, G as GenericForm, ag as ValidationError, a as AbstractSchema, ak as WriteMeta, j as DeepPartial, al as WriteShape, as as TransformAbortHolder, ae as ValidateOn, A as AttaformDefaults, b as UseFormReturnType, c as RegisterValue } from './attaform.DBhrKb2j.js';
 import { Ref, ComputedRef, App, InjectionKey } from 'vue';
 
 /**
@@ -209,9 +209,11 @@ type WizardSubmitContext = {
 type WizardOnSubmit = (ctx: WizardSubmitContext) => void | Promise<void>;
 /**
  * Optional `onError` callback registered via `wizard.handleSubmit`.
- * Receives the aggregate error list — entries originate from per-form
- * validation and activation failures (`atta:activation-failed`). Sync
- * or async; the returned promise gates `wizard.submitting`.
+ * Receives the aggregate error list. Entries originate from per-form
+ * validation, activation failures (`atta:activation-failed`), and a
+ * submit callback that left errors on a processed step (the
+ * `setErrors(...); return` server-rejection path). Sync or async; the
+ * returned promise gates `wizard.submitting`.
  */
 type WizardOnError = (errors: readonly WizardAggregateError[]) => void | Promise<void>;
 /**
@@ -402,25 +404,32 @@ type WizardForms<S> = FormsRecordOf<S> & Readonly<Record<FormKey, AnyForm>>;
  *                    Forward-looking; reactive to current form
  *                    validity. Gates "Finish button enable" style UI.
  *  - `done`        — monotonic latch: flips `true` the first time a
- *                    final-step `handleSubmit` resolves without
- *                    throwing, and stays `true` through subsequent
- *                    edits or invalidations. Only `reset()` flips it
- *                    back. Gates "show success card" style UI that
- *                    should reflect submission history rather than
- *                    current validity.
+ *                    final-step `handleSubmit` resolves without throwing
+ *                    AND leaves no errors set on any step, and stays
+ *                    `true` through subsequent edits or invalidations. A
+ *                    callback that calls `setErrors` and returns (the
+ *                    documented server-rejection path) is a failed submit,
+ *                    so it does not flip `done`. Only `reset()` flips it
+ *                    back. Gates "show success card" style UI that should
+ *                    reflect submission history rather than current
+ *                    validity.
  *  - `submitting`  — `true` while a `wizard.handleSubmit` call is in
  *                    flight. Global re-entrance guard: every
  *                    navigation method also refuses while this is on.
  *  - `submissionAttempts` — count of `wizard.handleSubmit` invocations
  *                    (success or failure). Always bumps, including on
  *                    noop-form steps.
- *  - `submitError` — the error thrown by the most recent
+ *  - `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.
+ *                    `form.meta.submitError`: this is the unexpected-throw
+ *                    channel, so an expected rejection handled via
+ *                    `setErrors` (no throw) surfaces through the error
+ *                    surface and `onError` instead, leaving this `null`.
+ *                    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.
@@ -643,12 +652,12 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * Schema-driven errors. Written ONLY by the schema validation pipeline:
      * `scheduleFieldValidation`, `handleSubmit`, the construction-time seed,
      * history restore, and hydration. Cleared by `reset` / `resetField` and by
-     * a successful submit. `setFieldErrors*` APIs do NOT touch this Map.
+     * a successful submit. `setErrors` / `clearErrors` do NOT touch this Map.
      */
     readonly schemaErrors: Map<PathKey, ValidationError[]>;
     /**
-     * User-injected errors. Written ONLY by the `setFieldErrors*` API surfaces
-     * (and history / hydration replay). Survives schema revalidation and
+     * User-injected errors. Written ONLY by the `setErrors` / `clearErrors`
+     * API surface (and history / hydration replay). Survives schema revalidation and
      * successful submits — the consumer owns its lifetime explicitly.
      */
     readonly userErrors: Map<PathKey, ValidationError[]>;
@@ -1005,7 +1014,7 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      */
     applySchemaErrorsForSubtree(path: Path, errors: ValidationError[]): void;
     setAllUserErrors(errors: readonly ValidationError[]): void;
-    addUserErrors(errors: readonly ValidationError[]): void;
+    setUserErrorsForPath(path: Path, errors: readonly ValidationError[]): void;
     clearUserErrors(path?: Path): void;
     /**
      * Merged read — returns `[...schemaErrors[path], ...userErrors[path]]`.
@@ -1311,9 +1320,8 @@ type SerializedFormData = {
      */
     readonly schemaErrors: ReadonlyArray<readonly [string, unknown]>;
     /**
-     * Errors set explicitly via `setFieldErrors` / `addFieldErrors`
-     * (typically from a server response parsed via `parseApiErrors`)
-     * at snapshot time. Replayed at hydration; persists across
+     * Errors set explicitly via `setErrors` (typically a server
+     * response) at snapshot time. Replayed at hydration; persists across
      * client-side re-validation.
      */
     readonly userErrors: ReadonlyArray<readonly [string, unknown]>;
@@ -1741,9 +1749,9 @@ declare function lazy<Ctx = WizardCtx>(resolve: (ctx: Ctx) => AnyForm | string |
  *   `issue.code` (e.g. `zod:too_small`). No enum here because
  *   Zod's code list evolves.
  * - consumer-defined — anything the consumer's backend / app stamps
- *   onto a `ValidationError` (via the `parseApiErrors` wire payload
- *   or `setFieldErrors` directly). Pick a scope (`api:`, `auth:`,
- *   etc.) and stay consistent.
+ *   onto a `ValidationError` (a server response handed to `setErrors`,
+ *   or a code passed inline). Pick a scope (`api:`, `auth:`, etc.) and
+ *   stay consistent.
  *
  * Use these constants in tests and error-routing UI:
  *
@@ -1787,6 +1795,14 @@ declare const AttaformErrorCode: {
      * `form.hydrateError` for retry UX.
      */
     readonly ActivationFailed: "atta:activation-failed";
+    /**
+     * Default code stamped on a manual error set through `form.setErrors`
+     * when the caller omits an explicit `code`. The `setErrors` input is
+     * lenient (`code` optional), so this is the fallback that keeps every
+     * produced `ValidationError` carrying a stable, branchable identifier.
+     * Override it per error by passing your own `code` (`api:…`, `auth:…`).
+     */
+    readonly UserError: "atta:user-error";
 };
 type AttaformErrorCode = (typeof AttaformErrorCode)[keyof typeof AttaformErrorCode];
 

package/dist/shared/{attaform.alpG7rT7.mjs → attaform.BunnTiTw.mjs}

@@ -1,6 +1,6 @@
-import { q as getAtPath, o as slimKindOf, r as setAtPath, p as humanize, h as useAbstractForm } from './attaform.CtJOd7ox.mjs';
-import { A as AttaformError, _ as __DEV__, a as canonicalizePath, b as InvalidUseFormConfigError } from './attaform.BhI9Icek.mjs';
-import { f as fieldMetaStore, g as getFieldMetaForSchema, a as getFieldMetaListForSchema, s as slimPrimitivesWalk, w as walkPathSegments, d as deriveDefaultWalk, m as mergeDeep, c as createAbstractSchema, b as getFieldMetaPathMap } from './attaform.Dd1Kmmaj.mjs';
+import { p as getAtPath, n as slimKindOf, q as setAtPath, o as humanize, h as useAbstractForm } from './attaform.NWrEGrNo.mjs';
+import { A as AttaformError, _ as __DEV__, f as canonicalizePath, a as InvalidUseFormConfigError } from './attaform.C0au8oXd.mjs';
+import { f as fieldMetaStore, g as getFieldMetaForSchema, a as getFieldMetaListForSchema, s as slimPrimitivesWalk, w as walkPathSegments, d as deriveDefaultWalk, m as mergeDeep, c as createAbstractSchema, b as getFieldMetaPathMap } from './attaform.C-tQKknW.mjs';
 import { z } from 'zod';
 
 const fieldMeta = fieldMetaStore;
@@ -1272,4 +1272,4 @@ function useForm(configuration) {
 }
 
 export { UnsupportedSchemaError as U, assertZodVersion as a, getIntersectionRight as b, unwrapLazy as c, unwrapInner as d, unwrapPipe as e, fieldMeta as f, getIntersectionLeft as g, getDiscriminator as h, getDiscriminatedOptions as i, getUnionOptions as j, kindOf as k, getRecordKeyType as l, getRecordValueType as m, getTupleItems as n, getSetValueType as o, getArrayElement as p, getObjectShape as q, getEnumValues as r, getLiteralValues as s, getChecks as t, useForm as u, getCatchDefault as v, withMeta as w, getDefaultValue as x, zodV4Adapter as z };
-//# sourceMappingURL=attaform.alpG7rT7.mjs.map
+//# sourceMappingURL=attaform.BunnTiTw.mjs.map