attaform 0.26.0 → 0.27.1

package/skills/attaform/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: attaform
+description: Build type-safe, schema-driven forms in Vue 3 and Nuxt with Attaform (first-class Zod). Use when creating, editing, or debugging a form (inputs, validation, submission, multistep wizards, or SSR) in a project that has the `attaform` package installed. Covers the correct import surface, the useForm handle, the v-register directive, reading validation state, handleSubmit, server-error routing, and wizards.
+license: MIT
+---
+
+# Building forms with Attaform
+
+Attaform turns a Zod schema into a reactive, typed Vue form: one schema declares the shape, the defaults, the validation, and the per-field errors, and Attaform builds the reactive surface around it. Use this skill when writing or editing a form in a project that depends on `attaform`.
+
+This file covers the common case end to end. For depth on one area, load the matching file in `references/` (indexed at the bottom).
+
+## Imports
+
+Everything comes from the `attaform` barrel:
+
+```ts
+import {
+  useForm,
+  useWizard,
+  injectForm,
+  injectWizard,
+  useRegister,
+  fieldMeta,
+  withMeta,
+  lazy,
+} 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.
+
+## Build a form
+
+Three moves: hoist the schema, hand it to `useForm`, bind each input with `v-register`. Submit through `form.handleSubmit`.
+
+```vue
+<script setup lang="ts">
+  import { useForm } from 'attaform'
+  import { z } from 'zod'
+
+  const schema = z.object({
+    email: z.email('Enter a valid email'),
+    password: z.string().min(8, 'At least 8 characters'),
+  })
+
+  const form = useForm({ schema, key: 'sign-in' })
+
+  const onSubmit = form.handleSubmit(async (values) => {
+    await fetch('/api/sign-in', { method: 'POST', body: JSON.stringify(values) })
+  })
+</script>
+
+<template>
+  <form @submit="onSubmit">
+    <label>
+      Email
+      <input v-register="form.register('email')" autocomplete="email" />
+      <em v-if="form.fields.email.showErrors">{{ form.fields.email.firstError?.message }}</em>
+    </label>
+    <label>
+      Password
+      <input v-register="form.register('password')" type="password" autocomplete="off" />
+      <em v-if="form.fields.password.showErrors">{{ form.fields.password.firstError?.message }}</em>
+    </label>
+    <button :disabled="form.meta.submitting" type="submit">Sign in</button>
+  </form>
+</template>
+```
+
+Prefer an explicit `key` (`useForm({ schema, key: 'sign-in' })`): it makes the form reachable through `injectForm('sign-in')`, survives parent refactors, and reads clearly at the call site. Anonymous `useForm({ schema })` is the fallback for a single throwaway form.
+
+## Rules
+
+- **Use the form handle. Don't destructure.** Keep `const form = useForm(...)` and reach for `form.register(...)`, `form.setValue(...)`, `form.meta`. Destructuring loses the reactive bindings.
+- **Bind with `v-register`; never write through `form.values`.** `form.values` is a read view and a callable proxy (`typeof form.values === 'function'`), so `schema.safeParse(form.values)` compiles but fails at runtime. Read `form.meta.valid` for validity; call `form.values()` for a plain snapshot (`form.values('a.b')` for a subtree).
+- **Let `handleSubmit` do the work.** It validates, calls `onSubmit` with the parsed values, and focuses the first offending field on an invalid submit. No manual focus and no `novalidate` ceremony. Bind it with `@submit`, not `@submit.prevent`: the handler calls `event.preventDefault()` for you, so `.prevent` only prevents twice.
+- **Never disable the submit button on validity.** Let the user click; the failed submit focuses the first error and reveals it. Gate only on `form.meta.submitting` or `!form.meta.dirty`. If a field's only guard was the disabled button, move the requirement into the schema (`.min(1)`, `.refine(...)`). See `references/validation.md`.
+- **Read errors through `field.showErrors` and `field.firstError?.message`.** The visibility heuristic lives in `showErrors`; reaching into `field.errors[0]` bypasses it. The async "checking" indicator is `field.showPending`.
+- **Route server errors through `form.setErrors(...)` inside the callback.** `setErrors` replaces the whole user-error layer, so call `form.clearErrors()` at the top of the submit for a fresh attempt. See `references/errors.md`.
+- **Banners read `form.meta.firstOwnError`,** the form's own error bucket, not `form.errors([])` (the whole-form aggregate). See `references/errors.md`.
+- **Accessibility is automatic.** `v-register` keeps `aria-invalid`, `aria-busy`, `aria-required`, and `aria-describedby` in sync and emits them during SSR. Put `form.fields.<path>.aria.errorId` on the error element so `aria-describedby` resolves. Author any ARIA attribute yourself to take it over, or pass `autoAria: false` to opt out.
+- **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.
+
+## Wizards
+
+Compose multiple `useForm` instances under `useWizard`. Navigation and submission are separate verbs: `wizard.tryNext()` is the gated Next (validates the active step, advances on a clean pass), and `wizard.handleSubmit(onSubmit)` validates every step from any position and calls `onSubmit` once with all values, but **never advances**.
+
+```ts
+import { useForm, useWizard } from 'attaform'
+
+const account = useForm({ schema: accountSchema, key: 'account' })
+const profile = useForm({ schema: profileSchema, key: 'profile' })
+
+const wizard = useWizard({ steps: [account, 'review', profile] })
+
+const onComplete = wizard.handleSubmit(async (ctx) => {
+  await fetch('/onboarding', { method: 'POST', body: JSON.stringify(ctx.values) })
+})
+```
+
+A step is a `useForm` reference, a bare string (an informational step with no schema), `null` / `undefined` (filtered out), or a function returning one of those. Full patterns, the declarative step registry, and the keyed-injection gotchas live in `references/wizards.md`.
+
+## SSR
+
+SSR is automatic under the Nuxt module or the Vite plugin: field values, `checked`, and `selected` are injected into the first paint and ARIA is emitted, with no extra wiring. Confirm any SSR behavior through the real build (curl the rendered HTML), not a bare unit render. The value injection is a build-time compiler transform that a plain Vitest render does not run. See `references/ssr.md`.
+
+## Reference files
+
+Load one when the task reaches its area:
+
+- **`references/wizards.md`**: multistep flows. The declarative step registry, `tryNext` vs `handleSubmit`, using a wizard as a flat multi-form coordinator, and how keyed `injectForm` / `injectWizard` resolve.
+- **`references/errors.md`**: routing server and API errors. The `ValidationError` envelope, `setErrors` / `clearErrors`, the own-vs-subtree error axis, banners, and the one-normalizer pattern.
+- **`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.
+
+## Going deeper
+
+- `llms.txt` (curated index): https://attaform.dev/llms.txt
+- `llms-full.txt` (every doc, concatenated): https://attaform.dev/llms-full.txt
+- Docs: https://attaform.dev
+- Source and issues: https://github.com/attaform/Attaform

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

