attaform 0.27.6 → 0.29.0

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "attaform",
-  "version": "0.27.6",
-  "main": "./dist/index.mjs",
+  "version": "0.29.0",
   "types": "./dist/index.d.mts",
   "files": [
     "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.cjs",
+    "!dist/**/*.d.cts",
+    "!dist/**/*.d.ts",
     "skills",
     "bin"
   ],
@@ -34,12 +37,12 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
+      "development": "./dist/dev/index.mjs",
       "import": "./dist/index.mjs"
     },
     "./nuxt": {
       "types": "./dist/nuxt.d.mts",
-      "import": "./dist/nuxt.mjs",
-      "require": "./dist/nuxt.cjs"
+      "import": "./dist/nuxt.mjs"
     },
     "./vite": {
       "types": "./dist/vite.d.mts",
@@ -70,22 +73,33 @@
     },
     "./zod": {
       "types": "./dist/zod.d.mts",
+      "development": "./dist/dev/zod.mjs",
       "import": "./dist/zod.mjs"
     },
     "./zod-v3": {
       "types": "./dist/zod-v3.d.mts",
+      "development": "./dist/dev/zod-v3.mjs",
       "import": "./dist/zod-v3.mjs"
     },
     "./zod-v4": {
       "types": "./dist/zod-v4.d.mts",
+      "development": "./dist/dev/zod-v4.mjs",
       "import": "./dist/zod-v4.mjs"
     },
     "./abstract": {
       "types": "./dist/abstract.d.mts",
+      "development": "./dist/dev/abstract.mjs",
       "import": "./dist/abstract.mjs"
     },
-    "./types": {
-      "types": "./dist/index.d.mts"
+    "./directive": {
+      "types": "./dist/directive.d.mts",
+      "development": "./dist/dev/directive.mjs",
+      "import": "./dist/directive.mjs"
+    },
+    "./history": {
+      "types": "./dist/history.d.mts",
+      "development": "./dist/dev/history.mjs",
+      "import": "./dist/history.mjs"
     },
     "./package.json": "./package.json"
   },
@@ -116,17 +130,18 @@
     "@commitlint/config-conventional": "^21.0.1",
     "@eslint/js": "^10.0.1",
     "@fast-check/vitest": "^0.4.0",
+    "@nuxt/devtools": "^3.4.2",
     "@nuxt/devtools-kit": "^3.2.0",
     "@nuxt/kit": "^4.4.2",
     "@nuxt/schema": "^4.4.2",
     "@nuxt/test-utils": "^4.0.2",
-    "@nuxt/ui": "^4.8.0",
+    "@nuxt/ui": "^4.11.1",
     "@rollup/plugin-alias": "^6.0.0",
     "@size-limit/preset-small-lib": "^12.1.0",
-    "@types/jsdom": "^28.0.1",
-    "@types/node": "^25.6.0",
+    "@types/jsdom": "^30.0.0",
+    "@types/node": "^26.5.1",
     "@vitejs/plugin-vue": "^6.0.6",
-    "@vitest/coverage-v8": "^4.1.5",
+    "@vitest/coverage-v8": "^4.1.11",
     "@vue/compiler-core": "^3.5.33",
     "@vue/compiler-sfc": "^3.5.33",
     "@vue/devtools-api": "^8.1.1",
@@ -143,19 +158,20 @@
     "fast-check": "^4.7.0",
     "globals": "^17.5.0",
     "husky": "^9.1.7",
-    "jsdom": "^29.0.2",
+    "jsdom": "^30.0.1",
     "lint-staged": "^17.0.4",
-    "nuxt": "^4.4.2",
+    "nuxt": "^4.5.2",
     "prettier": "^3.8.3",
-    "primevue": "^4.5.5",
-    "reka-ui": "^2.9.10",
+    "primevue": "4.5.5",
+    "reka-ui": "^2.10.4",
+    "rollup": "^4.63.1",
     "rollup-plugin-dts": "^6.4.1",
     "size-limit": "^12.1.0",
     "typescript": "6.0.3",
     "typescript-eslint": "^8.59.0",
     "unbuild": "^3.6.1",
-    "vite": "^8.0.10",
-    "vitest": "^4.1.5",
+    "vite": "^8.3.0",
+    "vitest": "^4.1.11",
     "vue": "^3.5.33",
     "vue-eslint-parser": "^10.4.0",
     "vue-tsc": "^3.2.7",
@@ -194,11 +210,11 @@
     "dev:prepare": "unbuild --stub && nuxi prepare apps/site",
     "dev:site": "pnpm --filter attaform-site dev",
     "build:site": "pnpm --filter attaform-site build",
-    "lint": "eslint --cache --concurrency=auto . && pnpm format:check",
-    "lint:fix": "eslint --cache --concurrency=auto --fix . && pnpm format",
+    "lint": "eslint --cache --concurrency=auto --max-warnings 0 . && pnpm format:check",
+    "lint:fix": "eslint --cache --concurrency=auto --max-warnings 0 --fix . && pnpm format",
     "format": "prettier --write '**/*.{ts,js,vue,css,scss,md,json,yml,yaml}'",
     "format:check": "prettier --check '**/*.{ts,js,vue,css,scss,md,json,yml,yaml}'",
-    "check": "pnpm lint && pnpm typecheck && pnpm check:site && pnpm test && pnpm test:nuxt-ui && pnpm check:size && pnpm check:eager && pnpm check:bench && pnpm check:coverage",
+    "check": "pnpm check:security-floors && pnpm lint && pnpm typecheck && pnpm check:site && pnpm test && pnpm test:nuxt-ui && pnpm check:size && pnpm check:tarball && pnpm check:eager && pnpm check:bench && pnpm check:coverage",
     "fix": "pnpm lint:fix",
     "typecheck": "tsc --noEmit",
     "prepack:watch": "chokidar 'src/**/*' -c 'pnpm prepack' --initial",
@@ -208,7 +224,9 @@
     "test:types": "pnpm dev:prepare && vue-tsc --noEmit && cd apps/site && vue-tsc --noEmit",
     "test:watch": "node scripts/run-with-webstorage-flag.mjs vitest watch",
     "bench": "node scripts/run-with-webstorage-flag.mjs vitest bench --run",
