Problem
When `excludeFields: ['password']` is set in a multi-step wizard, the user fills the password in step 1 and progresses to step 5. `step` is persisted, password is not. On refresh, the app restores at step 5 but the password field is empty. The user clicks Submit and the server receives an empty password — silent UX failure.
Proposed API
Add a derived field to `FormDraftResult`:
```ts
draft.fieldsNeedingReentry: ReadonlyArray<keyof T & string>;
```
Populated when storage restore happens AND the excluded fields were non-default before the persist that's being restored. Auto-clears per-field when the user re-enters a non-default value.
Implementation sketch
- `stored record` shape adds optional `__excludedHad?: string[]` — key names only, never values
- On each persist: scan `excludeFields`, list keys where `!Object.is(value, defaultValue)` → record
- On restore: hydrate `__excludedHad` into internal state
- Per-render: `fieldsNeedingReentry = excludedHadOnRestore.filter(k => Object.is(values[k], defaultValues[k]))`
- `discard()` clears
Exposed via
- `FormDraftResult`
- `useFormDraftStatus(key)`
- `getFormDraft(key)` handle (`getFieldsNeedingReentry()`)
- RHF / Formik / TanStack adapters
Backward compat
Pre-0.3.0 records have no `__excludedHad` field → `fieldsNeedingReentry === []` on restore. Safe.
Acceptance
- Unit tests: persist writes/omits the flag correctly; restore populates; user filling clears; discard clears; multi-field subset behavior
- e2e: wizard scenario where step persists past the password step
- README: new short section explaining the pattern
- Adapters all expose the field
Problem
When `excludeFields: ['password']` is set in a multi-step wizard, the user fills the password in step 1 and progresses to step 5. `step` is persisted, password is not. On refresh, the app restores at step 5 but the password field is empty. The user clicks Submit and the server receives an empty password — silent UX failure.
Proposed API
Add a derived field to `FormDraftResult`:
```ts
draft.fieldsNeedingReentry: ReadonlyArray<keyof T & string>;
```
Populated when storage restore happens AND the excluded fields were non-default before the persist that's being restored. Auto-clears per-field when the user re-enters a non-default value.
Implementation sketch
Exposed via
Backward compat
Pre-0.3.0 records have no `__excludedHad` field → `fieldsNeedingReentry === []` on restore. Safe.
Acceptance