@@ -0,0 +1,72 @@
+# Custom components
+
+Reach for these only when a native `<input>`, `<select>`, or `<textarea>` bound with `v-register` will not do. Most fields never need a wrapper.
+
+## Three orthogonal primitives
+
+There is deliberately no `useField(path)` that returns `{ register, fields, errors }` in one call. The three concerns are kept separate on purpose:
+
+- **`register(path)` returns an instance, not a path abstraction.** Two inputs can register the same path and move in sync: they share the path's field _state_, but each `register()` call has its own transforms and DOM lifecycle. A single bundled binding would have to pretend there is one binding per path.
+- **`fields(path)` is path-keyed leaf state**: `value`, `touched`, `dirty`, `blank`, `errors`, `label`, `aria`, the display signals. The noun is the path.
+- **`errors` is a related but separate concern**, not the same thing as field state.
+
+The three lines are the idiom, not a bundle. Small primitives age better than convenient bundles.
+
+## A single-field wrapper
+
+The parent binds with `v-register`; the wrapper re-forwards that same instance and reads state from it:
+
+```vue
+<!-- parent -->
+<UiTextField v-register="form.register('email')" type="email" />
+```
+
+```vue
+<!-- UiTextField.vue -->
+<script setup lang="ts">
+  import { computed } from 'vue'
+  import { injectForm, useRegister } from 'attaform'
+
+  const rv = useRegister() // the forwarded instance
+  const form = injectForm(rv?.formKey) // the owning form, by the instance's key
+  const field = computed(() => form?.fields(rv?.segments ?? [])) // reactive leaf state
+</script>
+
+<template>
+  <label>
+    <span>{{ field?.label }}</span>
+    <input v-register="rv" />
+    <em v-if="field?.showErrors">{{ field.firstError?.message }}</em>
+  </label>
+</template>
+```
+
+`rv` and `field` may be `undefined` until the parent directive attaches, so defend every read with `?.`. `rv.path`, `rv.segments`, and `rv.formKey` pierce directly in script setup without `.value`.
+
+For a **compound** component that binds _multiple_ paths (a date range exposing start and end, an address subform), skip `useRegister` (it assumes a single binding) and reach for `injectForm<Form>()`, then call `form.register(path)` for each field.
+
+## Let Attaform own display and ARIA
+
+- 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.
+
+## 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.
+
+## Do not re-declare native attributes as props
+
+Attribute fallthrough already delivers `id`, `aria-*`, `class`, and the like to the root element. Declare a Vue prop only when script needs to _consume_ the value; otherwise let it fall through. If the component root is not the control, set `inheritAttrs: false` and retarget the attributes onto the control with `v-bind="$attrs"`.
+
+## An optional `form-key` prop
+
+When the parent form has a key, give the wrapper an optional `form-key` prop and resolve through it, falling back to ambient injection for the single-throwaway-form case:
+
+```ts
+const form = formKey ? injectForm(formKey) : injectForm()
+```
+
+## Extend the surface, do not shrink it
+
+A wrapper composable should expose Attaform's full surface and add derived accessors on top, not return a hand-picked subset that strands state Attaform already computed. Spreading the raw handle plus your derived fields keeps everything reachable.