+    "check:security-floors": "node scripts/check-security-floors.mjs",
     "check:size": "pnpm prepack && size-limit",
+    "check:tarball": "node scripts/check-tarball-size.mjs",
     "check:eager": "node scripts/check-eager-size.mjs",
     "check:coverage": "node scripts/run-with-webstorage-flag.mjs vitest run --coverage",
     "check:bench": "node scripts/check-bench.mjs",
@@ -216,6 +234,6 @@
     "check:doc-snippets": "node scripts/check-doc-snippets.mjs",
     "check:site": "pnpm dev:prepare && pnpm --filter attaform-site typecheck",
     "fallow": "DO_NOT_TRACK=1 FALLOW_TELEMETRY=0 npx --yes fallow@2.88.3 --score",
-    "version": "node scripts/promote-changelog.mjs && (node scripts/generate-release-notes.mjs || echo '[version] release-notes step failed; continuing') && node scripts/sync-doc-versions.mjs && git add CHANGELOG.md RELEASES.md docs/scorecard/cii-best-practices-answers.md"
+    "version": "node scripts/promote-changelog.mjs && (node scripts/generate-release-notes.mjs || echo '[version] release-notes step failed; continuing') && node scripts/sync-doc-versions.mjs && node scripts/build-bestpractices-json.mjs && git add CHANGELOG.md RELEASES.md docs/scorecard/cii-best-practices-answers.md .bestpractices.json"
   }
 }

package/skills/attaform/SKILL.md

@@ -24,13 +24,15 @@ import {
   fieldMeta,
   withMeta,
   lazy,
+  gate,
 } from 'attaform'
 ```
 
 - **Do not import `useForm` from `attaform/abstract`.** That entry is the bring-your-own-adapter escape hatch: it exports `useAbstractForm`, which needs a schema adapter wired by hand. A Zod project wants `useForm` from `attaform`. This mismatch is the single most common first-try mistake.
 - Types come from the same barrel: `import type { AnyForm, WizardCtx, Json, ValidationError } from 'attaform'`.
 - `attaform/zod` is the same surface named explicitly; `attaform/zod-v3` and `attaform/zod-v4` pin a Zod major. Any of these works; default to `attaform`.
-- In **Nuxt** with the module installed (`attaform/nuxt`), this surface auto-imports and the `v-register` directive is registered globally, so a component needs no import lines at all. In **plain Vite**, add the Attaform plugin from `attaform/vite` plus the auto-import preset it exports.
+- In **Nuxt** with the module installed (`attaform/nuxt`), the whole block above auto-imports and the `v-register` directive is bound into each compiled template, so a component needs no import lines at all. Writing them anyway is always safe and always portable: an explicit import beats an auto-import of the same name, which is why every snippet below keeps its import line. In **plain Vite**, add the Attaform plugin from `attaform/vite` (it binds `v-register` the same way) plus the auto-import preset it exports. Without either build plugin, register the directive once per app: `import { installVRegister } from 'attaform/directive'` then `installVRegister(app)`.
+- Undo/redo ships from its own entry: `import { historyPlugin } from 'attaform/history'`, then `useForm({ schema, history: historyPlugin({ max: 200 }) })` unlocks a live `form.history` namespace (`undo` / `redo` / `clear` / `canUndo` / `canRedo` / `size`). Without the plugin the namespace is inert stubs.
 
 ## Build a form
 
@@ -85,7 +87,8 @@ Prefer an explicit `key` (`useForm({ schema, key: 'sign-in' })`): it makes the f
 - **Reach with `?.` on injected forms.** `injectForm()` and `injectWizard()` return `T | null`; chain optional access (`form?.register('email')`) at every consumption site.
 - **Put labels on the schema, not the template.** `z.string().register(fieldMeta, { label: 'Email' })`; read it back through `form.fields.email.label` (resolved, with a humanized-path fallback).
 - **Native inputs first.** Bind `<input>`, `<select>`, `<textarea>` with `v-register`. Reach for `useRegister` only inside a custom input component. See `references/custom-components.md`.
-- **`v-register` alone does binding, SSR value injection, and ARIA.** Do not stack `@change` handlers, reset-signal props, or watchers on top of it. If a control seems to need that scaffolding, the idiomatic shape is being missed.
+- **`v-register` alone does binding, SSR value injection, and ARIA.** Do not stack a second _writer_ on it: no `v-model`, no handler that writes the field back, no reset-signal prop. If a control seems to need that scaffolding, the idiomatic shape is being missed.
+- **Observing the field is fine, and is how a per-interaction save is built.** A `@change` that only reads, or a `watch(form.toRef('path'), ...)`, sits beside `v-register` without fighting it: the directive writes the field before your handler runs, so the value you read is the committed one. Reach for this whenever a surface persists each decision as it is made rather than on submit. See `references/saving.md`.
 
 ## Wizards
 
@@ -119,6 +122,7 @@ Load one when the task reaches its area:
 - **`references/custom-components.md`**: wrapping an input or binding a third-party component. `useRegister`, the three orthogonal primitives, attribute fallthrough, and the optional `form-key` prop.
 - **`references/ssr.md`**: debugging SSR and hydration. Why the value injection is a build-time transform, how to confirm it faithfully, and the test traps to avoid.
 - **`references/validation.md`**: designing the schema. Client-is-UX / server-is-truth, keeping closed sets in sync, and why a clearable edit field is a required string.
+- **`references/saving.md`**: persisting each decision as it is made. Choosing between an observing listener and a `watch`, the ordering that makes a listener safe, and the four things a production autosave adds.
 
 ## Going deeper
 

package/skills/attaform/references/custom-components.md

@@ -49,11 +49,16 @@ For a **compound** component that binds _multiple_ paths (a date range exposing
 
 - Read the display signals straight in the template: `field.showErrors` gates the error row, `field.showPending` gates an async "checking" indicator (it is anti-flash timed), `field.firstError?.message` is the text.
 - `v-register`'s `autoAria` (on by default) keeps `aria-invalid`, `aria-busy`, and `aria-required` in sync. It wires the _error_ id, and only while the field is in its error state, so author `aria-describedby` yourself if a _static_ hint should stay associated too.
-- **`v-register` alone does binding, SSR value injection, and ARIA.** Do not stack `@change` handlers, `:reset-signal` props, redundant directive imports, or watchers on top of it. If a control seems to need that scaffolding, find the idiomatic shape rather than hand-rolling around it.
+- **`v-register` alone does binding, SSR value injection, and ARIA.** Do not stack a second _writer_ on it: no `v-model`, no handler that writes the field back, no `:reset-signal` prop, no redundant directive import. If a control seems to need that scaffolding, find the idiomatic shape rather than hand-rolling around it.
+- **An _observer_ is not a second writer.** A `@change` that only reads, or a `watch(form.toRef('path'), ...)`, is supported beside `v-register`. The directive attaches its own listener in the `created` hook, before Vue applies yours, so it writes the field first and your handler reads committed state. That is the shape for a surface that saves each decision as it is made instead of on submit; see `references/saving.md`.
 
 ## Third-party components
 
-`v-register` binds a third-party component host, not just a native element, as long as the component renders a real form control and forwards attributes to it. The directive marks the host and injects the same binding, SSR, and ARIA it gives a native input.
+`v-register` binds a third-party component host, not just a native element. The directive marks the host and injects the same binding, SSR, and ARIA it gives a native input.
+
+When the component renders exactly one real form control and forwards attributes to it, that control becomes the field's anchor: focus and blur tracking, ARIA, and the invalid-submit focus target all land on it. A **composite** widget (a PIN input of several boxes) or a **control-less** one (a slider built from `<div>`s) binds too; the directive declines the single-element latch and tracks focus at the widget root instead. Do not reach for an escape hatch on account of either.
+
+The one shape that loses the directive half is a component whose root is a **fragment**, because Vue hands a runtime directive only to a single-element root. The value channel still works there; wrap it in an element you control to get the rest back.
 
 ## Do not re-declare native attributes as props
 

package/skills/attaform/references/errors.md

@@ -17,7 +17,8 @@ const onSubmit = form.handleSubmit(async (values) => {
 })
 ```
 