package/skills/attaform/references/errors.md

@@ -0,0 +1,62 @@
+# Errors
+
+Attaform holds three error layers (schema validation, blank-required, and user-set) and reads them back through one surface. Server and API errors go through the user-set layer via `form.setErrors`; you rarely touch the other two directly.
+
+## Routing server errors
+
+Inside the submit callback, clear the stale user layer, then route the failure through `setErrors`:
+
+```ts
+const onSubmit = form.handleSubmit(async (values) => {
+  form.clearErrors()
+  try {
+    await save(values)
+  } catch (err) {
+    form.setErrors(normalizeErrors(err))
+  }
+})
+```
+
+- `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.
+- `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
+
+If your backend emits Attaform's `ValidationError` shape, it pipes straight into `setErrors` with no translation layer:
+
+```ts
+import type { ValidationError, Json } from 'attaform'
+
+// { message: string; path: (string | number)[]; code?: string; data?: Json | null }
+```
+
+- One entry per message at `path: [field]`; a form-level error is `path: []`; a dotted key splits into segments.
+- A structured non-field payload (a lockout timestamp, a challenge token) is **one form-level error** whose `.data` carries the payload, never exploded into phantom field errors.
+- **Do not build a translation layer** to adapt a payload that already is Attaform's type. If the only friction is a type mismatch (your `data` typed `Record<string, unknown>` rather than Attaform's `Json`), fix the _type_, not with code: `data: z.custom<Json>().nullish()`. Messages come from one source (the server), not a frontend copy map.
+
+A thrown `onSubmit` is also caught and surfaces as a single form-level error, so a bare `throw` is the shortcut when you have no per-field array to distribute. Reach for `setErrors` when the server hands you an array that should target individual fields.
+
+## The own vs subtree axis
+
+Every `FieldState` node (leaves, containers, and the form root) exposes two error axes:
+
+| Accessor                                | Scope                                           |
+| --------------------------------------- | ----------------------------------------------- |
+| `node.ownErrors` / `node.firstOwnError` | errors at **this path exactly**, no descendants |
+| `node.errors` / `form.errors(path)`     | the **subtree**: this path plus descendants     |
+
+On a leaf the two axes coincide. They diverge on containers and on the form root.
+
+## Banners
+
+A form-level banner wants the root's **own** bucket, not the aggregate:
+
+```ts
+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`.
+
+## One normalizer, always non-empty
+
+Route every form's error handling through a single normalizer that sits at the error-reading layer, above the transport, and **always returns a non-empty error set**. The fallback is load-bearing: a network drop, a non-standard 500, or a contract violation whose error array came back empty should still yield one generic form-level error, so the user never sees a submit that silently no-ops. Keep this one chokepoint rather than digging the envelope at each call site.

package/skills/attaform/references/ssr.md

@@ -0,0 +1,26 @@
+# SSR
+
+SSR is automatic under the Nuxt module or the Vite plugin. Field values, `checked`, and `selected` are rendered into the first paint and ARIA is emitted, with no extra wiring. You do not opt in and you do not configure it. What follows matters mostly when you are _debugging_ SSR or writing a test that touches it.
+
+## The value injection is a build-time transform
+
+On the compiled template path, `v-register`'s SSR value / `checked` / `selected` injection is a **build-time Vue-compiler transform** (from `attaform/vite`, wired by the `attaform/nuxt` module), not a runtime `getSSRProps`. On that path `getSSRProps` emits only the `aria-*` attributes; the value rides on the compile-time transform. On the runtime render-function path (a hand-written `h()` component), the value instead comes through `getSSRProps`. Both paths reach the same rendered HTML; they differ only in _which_ mechanism carries the value.
+
+One consequence worth knowing: a `<input :type="...">` with a _dynamic_ type bails the input transform, so give an input a static `type` when you want the compile-time SSR value.
+
+## Confirm SSR through the real build
+
+Always confirm an Attaform SSR claim through the **real build**: curl or inspect the server-rendered HTML of a real (or throwaway) page. Never judge SSR behavior from a bare unit render.
+
+The reason is the transform above. A plain Vitest render (bare `vue()`, no Attaform compiler transform) **cannot** see SSR-injected values for a compiled form component, so a check written there fails even when production is correct. A naive isolated Node render experiment false-negatives for the same reason: the transform is not present, so even the correct shape looks broken.
+
+## Test traps
+
+- **Do not hand-wire `attaform/vite` into `vitest.config.ts`** to force a green. That fakes a third compile pipeline that matches neither production nor a clean unit test, and it hides the real reason a bare test cannot see the value.
+- A faithful SSR test goes through the real build: a Nuxt-level test with `@nuxt/test-utils`. The one lower-level exception is a test that itself invokes `@vue/compiler-sfc`'s `compileTemplate` with Attaform's real node transforms, which reproduces the compiled path honestly.
+
+## One concern that stays in your app
+
+Attaform handles the SSR-adjacent details itself: the value injection above, and error-focus (which requests `focusVisible: true`, so the ring paints even when focus moves programmatically to a radio or checkbox). One SSR pattern is still the app's responsibility:
+
+- **Seeding a page-owned form from async data races SSR.** If an ancestor lifts a form (so it can be injected downward) and seeds it from an async query through an immediate `watch`, the server's watch runs before the query resolves and does not re-fire, so the server renders empty while the client hydrates filled: a hydration mismatch. Seed **both legs**: a client immediate `watch` and a server `onServerPrefetch` that awaits the query, then seeds. A form created lazily behind a resolved gate never hits this.

package/skills/attaform/references/validation.md

@@ -0,0 +1,40 @@
+# Validation
+
+Attaform validates against the form's own Zod schema and drives the display signals from it. The schema is the contract; design it deliberately.
+
+## Client is UX, server is truth
+
+The client schema is a **UX gate only**. A direct request bypasses it entirely, so the server must validate every input independently. Client validation exists to give fast inline feedback, not to protect the backend. Write the schema for the person filling the form; never lean on it as a security boundary.
+
+## Keep closed sets in sync
+
+Where a field is a closed set on both sides (a country, a size band, a status), derive the client `z.enum` from the same option list the control renders, and mirror the server's set. The client should reject _exactly_ what the server would, never stricter on a value the server accepts. A drift between the two shows up as a form that blocks a submit the backend would have taken.
+
+## Reflect server truth, not optimism
+
+On a successful mutation, reset the form from the returned resource or re-read a server-truth source, rather than trusting the values you submitted. A success message should sit on server-confirmed state, not on the optimistic input. This keeps the form honest when the server normalizes, defaults, or rejects part of what you sent.
+
+## A clearable edit field is a required string
+
+A field the user must be able to **clear** should be a required, possibly-empty string, not `.optional()`:
+
+```ts
+const schema = z.object({
+  // Wrong for a clearable edit field: a cleared value drops from the payload,
+  // and a partial-update backend reads the omission as "unchanged".
+  // nickname: z.string().optional(),
+
+  // Right: an empty string still transmits, so the clear reaches the server.
+  nickname: z.string(),
+})
+```
+
+A cleared `.optional()` field drops out of the payload, and a partial-update backend that treats an absent key as "leave unchanged" silently ignores the clear. Use `z.string()` (allowed empty) so the cleared value is sent and the update takes.
+
+## Move real requirements into the schema
+
+If a field's only guard was a disabled submit button, that requirement is not enforced once you stop disabling the button (which you should, see the core rules). Put the requirement in the schema (`.min(1)`, `.refine(...)`) so `handleSubmit` actually fails on it and focuses the field. A field left as a bare `z.string()` or `z.boolean()` accepts empty or `false`, which is often not what an "acknowledge" checkbox or a required text field means.
+
+## The display signals
+
+The per-field `showErrors` / `showSuccess` / `showPending` signals already encode a reward-early, punish-late display policy: an error is revealed once the user has engaged with the field, success is shown when earned, and the async pending state is anti-flash timed. Read those signals; do not rebuild the visibility heuristic from raw `errors` and `touched`.