-- `setErrors(errors | updater | (path, errors))` is a **whole-layer replace**, so `clearErrors()` at the top of a fresh attempt drops errors a previous submit set. `clearErrors(path?)` scopes the clear.
+- `setErrors(errors | updater | (path, errors))` is a **whole-layer replace** of the user layer, so `clearErrors()` at the top of a fresh attempt drops errors a previous submit set. `clearErrors(path?)` scopes the clear.
+- `clearErrors` clears the **schema layer too**, at whatever path it targets, not just the user one. Inside a submit callback that costs nothing, since validation has already passed to get there, and with always-on validation the schema half re-populates on the next mutation if the value is still wrong. Pass `setErrors([])` instead when you mean to empty the user layer alone.
 - `handleSubmit` focuses the first offending field for user-set errors exactly as it does for client-invalid fields, so a `setErrors` call inside the callback needs no separate focus step.
 
 ## The `ValidationError` envelope
@@ -27,7 +28,11 @@ If your backend emits Attaform's `ValidationError` shape, it pipes straight into
 ```ts
 import type { ValidationError, Json } from 'attaform'
 
-// { message: string; path: (string | number)[]; code?: string; data?: Json | null }
+// ValidationError, what you READ BACK:
+// { message: string; path: (string | number)[]; code: string; data?: Json | null }
+// What setErrors ACCEPTS is looser: every field optional, plus a bare
+// Error. A missing message becomes 'Unknown error', a missing path is
+// [] (form level), a missing code is 'atta:user-error'.
 ```
 
 - One entry per message at `path: [field]`; a form-level error is `path: []`; a dotted key splits into segments.
@@ -55,7 +60,7 @@ A form-level banner wants the root's **own** bucket, not the aggregate:
 const banner = computed(() => form.meta.firstOwnError)
 ```
 
-Do not use `form.errors([])` for a banner: `errors(path)` uniformly means "path plus descendants", so `errors([])` is the whole-form aggregate and would surface individual field errors in the summary. `form.meta.firstOwnError` is the correct root-only read. The same own axis surfaces a container-level `.refine()` error, for example `form.fields.address.firstOwnError`.
+Do not use `form.errors([])` for a banner: `errors(path)` uniformly means "path plus descendants", so `errors([])` is the whole-form aggregate and would surface individual field errors in the summary. `form.meta.firstOwnError` is the correct root-only read. The same own axis surfaces a container-level `.refine()` error, through the CALL form: `form.fields('address').firstOwnError`. Dot access on a container (`form.fields.address`) is navigation toward leaves and carries no error state of its own, so the dotted spelling reads `undefined` no matter what the container holds.
 
 ## One normalizer, always non-empty
 

package/skills/attaform/references/saving.md

@@ -0,0 +1,77 @@
+# Saving as the user goes
+
+A surface that persists each decision as it is made, instead of on a submit, is a supported shape. It needs no scaffolding around `v-register` and no redesign toward a batch Save button. Two shapes fit it, and the one to reach for follows what the reaction belongs to.
+
+- The reaction belongs to the **interaction** (one pick is one whole decision: a `<select>`, a checkbox, a radio, a star rating) → a plain listener beside `v-register`.
+- The reaction belongs to the **value** (typing, or anything that must also catch a programmatic write) → `watch(form.toRef(path), ...)`.
+
+The deciding fact when a form both saves per change and hydrates itself from a saved record: a DOM listener never sees `form.setValue` or `form.reset()`, because neither fires a DOM event. Only the watch does.
+
+## The listener shape
+
+```vue
+<script setup lang="ts">
+  import { z } from 'zod'
+  import { useForm } from 'attaform'
+
+  const schema = z.object({ choice: z.string() })
+  const form = useForm({ schema })
+
+  async function save() {
+    // Already the newly picked value: the directive wrote it first.
+    await fetch('/api/choice', {
+      method: 'PATCH',
+      body: JSON.stringify({ value: form.values.choice }),
+    })
+  }
+</script>
+
+<template>
+  <select v-register="form.register('choice')" @change="save">
+    <option value="yes">Yes</option>
+    <option value="no">No</option>
+  </select>
+</template>
+```
+
+`v-register` attaches its own listener in Vue's `created` hook, which runs before Vue applies the handlers you wrote. The directive's listener is therefore registered first, fires first, and has written the field by the time yours is called, so the handler reads committed state rather than the previous value. That ordering is a pinned contract, not an accident of timing, and it holds for `@change`, `@input`, a `v-register.lazy` control, a checkbox, and a radio.
+
+An observing handler is **not** a second writer. Nothing is stacked, and neither the compile-time nor the runtime redundant-binding guard flags it. What stays forbidden is a second _writer_: a `v-model`, a handler that writes the field back, a reset-signal prop.
+
+## The watch shape
+
+```ts
+import { watch } from 'vue'
+import { z } from 'zod'
+import { useForm } from 'attaform'
+
+const schema = z.object({ bio: z.string() })
+const form = useForm({ schema })
+
+async function save(value: string): Promise<void> {
+  await fetch('/api/bio', { method: 'PATCH', body: JSON.stringify({ value }) })
+}
+
+// `form.toRef(path)` is a read-only ref over that path's value, so this
+// fires on every committed change, including `setValue` and `reset`.
+watch(form.toRef('bio'), (value) => {
+  void save(value)
+})
+```
+
+Registered inside `setup`, so the watchers stop on unmount with no manual teardown. Writing the same value back is a no-op in Attaform, so a watcher never fires for a write that changed nothing. For a whole container path, add `{ deep: true }`: an in-place leaf edit keeps the container's reference stable.
+
+## What a real one adds
+
+The full recipe at https://attaform.dev/docs/cross-cutting-state/autosave is copy-paste and carries the parts a production autosave needs. Reproduce these rather than shipping the bare watch above:
+
+- **Debounce per path**, because typing is continuous and a keystroke is not a decision. For a per-interaction surface the wait is pointless: keep the recipe and pass `{ debounceMs: 0 }`.
+- **A validity gate.** Run `form.parse(path, { commit: true })` and skip the write when it fails, so an invalid value never reaches the server and async refinements run as part of the same check. Turn it off per path for a true draft save.
+- **Abort on supersede.** One `AbortController` per path, handed to `fetch` as its `signal`, so a slow request cancels when a newer edit lands and the latest write wins.
+- **A pause for your own writes.** This is the one that bites. A watch reacts to every change including yours, so hydrating ten fields from a saved record echoes ten saves straight back at the server you just loaded from. Wrap a hydrating `setValue` or `reset` so the watchers skip it. The pause belongs to your composable, never to the form.
+
+## Do not trade away the rendering to get the saving
+
+Both shapes leave `v-register` in place, so the control keeps its binding, its ARIA, and its SSR value injection. That last one is worth naming, because a row of server-rendered `<select>` elements is where it shows: a selection is a DOM property rather than markup, so the server can only express it as `selected` on the right `<option>`, and hand-binding that per call site is a step every new row can forget. `v-register` emits it for every option it owns.
+
+Saving per decision never costs you that. Guidance that implies otherwise, and sends an author to a batch submit to keep their server-rendered state correct, is wrong.

package/skills/attaform/references/wizards.md

@@ -12,6 +12,8 @@ A step slot is one of:
 - a **function** returning any of those, for runtime branching,
 - a `lazy((ctx) => ...)`-wrapped function, which memoizes its resolution and re-fires only when its own tracked reads change.
 
+`gate(slot)` wraps any of them rather than being a kind of its own: it marks that position a hard prerequisite and leaves how the slot resolves alone. A function slot may return one, so whether a position is a gate can itself be a runtime decision.
+
 ```ts
 import { useForm, useWizard } from 'attaform'
 