package/skills/attaform/references/wizards.md

@@ -0,0 +1,104 @@
+# Wizards
+
+`useWizard` composes existing `useForm` instances into a multistep flow with navigation, per-step status, and one aggregate submit. Navigation and submission are separate verbs; keep them separate.
+
+## Step slots
+
+A step slot is one of:
+
+- a `useForm` reference,
+- a **bare string**: an always-valid noop step (key = the string), the native primitive for an informational or affordance screen with no schema,
+- `null` / `undefined`: filtered out of the flow,
+- 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.
+
+```ts
+import { useForm, useWizard } from 'attaform'
+
+const account = useForm({ schema: accountSchema, key: 'account' })
+const profile = useForm({ schema: profileSchema, key: 'profile' })
+
+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.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`:
+
+```ts
+const onStepDone = account.handleSubmit(async (values) => {
+  await saveDraft(values)
+  wizard.next()
+})
+```
+
+`handleSubmit` validating the whole list from any step means there is no "only the last step validates everything" caveat: a user who steps back, edits, and submits from the middle still gets the whole flow validated, and `done` still latches on success. `ctx.isFinal` reports only _where_ the submit fired, never _what_ was validated.
+
+## The submit context
+
+The `onSubmit` callback receives a context, not a bare values object:
+
+```ts
+const onComplete = wizard.handleSubmit(async (ctx) => {
+  // ctx.values is the aggregate keyed by form key (mirrors wizard.allValues)
+  // ctx.get(form) returns one form's typed parsed output
+  // ctx.currentKey is the step that fired the submit
+  // ctx.isFinal is positional: whether currentKey is the last step
+  await fetch('/onboarding', { method: 'POST', body: JSON.stringify(ctx.values) })
+})
+```
+
+`ctx.get(account)` is the type-safe read for one form: it returns that form's parsed output typed from its schema, which survives across a component graph because the form ref carries its schema.
+
+## Reading aggregate state
+
+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.allValues` / `wizard.allErrors`: every form's values / aggregate errors, keyed.
+- `wizard.activeForm`: the currently active step's form facade.
+- `wizard.statuses`: per-form status. Plus `wizard.progress`, `wizard.canAdvance`, `wizard.canGoBack`, `wizard.isFinalStep`, `wizard.visited`.
+
+## A declarative step registry
+
+When steps carry metadata (title, a visibility predicate, persisted keys), drive the whole wizard from one registry rather than scattering the shape. `WizardCtx` is `{ forms, currentKey }` and reactive, so a `when` predicate can branch on live form values and re-evaluate as they change:
+
+```ts
+import { useWizard } from 'attaform'
+import type { AnyForm, WizardCtx } from 'attaform'
+
+interface StepDef {
+  key: string
+  title: string
+  form: AnyForm | null // null becomes a bare-string noop slot
+  when?: (ctx: WizardCtx) => boolean // omitted means always shown
+}
+
+const registry: StepDef[] = [
+  { key: 'intent', title: 'Get started', form: null },
+  { key: 'account', title: 'Your account', form: account },
+  { key: 'profile', title: 'Your profile', form: profile },
+]
+
+const wizard = useWizard({
+  key: 'onboarding',
+  steps: registry.map(
+    (s) => (ctx: WizardCtx) => ((s.when?.(ctx) ?? true) ? (s.form ?? s.key) : undefined)
+  ),
+})
+```
+
+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
+
+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:
+
+- `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.
+
+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`.

package/dist/shared/attaform.55hFR_cl.d.ts

@@ -1,97 +0,0 @@
-import './attaform.DBNjHgNj.js';
-
-/**
- * Typed error classes thrown by the form library. Each one signals a
- * distinct misuse so calling code can branch on `instanceof` instead
- * of pattern-matching error messages.
- *
- * Every class extends `AttaformError`, so consumers can write a single
- * polymorphic catch (`catch (e) { if (e instanceof AttaformError) ... }`)
- * instead of OR-chaining checks for each subclass. `AttaformError` itself
- * extends the standard `Error`, so existing `instanceof Error` usage
- * keeps working.
- */
-
-/**
- * Base for every error class thrown by `attaform`. Sets
- * `this.name` from the constructor's `new.target.name`, so subclasses
- * don't have to redeclare their own name override.
- */
-declare class AttaformError extends Error {
-    constructor(message: string, options?: ErrorOptions);
-}
-/**
- * Thrown when a path string is malformed — typically a dotted path
- * with empty segments (e.g. `'a..b'`, leading or trailing dots).
- * Use array form (`['a', 'b']`) for keys that contain literal dots.
- */
-declare class InvalidPathError extends AttaformError {
-}
-/**
- * Thrown when `useForm` receives an invalid configuration — most often
- * a schema passed directly as the first argument, or no argument at
- * all. The configuration is an options bag; the schema is one of
- * several fields, even when it's the only one in use.
- *
- * ```ts
- * // ✗ Crashes deep inside the validator with an opaque message:
- * const form = useForm(z.object({ ... }))
- * // ✗ Same:
- * const form = useForm()
- * // ✓ Pass the schema as the `schema` field:
- * const form = useForm({ schema: z.object({ ... }) })
- * ```
- *
- * The same shape applies to every entry point: `attaform/zod`,
- * `attaform/zod-v3`, `attaform/zod-v4`, and the schema-agnostic
- * `attaform` root.
- */
-declare class InvalidUseFormConfigError extends AttaformError {
-    constructor();
-}
-/**
- * Thrown when a `handleSubmit`-supplied `onError` callback itself
- * throws or rejects. Wraps the inner failure so both the original
- * cause (via `error.cause`) and the propagation site are visible.
- */
-declare class SubmitErrorHandlerError extends AttaformError {
-}
-/**
- * Thrown when an `attaform` API needs the registry attached to a Vue
- * app but it isn't there yet. Component-level entry points (`useForm`,
- * `injectForm`, `useRegister`) lazy-install the registry on first use,
- * so this error is mostly reached by SSR helpers — `renderAttaformState`
- * and `hydrateAttaformState` — which run outside a setup context and
- * have no current instance to install against.
- *
- * Fix: add `app.use(createAttaform())` (or `app.use(createAttaform({
- * ssr: true }))` on the server) to your SSR entry, before
- * `renderToString` / hydration. Under Nuxt, `attaform/nuxt` already
- * does this; the error usually points at a non-Nuxt SSR setup that
- * hasn't installed explicitly.
- */
-declare class RegistryNotInstalledError extends AttaformError {
-    constructor();
-}
-/**
- * Thrown when `useForm` / `injectForm` is called outside of a
- * Vue `setup()` function — typically from an event handler, watcher,
- * or async callback that runs after mount.
- *
- * Fix: move the call into `setup()`, or trigger it from a child
- * component whose `setup()` runs the composable.
- */
-declare class OutsideSetupError extends AttaformError {
-    constructor();
-}
-/**
- * Thrown when a `useForm({ key })` call uses a key starting with
- * `__atta:`. That prefix is reserved for keys the library generates
- * internally (e.g. for anonymous `useForm()` calls without an
- * explicit key). Pick a different prefix for your form.
- */
-declare class ReservedFormKeyError extends AttaformError {
-    constructor(key: string);
-}
-
-export { AttaformError as A, InvalidPathError as I, OutsideSetupError as O, RegistryNotInstalledError as R, SubmitErrorHandlerError as S, InvalidUseFormConfigError as a, ReservedFormKeyError as b };