@@ -24,7 +26,7 @@ const wizard = useWizard({ key: 'onboarding', steps: [account, 'review', profile
 ## Navigation vs submission
 
 - **`wizard.tryNext(): Promise<boolean>`** is the gated Next. It validates the active step and advances only on a clean pass, revealing that step's errors in place otherwise. It resolves to whether it advanced, and it is inline-bindable: `@click="wizard.tryNext()"`.
-- **`wizard.next()` / `wizard.back()` / `wizard.goTo(key)`** are positional moves with no validation gate. Use them for a Back button or a jump; use `tryNext` for a forward move that should validate.
+- **`wizard.next()` / `wizard.back()` / `wizard.goTo(key)`** are positional moves with no validation gate. Use them for a Back button or a jump; use `tryNext` for a forward move that should validate. Two exceptions: they refuse while a submit is in flight, and `next()` on an **uncleared `gate()` step behaves as `tryNext()`**, so wiring Next straight to it can never skip the gate's confirmation. Once that gate clears, `next()` is plain navigation again and does not re-submit.
 - **`wizard.handleSubmit(onSubmit, onError?)`** validates **every** step from any position and calls `onSubmit` once with all forms' values. It **never advances**. Wire it to the final Submit.
 
 For a forward move that runs a custom callback before advancing, compose the step form's own submit with `next`:
@@ -58,9 +60,9 @@ const onComplete = wizard.handleSubmit(async (ctx) => {
 
 The wizard handle exposes the flow's rolled-up state, all reactive:
 
-- `wizard.forms[key]`: the live form handle for a step (a facade typed as a form).
+- `wizard.forms[key]`: the step's own form handle, identity-equal to the `useForm` ref that was slotted in.
 - `wizard.allValues` / `wizard.allErrors`: every form's values / aggregate errors, keyed.
-- `wizard.activeForm`: the currently active step's form facade.
+- `wizard.activeForm`: a live facade over whichever step is active, so a handler captured once retargets as the pin moves. Not the handle itself: use `wizard.forms[key]` for that.
 - `wizard.statuses`: per-form status. Plus `wizard.progress`, `wizard.canAdvance`, `wizard.canGoBack`, `wizard.isFinalStep`, `wizard.visited`.
 
 ## A declarative step registry
@@ -94,11 +96,11 @@ const wizard = useWizard({
 
 Everything derives from the registry: the step slots, the titles, any persisted key list. Add, remove, reorder, or gate a step by editing the registry alone. Do not add speculative registry fields with no consumer; add a hook when the second consumer arrives.
 
-## Keyed injection resolves by tree and timing
+## Keyed injection resolves by name and timing
 
-A string key passed to `injectForm('account')` or `injectWizard('onboarding')` _reads_ like a global address but resolves by the **caller's component-tree position and mount timing**, not as a global lookup:
+A string key passed to `injectForm('account')` or `injectWizard('onboarding')` is a name in Attaform's app-level registry, not a location in the component tree:
 
-- `provide` / `inject` is descendant-only, so a form created in a **leaf** is unreachable from an **ancestor**.
-- A keyed form is not resolvable until the creating component's `setup` has run, so mount order matters.
+- **Position-independent.** The lookup reaches any component in the app: a sibling branch, a floating toolbar, a teleported modal. Extracting a wrapper or changing how deep a component sits never changes what a key resolves to. The no-key ambient form is the opposite, and is the one that runs on `provide` / `inject`: it reaches descendants of the owning `useForm` only.
+- **Time-dependent.** The registry entry appears when the owner's own `useForm({ key })` / `useWizard({ key })` setup runs, and not before.
 
-The consequence: a purely structural refactor can silently break a lookup. The stable shape is to **lift a shared form's creation to the coordinating ancestor** (the component that owns the wizard) and have leaves `injectForm(key)` it downward by a prop key. Always chain `?.` on the result, which is `T | null`.
+Together they give one rule: **resolve downward.** Vue runs a parent's setup before its children's, so a descendant reaching an ancestor's keyed form always resolves, while an ancestor reaching a descendant's gets `null`. The stable shape is to **lift a shared form's creation to the coordinating ancestor** (the component that owns the wizard) and reach for it at or below that point. Always chain `?.` on the result, which is `T | null`.

package/dist/abstract.cjs

@@ -1,48 +0,0 @@
-'use strict';
-
-const serializeScript = require('./shared/attaform.DrvMscNX.cjs');
-const devtoolsShared = require('./shared/attaform.Biytrv0-.cjs');
-const registerProtocol = require('./shared/attaform.yUrz7C2z.cjs');
-
-
-
-exports.AttaformErrorCode = serializeScript.AttaformErrorCode;
-exports.DEFAULT_TIMINGS = serializeScript.DEFAULT_TIMINGS;
-exports.defaultCoercionRules = serializeScript.defaultCoercionRules;
-exports.defaultDisplayState = serializeScript.defaultDisplayState;
-exports.defineCoercion = serializeScript.defineCoercion;
-exports.escapeForInlineScript = serializeScript.escapeForInlineScript;
-exports.gate = serializeScript.gate;
-exports.injectForm = serializeScript.injectForm;
-exports.injectWizard = serializeScript.injectWizard;
-exports.isUnset = serializeScript.isUnset;
-exports.lazy = serializeScript.lazy;
-exports.makeDefaultDisplayState = serializeScript.makeDefaultDisplayState;
-exports.unset = serializeScript.unset;
-exports.useAbstractForm = serializeScript.useAbstractForm;
-exports.useRegister = serializeScript.useRegister;
-exports.useWizard = serializeScript.useWizard;
-exports.AttaformError = devtoolsShared.AttaformError;
-exports.DEVTOOLS_WINDOW_KEY = devtoolsShared.DEVTOOLS_WINDOW_KEY;
-exports.InvalidPathError = devtoolsShared.InvalidPathError;
-exports.InvalidUseFormConfigError = devtoolsShared.InvalidUseFormConfigError;
-exports.OutsideSetupError = devtoolsShared.OutsideSetupError;
-exports.ROOT_PATH = devtoolsShared.ROOT_PATH;
-exports.ROOT_PATH_KEY = devtoolsShared.ROOT_PATH_KEY;
-exports.RegistryNotInstalledError = devtoolsShared.RegistryNotInstalledError;
-exports.ReservedFormKeyError = devtoolsShared.ReservedFormKeyError;
-exports.SubmitErrorHandlerError = devtoolsShared.SubmitErrorHandlerError;
-exports.assignKey = devtoolsShared.assignKey;
-exports.canonicalizePath = devtoolsShared.canonicalizePath;
-exports.createAttaform = devtoolsShared.createAttaform;
-exports.createRegistry = devtoolsShared.createRegistry;
-exports.getRegistryFromApp = devtoolsShared.getRegistryFromApp;
-exports.hydrateAttaformState = devtoolsShared.hydrateAttaformState;
-exports.isPathPrefix = devtoolsShared.isPathPrefix;
-exports.kAttaformRegistry = devtoolsShared.kAttaformRegistry;
-exports.parseDottedPath = devtoolsShared.parseDottedPath;
-exports.renderAttaformState = devtoolsShared.renderAttaformState;
-exports.useRegistry = devtoolsShared.useRegistry;
-exports.vRegister = devtoolsShared.vRegister;
-exports.isRegisterValue = registerProtocol.isRegisterValue;
-//# sourceMappingURL=abstract.cjs.map

package/dist/abstract.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"abstract.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/abstract.d.cts

@@ -1,42 +0,0 @@
-import { A as AttaformRegistry } from './shared/attaform.FmqKO1Ex.cjs';
-export { a as AnyForm, b as AttaformDevtoolsBridge, c as AttaformError, d as AttaformErrorCode, e as AttaformPluginOptions, C as CompiledStep, D as DEFAULT_TIMINGS, f as DEVTOOLS_WINDOW_KEY, g as DisplayTimings, F as FormStatus, h as FormStatusSeed, G as GateMarker, I as InjectWizardInput, i as InvalidPathError, j as InvalidUseFormConfigError, L as LazyMarker, O as OutsideSetupError, R as RegistryNotInstalledError, k as ReservedFormKeyError, S as SerializedAttaformState, l as SerializedFormData, m as StepSlot, n as SubmitErrorHandlerError, U as UseRegisterReturn, o as UseWizardReturnType, W as WizardAggregateError, p as WizardCtx, q as WizardCtxForm, r as WizardOnError, s as WizardOnSubmit, t as WizardOptions, u as WizardPersistFn, v as WizardRestoreFn, w as WizardRestoreState, x as WizardStatusesProxy, y as WizardSubmitContext, z as assignKey, B as createAttaform, E as createRegistry, H as defaultCoercionRules, J as defaultDisplayState, K as defineCoercion, M as escapeForInlineScript, N as gate, P as getRegistryFromApp, Q as hydrateAttaformState, T as injectForm, V as injectWizard, X as isRegisterValue, Y as kAttaformRegistry, Z as lazy, _ as makeDefaultDisplayState, $ as renderAttaformState, a0 as useRegister, a1 as useRegistry, a2 as useWizard, a3 as vRegister } from './shared/attaform.FmqKO1Ex.cjs';
-import { G as GenericForm, F as FormKey, U as UseFormConfiguration, A as AbstractSchema, D as DefaultValuesInput, a as UseFormReturnType } from './shared/attaform.DniawQLP.cjs';
-export { b as ArrayItem, c as ArrayPath, d as AttaformDefaults, C as CoercionEntry, e as CoercionRegistry, f as CoercionResult, g as CustomDirectiveRegisterAssignerFn, h as DeepPartial, i as DefaultValuesResponse, j as DefaultValuesShape, k as DisplayCtx, l as DisplayMachine, m as DisplayState, E as ErrorInput, n as ErrorsProxyShape, o as FieldMetaPayload, p as FieldState, q as FieldStateMap, r as FieldStateMapEntry, s as FlatPath, t as FormErrorRecord, u as FormErrorsSurface, v as FormMeta, w as GetDisplayState, H as HandleSubmit, x as HistoryConfig, I as IsTuple, y as IsUnion, J as JoinSegments, z as Json, K as KeyofUnion, L as LiftedValueShape, M as MetaTrackerValue, N as NestedReadType, B as NestedType, O as OnError, P as OnInvalidSubmitPolicy, Q as OnSubmit, R as PartialFlatPath, S as Path, T as PathKey, V as PendingValidationStatus, W as Primitive, X as ROOT_PATH, Y as ROOT_PATH_KEY, Z as ReactiveValidationStatus, _ as RegisterDirective, $ as RegisterFlatPath, a0 as RegisterOptions, a1 as RegisterSelectModifier, a2 as RegisterTextModifier, a3 as RegisterTransform, a4 as RegisterValue, a5 as Segment, a6 as SetValueCallback, a7 as SetValuePayload, a8 as SettledValidationStatus, a9 as SlimPrimitiveKind, aa as SlimRuntimeOf, ab as SubmitHandler, ac as Unset, ad as ValidateOn, ae as ValidateOnConfig, af as ValidationError, ag as ValidationResponse, ah as ValidationResponseWithoutValue, ai as ValueOfUnion, aj as WriteMeta, ak as WriteShape, al as canonicalizePath, am as isPathPrefix, an as isUnset, ao as parseDottedPath, ap as unset } from './shared/attaform.DniawQLP.cjs';
-import 'vue';
-
-/**
- * Schema-agnostic `useForm`. Accepts any object that implements
- * `AbstractSchema` — useful when integrating a custom schema
- * adapter or a third-party validation library.
- *
- * ```ts
- * import { useForm } from 'attaform'
- *
- * const form = useForm({
- *   schema: myCustomAdapter,
- *   defaultValues: { name: '' },
- * })
- * ```
- *
- * Most consumers prefer a typed entry point that wraps the underlying
- * library's schema with the matching adapter automatically; see the
- * subpath documentation for the available adapters.
- *
- * Returns the same form API as the typed entry points; see
- * `UseFormReturnType` for the full surface.
- */
-declare function useAbstractForm<Form extends GenericForm, GetValueFormType extends GenericForm = Form, ReadForm extends GenericForm = Form, K extends FormKey = FormKey>(configuration: UseFormConfiguration<Form, GetValueFormType, AbstractSchema<Form, GetValueFormType>, DefaultValuesInput<Form>, K>, 
-/**
- * Internal escape hatch for callers that already hold a registry
- * reference and need to construct a form outside Vue's setup context
- * (e.g. the wizard's lazy noop builder, which runs inside a
- * `computed` re-eval). Passing this skips the strict `useRegistry()`
- * call; everything else (FormStore allocation, registry presence,
- * consumer ref-counting via `onScopeDispose`) goes through the same
- * path eager calls follow. Not part of the public surface.
- */
-options?: {
-    readonly registry?: AttaformRegistry;
-}): UseFormReturnType<Form, GetValueFormType, ReadForm, K>;
-
-export { AbstractSchema, AttaformRegistry, DefaultValuesInput, FormKey, GenericForm, UseFormConfiguration, UseFormReturnType, useAbstractForm };

package/dist/abstract.d.ts

@@ -1,42 +0,0 @@
-import { A as AttaformRegistry } from './shared/attaform.F2Q8iv38.js';
-export { a as AnyForm, b as AttaformDevtoolsBridge, c as AttaformError, d as AttaformErrorCode, e as AttaformPluginOptions, C as CompiledStep, D as DEFAULT_TIMINGS, f as DEVTOOLS_WINDOW_KEY, g as DisplayTimings, F as FormStatus, h as FormStatusSeed, G as GateMarker, I as InjectWizardInput, i as InvalidPathError, j as InvalidUseFormConfigError, L as LazyMarker, O as OutsideSetupError, R as RegistryNotInstalledError, k as ReservedFormKeyError, S as SerializedAttaformState, l as SerializedFormData, m as StepSlot, n as SubmitErrorHandlerError, U as UseRegisterReturn, o as UseWizardReturnType, W as WizardAggregateError, p as WizardCtx, q as WizardCtxForm, r as WizardOnError, s as WizardOnSubmit, t as WizardOptions, u as WizardPersistFn, v as WizardRestoreFn, w as WizardRestoreState, x as WizardStatusesProxy, y as WizardSubmitContext, z as assignKey, B as createAttaform, E as createRegistry, H as defaultCoercionRules, J as defaultDisplayState, K as defineCoercion, M as escapeForInlineScript, N as gate, P as getRegistryFromApp, Q as hydrateAttaformState, T as injectForm, V as injectWizard, X as isRegisterValue, Y as kAttaformRegistry, Z as lazy, _ as makeDefaultDisplayState, $ as renderAttaformState, a0 as useRegister, a1 as useRegistry, a2 as useWizard, a3 as vRegister } from './shared/attaform.F2Q8iv38.js';
-import { G as GenericForm, F as FormKey, U as UseFormConfiguration, A as AbstractSchema, D as DefaultValuesInput, a as UseFormReturnType } from './shared/attaform.DniawQLP.js';
-export { b as ArrayItem, c as ArrayPath, d as AttaformDefaults, C as CoercionEntry, e as CoercionRegistry, f as CoercionResult, g as CustomDirectiveRegisterAssignerFn, h as DeepPartial, i as DefaultValuesResponse, j as DefaultValuesShape, k as DisplayCtx, l as DisplayMachine, m as DisplayState, E as ErrorInput, n as ErrorsProxyShape, o as FieldMetaPayload, p as FieldState, q as FieldStateMap, r as FieldStateMapEntry, s as FlatPath, t as FormErrorRecord, u as FormErrorsSurface, v as FormMeta, w as GetDisplayState, H as HandleSubmit, x as HistoryConfig, I as IsTuple, y as IsUnion, J as JoinSegments, z as Json, K as KeyofUnion, L as LiftedValueShape, M as MetaTrackerValue, N as NestedReadType, B as NestedType, O as OnError, P as OnInvalidSubmitPolicy, Q as OnSubmit, R as PartialFlatPath, S as Path, T as PathKey, V as PendingValidationStatus, W as Primitive, X as ROOT_PATH, Y as ROOT_PATH_KEY, Z as ReactiveValidationStatus, _ as RegisterDirective, $ as RegisterFlatPath, a0 as RegisterOptions, a1 as RegisterSelectModifier, a2 as RegisterTextModifier, a3 as RegisterTransform, a4 as RegisterValue, a5 as Segment, a6 as SetValueCallback, a7 as SetValuePayload, a8 as SettledValidationStatus, a9 as SlimPrimitiveKind, aa as SlimRuntimeOf, ab as SubmitHandler, ac as Unset, ad as ValidateOn, ae as ValidateOnConfig, af as ValidationError, ag as ValidationResponse, ah as ValidationResponseWithoutValue, ai as ValueOfUnion, aj as WriteMeta, ak as WriteShape, al as canonicalizePath, am as isPathPrefix, an as isUnset, ao as parseDottedPath, ap as unset } from './shared/attaform.DniawQLP.js';
-import 'vue';
-
-/**
- * Schema-agnostic `useForm`. Accepts any object that implements
- * `AbstractSchema` — useful when integrating a custom schema
- * adapter or a third-party validation library.
- *
- * ```ts
- * import { useForm } from 'attaform'
- *
- * const form = useForm({
- *   schema: myCustomAdapter,
- *   defaultValues: { name: '' },
- * })
- * ```
- *
- * Most consumers prefer a typed entry point that wraps the underlying
- * library's schema with the matching adapter automatically; see the
- * subpath documentation for the available adapters.
- *
- * Returns the same form API as the typed entry points; see
- * `UseFormReturnType` for the full surface.
- */
-declare function useAbstractForm<Form extends GenericForm, GetValueFormType extends GenericForm = Form, ReadForm extends GenericForm = Form, K extends FormKey = FormKey>(configuration: UseFormConfiguration<Form, GetValueFormType, AbstractSchema<Form, GetValueFormType>, DefaultValuesInput<Form>, K>, 
-/**
- * Internal escape hatch for callers that already hold a registry
- * reference and need to construct a form outside Vue's setup context
- * (e.g. the wizard's lazy noop builder, which runs inside a
- * `computed` re-eval). Passing this skips the strict `useRegistry()`
- * call; everything else (FormStore allocation, registry presence,
- * consumer ref-counting via `onScopeDispose`) goes through the same
- * path eager calls follow. Not part of the public surface.
- */
-options?: {
-    readonly registry?: AttaformRegistry;
-}): UseFormReturnType<Form, GetValueFormType, ReadForm, K>;
-
-export { AbstractSchema, AttaformRegistry, DefaultValuesInput, FormKey, GenericForm, UseFormConfiguration, UseFormReturnType, useAbstractForm };

package/dist/abstract.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"abstract.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}

package/dist/chunks/dev-key-collision-warnings.cjs

@@ -1,25 +0,0 @@
-'use strict';
-
-async function warnOnSchemaFingerprintMismatch(key, existing, incoming) {
-  let existingFp;
-  let incomingFp;
-  try {
-    existingFp = await existing.fingerprint();
-    incomingFp = await incoming.fingerprint();
-  } catch (error) {
-    console.error(
-      `[attaform] fingerprint() rejected for key "${key}"; skipping mismatch check.`,
-      error
-    );
-    return;
-  }
-  if (existingFp === incomingFp) return;
-  console.warn(
-    `[attaform] useForm() calls with key "${key}" use different schemas; first wins, second is ignored. Use identical schemas or unique keys.
-  existing: ${existingFp}
-  incoming: ${incomingFp}`
-  );
-}
-
-exports.warnOnSchemaFingerprintMismatch = warnOnSchemaFingerprintMismatch;
-//# sourceMappingURL=dev-key-collision-warnings.cjs.map

package/dist/chunks/dev-key-collision-warnings.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"dev-key-collision-warnings.cjs","sources":["../../src/runtime/core/dev-key-collision-warnings.ts"],"sourcesContent":["/**\n * Dev-only shared-key collision diagnostics for `useForm`. When two\n * `useForm({ key })` calls land on the same key, they resolve to one\n * `FormStore` by design (the shared-store semantic), and the second\n * call's schema is silently dropped in favour of the first's wiring.\n * The warnings here surface that divergence so a genuine collision (two\n * unrelated call sites that happen to agree on a key) is diagnosable\n * rather than silent.\n *\n * This whole module is loaded behind a `__DEV__`-gated dynamic import in\n * `use-abstract-form.ts`. A production build folds that gate to `false`,\n * dead-code-eliminates the `import()` call, and leaves this module an\n * unreferenced chunk the consumer's bundler drops. Keeping the warnings\n * here (rather than as plain functions called from the gated block)\n * matters because esbuild removes the inline dead branch but NOT a\n * top-level function it is the sole caller of: tree-shaking runs before\n * the define-fold, so the function survives. A separately-imported\n * module sidesteps that and keeps the cluster out of every consumer's\n * production bundle.\n */\nimport type { AbstractSchema, FormKey } from '../types/types-api'\nimport type { GenericForm } from '../types/types-core'\n\n/**\n * Dev-only: warn when a second `useForm` lands on the same key with\n * a structurally-different schema. Two schemas resolve their own\n * fingerprints; we compare the strings and flag mismatches. An adapter\n * `fingerprint()` that rejects is caught (never crashes the form) and\n * surfaced as a `console.error` in dev: the mismatch check is skipped,\n * matching the \"allow the inconsistency\" failure mode. See\n * `AbstractSchema.fingerprint()` in types-api.ts for the contract.\n */\nexport async function warnOnSchemaFingerprintMismatch(\n  key: FormKey,\n  existing: AbstractSchema<GenericForm, GenericForm>,\n  incoming: AbstractSchema<GenericForm, GenericForm>\n): Promise<void> {\n  let existingFp: string\n  let incomingFp: string\n  try {\n    existingFp = await existing.fingerprint()\n    incomingFp = await incoming.fingerprint()\n  } catch (error) {\n    console.error(\n      `[attaform] fingerprint() rejected for key \"${key}\"; skipping mismatch check.`,\n      error\n    )\n    return\n  }\n  if (existingFp === incomingFp) return\n  console.warn(\n    `[attaform] useForm() calls with key \"${key}\" use different schemas; first wins, second is ignored. Use identical schemas or unique keys.\\n  existing: ${existingFp}\\n  incoming: ${incomingFp}`\n  )\n}\n"],"names":[],"mappings":";;AAgCA,eAAsB,+BAAA,CACpB,GAAA,EACA,QAAA,EACA,QAAA,EACe;AACf,EAAA,IAAI,UAAA;AACJ,EAAA,IAAI,UAAA;AACJ,EAAA,IAAI;AACF,IAAA,UAAA,GAAa,MAAM,SAAS,WAAA,EAAY;AACxC,IAAA,UAAA,GAAa,MAAM,SAAS,WAAA,EAAY;AAAA,EAC1C,SAAS,KAAA,EAAO;AACd,IAAA,OAAA,CAAQ,KAAA;AAAA,MACN,8CAA8C,GAAG,CAAA,2BAAA,CAAA;AAAA,MACjD;AAAA,KACF;AACA,IAAA;AAAA,EACF;AACA,EAAA,IAAI,eAAe,UAAA,EAAY;AAC/B,EAAA,OAAA,CAAQ,IAAA;AAAA,IACN,wCAAwC,GAAG,CAAA;AAAA,YAAA,EAA8G,UAAU;AAAA,YAAA,EAAiB,UAAU,CAAA;AAAA,GAChM;AACF;;;;"}

package/dist/chunks/dev-key-collision-warnings.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"dev-key-collision-warnings.mjs","sources":["../../src/runtime/core/dev-key-collision-warnings.ts"],"sourcesContent":["/**\n * Dev-only shared-key collision diagnostics for `useForm`. When two\n * `useForm({ key })` calls land on the same key, they resolve to one\n * `FormStore` by design (the shared-store semantic), and the second\n * call's schema is silently dropped in favour of the first's wiring.\n * The warnings here surface that divergence so a genuine collision (two\n * unrelated call sites that happen to agree on a key) is diagnosable\n * rather than silent.\n *\n * This whole module is loaded behind a `__DEV__`-gated dynamic import in\n * `use-abstract-form.ts`. A production build folds that gate to `false`,\n * dead-code-eliminates the `import()` call, and leaves this module an\n * unreferenced chunk the consumer's bundler drops. Keeping the warnings\n * here (rather than as plain functions called from the gated block)\n * matters because esbuild removes the inline dead branch but NOT a\n * top-level function it is the sole caller of: tree-shaking runs before\n * the define-fold, so the function survives. A separately-imported\n * module sidesteps that and keeps the cluster out of every consumer's\n * production bundle.\n */\nimport type { AbstractSchema, FormKey } from '../types/types-api'\nimport type { GenericForm } from '../types/types-core'\n\n/**\n * Dev-only: warn when a second `useForm` lands on the same key with\n * a structurally-different schema. Two schemas resolve their own\n * fingerprints; we compare the strings and flag mismatches. An adapter\n * `fingerprint()` that rejects is caught (never crashes the form) and\n * surfaced as a `console.error` in dev: the mismatch check is skipped,\n * matching the \"allow the inconsistency\" failure mode. See\n * `AbstractSchema.fingerprint()` in types-api.ts for the contract.\n */\nexport async function warnOnSchemaFingerprintMismatch(\n  key: FormKey,\n  existing: AbstractSchema<GenericForm, GenericForm>,\n  incoming: AbstractSchema<GenericForm, GenericForm>\n): Promise<void> {\n  let existingFp: string\n  let incomingFp: string\n  try {\n    existingFp = await existing.fingerprint()\n    incomingFp = await incoming.fingerprint()\n  } catch (error) {\n    console.error(\n      `[attaform] fingerprint() rejected for key \"${key}\"; skipping mismatch check.`,\n      error\n    )\n    return\n  }\n  if (existingFp === incomingFp) return\n  console.warn(\n    `[attaform] useForm() calls with key \"${key}\" use different schemas; first wins, second is ignored. Use identical schemas or unique keys.\\n  existing: ${existingFp}\\n  incoming: ${incomingFp}`\n  )\n}\n"],"names":[],"mappings":"AAgCA,eAAsB,+BAAA,CACpB,GAAA,EACA,QAAA,EACA,QAAA,EACe;AACf,EAAA,IAAI,UAAA;AACJ,EAAA,IAAI,UAAA;AACJ,EAAA,IAAI;AACF,IAAA,UAAA,GAAa,MAAM,SAAS,WAAA,EAAY;AACxC,IAAA,UAAA,GAAa,MAAM,SAAS,WAAA,EAAY;AAAA,EAC1C,SAAS,KAAA,EAAO;AACd,IAAA,OAAA,CAAQ,KAAA;AAAA,MACN,8CAA8C,GAAG,CAAA,2BAAA,CAAA;AAAA,MACjD;AAAA,KACF;AACA,IAAA;AAAA,EACF;AACA,EAAA,IAAI,eAAe,UAAA,EAAY;AAC/B,EAAA,OAAA,CAAQ,IAAA;AAAA,IACN,wCAAwC,GAAG,CAAA;AAAA,YAAA,EAA8G,UAAU;AAAA,YAAA,EAAiB,UAAU,CAAA;AAAA,GAChM;AACF;;;;"}