@molecule/app-react 1.7.1 → 1.9.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-21T17:02:37.827Z
+Generated: 2026-10-22T08:55:49.342Z
 -->
 
 # @molecule/app-react
@@ -15,12 +15,38 @@ core interfaces (auth, i18n, theme, routing, state, http, storage, logger,
 chat, workspace, editor, preview), so framework-agnostic providers plug
 into React idioms.
 
+**Editable account/profile forms:** `useProfileForm` composes the bonded form
+and auth clients. It hydrates asynchronous user data without erasing dirty
+fields, snapshots controlled values on native form submission, submits only
+changed fields through an app-supplied adapter, and persists/publishes the
+server's saved user. Use its `onSaved` callback to update other query caches
+from that response before navigating. Configure the endpoint, method and JSON
+envelope once in `AuthClientConfig`; no page-local session store is needed.
+
 > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
 > It is written to be read by coding agents as much as by people, and is generated from this
 > package's source — edit `src/index.ts` JSDoc, not this file.
 
 ## Quick Start
 
+```tsx
+const profile = useProfileForm<User, { name: string; email: string }>({
+  defaultValues: { name: '', email: '' },
+  getIdentity: (user) => user.id,
+  toValues: (user) => ({ name: user.name ?? '', email: user.email ?? '' }),
+  toPatch: (changes) => changes,
+  onSaved: async (user) => {
+    // Set/invalidate the app's profile query keys using the saved response.
+    // Navigate only after those writes complete.
+  },
+})
+<form {...profile.formProps}>
+  <input {...profile.register('name')} />
+  <input {...profile.register('email', { email: true })} type="email" />
+  <button type="submit" disabled={!profile.ready || profile.isSubmitting}>Save</button>
+</form>
+```
+
 ```tsx
 import { MoleculeProvider, useAuth, useTheme, useTranslation } from '@molecule/app-react'
 import { provider as stateProvider } from '@molecule/app-state-zustand'
@@ -215,6 +241,9 @@ interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegi
     confirmPasswordReset(data: PasswordResetConfirm): Promise<void>;
     /**
      * Updates the current user's profile.
+     * Returns the saved response. If the session is explicitly replaced or ended
+     * while the request is pending, that response does not replace the current
+     * session's user or persisted cache.
      */
     updateProfile(data: Partial<T>): Promise<T>;
     /**
@@ -281,8 +310,6 @@ interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegi
      * HTTP client bonded to that provider sends first-paint requests unauthenticated.
      *
      * A provider whose restore sends a request THROUGH the gated HTTP client must send that
-     * request with `skipAuthGate: true` (`RequestConfig` in `@molecule/app-http`): the gate
-     * waits on this promise, so holding the restore's own request makes the gate wait on
 // … truncated — the full declaration is in node_modules/@molecule/app-react/dist
 ```
 
@@ -365,7 +392,13 @@ interface FormController<T extends Record<string, unknown> = Record<string, unkn
    */
   validate(): Promise<boolean>
   /**
-   * Resets the form to initial values.
+   * Resets the form and clears errors, touched fields and submission state.
+   *
+   * With no argument it restores the current baseline — the initial
+   * `defaultValues`, or the values a previous `reset(values)` established.
+   * Passing `values` merges them over the current baseline and makes the
+   * result the new baseline, so a form reset to freshly loaded or saved data
+   * reads clean (`isDirty === false`).
    */
   reset(values?: Partial<T>): void
   /**
@@ -397,7 +430,8 @@ Form creation options.
 ```typescript
 interface FormOptions<T extends Record<string, unknown>> {
   /**
-   * Default values.
+   * Default values, captured as the form's clean baseline when the controller
+   * is created. Mutating this object afterwards does not change the baseline.
    */
   defaultValues?: Partial<T>
   /**
@@ -765,12 +799,18 @@ interface UseDeviceResult {
 
 Options for useForm hook.
 
+Every `FormOptions` field is supported. `createForm` is only an override —
+omit it and the hook creates the controller through the bonded forms
+provider (`createForm` from `@molecule/app-forms`), which uses the built-in
+native provider until the app bonds its own.
+
 ```typescript
 interface UseFormOptions<T extends Record<string, unknown>> extends FormOptions<T> {
   /**
-   * Form provider's createForm function.
+   * Explicit form factory for this one form. Defaults to the bonded forms
+   * provider; pass it only to pin a specific provider instance.
    */
-  createForm: (options: FormOptions<T>) => FormController<T>
+  createForm?: (options: FormOptions<T>) => FormController<T>
 }
 ```
 
@@ -822,6 +862,13 @@ Result of useHttp hook.
 
 ```typescript
 interface UseHttpResult<T> extends UseHttpState<T> {
+  /**
+   * Runs the request and resolves with its data, or `null` on failure.
+   *
+   * This function is IDENTITY-STABLE for as long as `method`, `url` and the HTTP
+   * client do not change, so it is safe in a `useEffect` dependency array. Its
+   * request options are read when it is CALLED, from the latest committed render.
+   */
   execute: () => Promise<T | null>
   reset: () => void
 }
@@ -831,6 +878,11 @@ interface UseHttpResult<T> extends UseHttpState<T> {
 
 Options for useHttp hook.
 
+Every request option — headers, params, body `data`, `signal`, `onSuccess`,
+`onError` — is read at the moment `execute` runs, not when the hook rendered,
+so an inline object or callback needs no memoizing. Only `immediate` is read
+on mount.
+
 ```typescript
 interface UseHttpOptions<T> extends RequestConfig {
   /**
@@ -915,6 +967,71 @@ interface UsePlatformResult {
 }
 ```
 
+#### `UseProfileFormOptions`
+
+Configuration for a profile form; transport stays in the auth bond.
+
+```typescript
+interface UseProfileFormOptions<TUser, TValues extends Record<string, unknown>> extends Omit<
+  UseFormOptions<TValues>,
+  'defaultValues'
+> {
+  /** Complete controlled-field defaults, including blank write-only fields. */
+  defaultValues: TValues
+  /** Stable account identity; changing accounts discards the previous account's edits. */
+  getIdentity: (user: TUser) => string
+  /** Maps the current/saved user into controlled values, e.g. nullable text to ''. */
+  toValues: (user: TUser) => TValues
+  /**
+   * Maps ONLY changed fields into an API patch. Omit blank optional credentials
+   * here; preserve undefined/absent fields rather than turning them into null.
+   * The second argument is the complete value snapshot taken at submit time.
+   */
+  toPatch: (changes: Partial<TValues>, values: Readonly<TValues>) => Partial<TUser>
+  /**
+   * Propagates the server's saved user to other caches, then navigates if needed.
+   * Awaited before submission finishes. The auth client already persists and
+   * publishes the saved user; never seed caches from the submitted patch.
+   */
+  onSaved?: (user: TUser) => void | Promise<void>
+}
+```
+
+#### `UseProfileFormResult`
+
+Controlled profile form state and native form bindings.
+
+```typescript
+interface UseProfileFormResult<TUser, TValues extends Record<string, unknown>> extends Omit<
+  UseFormResult<TValues>,
+  'register' | 'handleSubmit' | 'reset'
+> {
+  /** The shared auth user's current profile. */
+  user: TUser | null
+  /** A user has been loaded; disable submission until this is true. */
+  ready: boolean
+  /**
+   * The latest save/propagation failure. Rejected saves retain edits; a failed
+   * onSaved callback can be retried by submit without repeating the mutation.
+   */
+  error: unknown
+  /** Native input/textarea bindings with the field's concrete value type. */
+  register: <K extends keyof TValues>(
+    name: K,
+    options?: Parameters<UseFormResult<TValues>['register']>[1],
+  ) => Omit<FieldRegistration, 'value'> & { value: TValues[K] }
+  /** Bind to the native form, with a type="submit" button inside it. */
+  formProps: { onSubmit: (event: React.FormEvent<HTMLFormElement>) => void }
+  /**
+   * Validates and saves one submit-time snapshot. Concurrent submits share the
+   * same promise. Resolves undefined on validation, save or propagation failure.
+   */
+  submit: () => Promise<TUser | undefined>
+  /** Discards edits and restores the newest loaded/saved profile baseline. */
+  reset: () => void
+}
+```
+
 #### `UsePromiseState`
 
 Extended promise state with actions.
@@ -1938,11 +2055,15 @@ function useEditor(): UseEditorResult
 
 Hook for form state management.
 
+Creates its controller through the bonded forms provider, so a React app
+wires a form library once (`setProvider` from `@molecule/app-forms`) and
+every form picks it up. Passing `createForm` overrides that for one form.
+
 ```typescript
-function useForm(options: UseFormOptions<T>): UseFormResult<T>
+function useForm(options?: UseFormOptions<T>): UseFormResult<T>
 ```
 
-- `options` — Form options including createForm from a forms provider
+- `options` — Form options. `defaultValues`, `mode` and the form-level `validate` are forwarded to the provider; omit the options entirely for a form whose fields are registered with their own defaults.
 
 **Returns:** Form state and methods
 
@@ -1986,6 +2107,15 @@ function useHttpClient(): HttpClient
 
 Hook for making HTTP requests with state management.
 
+`execute` keeps one identity while `method`, `url` and the HTTP client stay the
+same — across the hook's own loading/data updates, parent rerenders, and inline
+options or callbacks — so `useEffect(() => { void execute() }, [execute])`
+runs once per request target instead of looping. The current headers, body,
+`signal` and callbacks are read when `execute` is called, so a later manual
+call always sends what the latest committed render passed. Changing `method`, `url` or
+the client does replace `execute` (it selects a different request) and
+re-runs such an effect.
+
 ```typescript
 function useHttp(
   method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
@@ -1996,7 +2126,7 @@ function useHttp(
 
 - `method` — HTTP method
 - `url` — Request URL
-- `options` — Request options
+- `options` — Request options, read at call time
 
 **Returns:** Request state and execute function
 
@@ -2201,6 +2331,27 @@ function usePreview(): UsePreviewResult
 
 **Returns:** Preview state and controls: state (url, isLoading, device, error, isConnected), setUrl, refresh, setDevice, and openExternal.
 
+#### `useProfileForm(options)`
+
+Owns load → edit → submit → publish for the signed-in user's profile.
+
+Same-account background updates refresh untouched fields but preserve dirty
+controls. Submission snapshots the registered values before asynchronous
+validation, sends only changed fields through `toPatch`, and uses the auth
+client's configured updateProfile transport. The saved server response becomes
+the clean baseline; edits made while saving remain dirty. No request is made
+for a patch with no fields. A failed request retains the edits and shared user.
+
+```typescript
+function useProfileForm(
+  options: UseProfileFormOptions<TUser, TValues>,
+): UseProfileFormResult<TUser, TValues>
+```
+
+- `options` — Controlled defaults, identity and wire adapters, optional cache/navigation callback.
+
+**Returns:** Form state, typed control bindings, native submit binding and save error.
+
 #### `usePromise(asyncFn)`
 
 Hook that wraps an async function with state tracking.
@@ -2990,6 +3141,23 @@ Peer dependencies:
 - `@molecule/app-version`
 - `react`
 
+- `useProfileForm` needs `AuthProvider` (or `MoleculeProvider auth={client}`)
+  and uses the bonded forms provider, just like `useForm`. `defaultValues`
+  and `toValues` must cover every registered control; map nullable text to
+  `''` there. Add optional write-only controls such as `password: ''` to both,
+  then omit a blank password in `toPatch`: `({ password, ...changes }) =>
+({ ...changes, ...(password?.trim() ? { password } : {}) })`. `changes`
+  contains only edited fields, so do not fill omitted fields with null or
+  copy every property of the auth user into the request. `reset()` discards
+  edits to the newest baseline. A changed `getIdentity(user)` clears the old
+  account's edits. Field comparisons are shallow, matching form providers.
+  A submission whose account or auth client changes, or whose form unmounts,
+  during asynchronous validation is discarded before any mutation or saved
+  callback. Same-account background hydration does not discard the submit.
+  The hook captures save failures in `error`; render that error with the
+  app's normal API-error presentation. Use native `<form>` submit semantics,
+  and pass the typed `register()` props through custom controls to their
+  actual input/textarea elements.
 - **Every hook throws when its provider is not mounted.** `MoleculeProvider` wires ONLY the
   services you pass as props — it is a convenience wrapper, not a default registry. The map:
   `useAuth`→`auth`, `useTranslation`/`useT`→`i18n`, `useTheme`→`theme`, `useRouter`→`router`,

package/dist/hooks/useForm.d.ts

@@ -6,12 +6,18 @@
 import type { FieldRegistration, FieldState, FormController, FormOptions, FormState, RegisterOptions } from '@molecule/app-forms';
 /**
  * Options for useForm hook.
+ *
+ * Every `FormOptions` field is supported. `createForm` is only an override —
+ * omit it and the hook creates the controller through the bonded forms
+ * provider (`createForm` from `@molecule/app-forms`), which uses the built-in
+ * native provider until the app bonds its own.
  */
 export interface UseFormOptions<T extends Record<string, unknown>> extends FormOptions<T> {
     /**
-     * Form provider's createForm function.
+     * Explicit form factory for this one form. Defaults to the bonded forms
+     * provider; pass it only to pin a specific provider instance.
      */
-    createForm: (options: FormOptions<T>) => FormController<T>;
+    createForm?: (options: FormOptions<T>) => FormController<T>;
 }
 /**
  * Result of useForm hook.
@@ -36,16 +42,21 @@ export interface UseFormResult<T extends Record<string, unknown>> {
 /**
  * Hook for form state management.
  *
- * @param options - Form options including createForm from a forms provider
+ * Creates its controller through the bonded forms provider, so a React app
+ * wires a form library once (`setProvider` from `@molecule/app-forms`) and
+ * every form picks it up. Passing `createForm` overrides that for one form.
+ *
+ * @param options - Form options. `defaultValues`, `mode` and the form-level
+ * `validate` are forwarded to the provider; omit the options entirely for a
+ * form whose fields are registered with their own defaults.
  * @returns Form state and methods
  *
  * @example
  * ```tsx
- * import { createForm } from '@molecule/app-forms'
+ * import { useForm } from '@molecule/app-react'
  *
  * function LoginForm() {
  *   const { register, handleSubmit, formState, isSubmitting } = useForm({
- *     createForm,
  *     defaultValues: { email: '', password: '' },
  *   })
  *
@@ -69,7 +80,7 @@ export interface UseFormResult<T extends Record<string, unknown>> {
  * }
  * ```
  */
-export declare function useForm<T extends Record<string, unknown>>(options: UseFormOptions<T>): UseFormResult<T>;
+export declare function useForm<T extends Record<string, unknown>>(options?: UseFormOptions<T>): UseFormResult<T>;
 /**
  * Hook to watch a specific field value.
  *

package/dist/hooks/useForm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useForm.d.ts","sourceRoot":"","sources":["../../src/hooks/useForm.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EACV,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,WAAW,EACX,SAAS,EACT,eAAe,EAChB,MAAM,qBAAqB,CAAA;AAkC5B;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IACvF;;OAEG;IACH,UAAU,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,cAAc,CAAC,CAAC,CAAC,CAAA;CAC3D;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAE9D,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACvB,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,YAAY,EAAE,OAAO,CAAA;IAGrB,QAAQ,EAAE,CACR,IAAI,EAAE,MAAM,CAAC,EACb,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KACxD,iBAAiB,CAAA;IACtB,QAAQ,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC9C,QAAQ,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IAC3D,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,MAAM,GAAG,SAAS,CAAA;IAC/C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAA;IAC5D,WAAW,EAAE,MAAM,IAAI,CAAA;IAGvB,YAAY,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAA;IAClG,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IACpC,QAAQ,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvD,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,aAAa,CAAC,CAAC,CAAC,CAwElB;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,EAC3E,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,CAAC,GACN,CAAC,CAAC,CAAC,CAAC,CAGN;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,MAAM,CAAC,GACZ,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAGxB"}
+{"version":3,"file":"useForm.d.ts","sourceRoot":"","sources":["../../src/hooks/useForm.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EACV,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,WAAW,EACX,SAAS,EACT,eAAe,EAChB,MAAM,qBAAqB,CAAA;AAmC5B;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IACvF;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,cAAc,CAAC,CAAC,CAAC,CAAA;CAC5D;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAE9D,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACvB,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,YAAY,EAAE,OAAO,CAAA;IAGrB,QAAQ,EAAE,CACR,IAAI,EAAE,MAAM,CAAC,EACb,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KACxD,iBAAiB,CAAA;IACtB,QAAQ,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC9C,QAAQ,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IAC3D,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,MAAM,GAAG,SAAS,CAAA;IAC/C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAA;IAC5D,WAAW,EAAE,MAAM,IAAI,CAAA;IAGvB,YAAY,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAA;IAClG,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IACpC,QAAQ,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvD,OAAO,GAAE,cAAc,CAAC,CAAC,CAAM,GAC9B,aAAa,CAAC,CAAC,CAAC,CAwElB;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,EAC3E,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,CAAC,GACN,CAAC,CAAC,CAAC,CAAC,CAGN;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,MAAM,CAAC,GACZ,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAGxB"}

package/dist/hooks/useForm.js

@@ -4,6 +4,7 @@
  * @module
  */
 import { useCallback, useMemo, useRef, useSyncExternalStore } from 'react';
+import { createForm as createBondedForm } from '@molecule/app-forms';
 /**
  * Adapt controller notifications to React's stable snapshot contract. Providers
  * may return fresh objects from their getters; reads between notifications must
@@ -35,16 +36,21 @@ function useFormSnapshot(form, read) {
 /**
  * Hook for form state management.
  *
- * @param options - Form options including createForm from a forms provider
+ * Creates its controller through the bonded forms provider, so a React app
+ * wires a form library once (`setProvider` from `@molecule/app-forms`) and
+ * every form picks it up. Passing `createForm` overrides that for one form.
+ *
+ * @param options - Form options. `defaultValues`, `mode` and the form-level
+ * `validate` are forwarded to the provider; omit the options entirely for a
+ * form whose fields are registered with their own defaults.
  * @returns Form state and methods
  *
  * @example
  * ```tsx
- * import { createForm } from '@molecule/app-forms'
+ * import { useForm } from '@molecule/app-react'
  *
  * function LoginForm() {
  *   const { register, handleSubmit, formState, isSubmitting } = useForm({
- *     createForm,
  *     defaultValues: { email: '', password: '' },
  *   })
  *
@@ -68,8 +74,8 @@ function useFormSnapshot(form, read) {
  * }
  * ```
  */
-export function useForm(options) {
-    const { createForm, ...formOptions } = options;
+export function useForm(options = {}) {
+    const { createForm = createBondedForm, ...formOptions } = options;
     // Create form controller once
     const formRef = useRef(null);
     if (!formRef.current) {

package/dist/hooks/useForm.js.map

@@ -1 +1 @@
-{"version":3,"file":"useForm.js","sourceRoot":"","sources":["../../src/hooks/useForm.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useForm.js","sourceRoot":"","sources":["../../src/hooks/useForm.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useHttp.d.ts

@@ -23,11 +23,23 @@ export interface UseHttpState<T> {
  * Result of useHttp hook.
  */
 export interface UseHttpResult<T> extends UseHttpState<T> {
+    /**
+     * Runs the request and resolves with its data, or `null` on failure.
+     *
+     * This function is IDENTITY-STABLE for as long as `method`, `url` and the HTTP
+     * client do not change, so it is safe in a `useEffect` dependency array. Its
+     * request options are read when it is CALLED, from the latest committed render.
+     */
     execute: () => Promise<T | null>;
     reset: () => void;
 }
 /**
  * Options for useHttp hook.
+ *
+ * Every request option — headers, params, body `data`, `signal`, `onSuccess`,
+ * `onError` — is read at the moment `execute` runs, not when the hook rendered,
+ * so an inline object or callback needs no memoizing. Only `immediate` is read
+ * on mount.
  */
 export interface UseHttpOptions<T> extends RequestConfig {
     /**
@@ -46,9 +58,18 @@ export interface UseHttpOptions<T> extends RequestConfig {
 /**
  * Hook for making HTTP requests with state management.
  *
+ * `execute` keeps one identity while `method`, `url` and the HTTP client stay the
+ * same — across the hook's own loading/data updates, parent rerenders, and inline
+ * options or callbacks — so `useEffect(() => { void execute() }, [execute])`
+ * runs once per request target instead of looping. The current headers, body,
+ * `signal` and callbacks are read when `execute` is called, so a later manual
+ * call always sends what the latest committed render passed. Changing `method`, `url` or
+ * the client does replace `execute` (it selects a different request) and
+ * re-runs such an effect.
+ *
  * @param method - HTTP method
  * @param url - Request URL
- * @param options - Request options
+ * @param options - Request options, read at call time
  * @returns Request state and execute function
  *
  * @example
@@ -56,8 +77,8 @@ export interface UseHttpOptions<T> extends RequestConfig {
  * const { data, loading, error, execute } = useHttp<User[]>('GET', '/api/users')
  *
  * useEffect(() => {
- *   execute()
- * }, [])
+ *   void execute()
+ * }, [execute])
  *
  * if (loading) return <Spinner />
  * if (error) return <Error message={error.message} />

package/dist/hooks/useHttp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useHttp.d.ts","sourceRoot":"","sources":["../../src/hooks/useHttp.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAgB,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAKjF;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAU1C;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IACd,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAC;IACvD,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IAChC,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,aAAa;IACtD;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;IAC7B;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,EACnD,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAC1B,aAAa,CAAC,CAAC,CAAC,CAqFlB;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAEpF;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAErF;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAEpF;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAEtF;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAEvF"}
+{"version":3,"file":"useHttp.d.ts","sourceRoot":"","sources":["../../src/hooks/useHttp.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAgB,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAKjF;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAU1C;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IACd,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAC;IACvD;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IAChC,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,aAAa;IACtD;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;IAC7B;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,EACnD,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAC1B,aAAa,CAAC,CAAC,CAAC,CAqGlB;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAEpF;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAErF;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAEpF;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAEtF;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAEvF"}

package/dist/hooks/useHttp.js

@@ -3,7 +3,7 @@
  *
  * @module
  */
-import { useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { useCallback, useContext, useEffect, useInsertionEffect, useRef, useState } from 'react';
 import { t } from '@molecule/app-i18n';
 import { HttpContext } from '../contexts.js';
 /**
@@ -24,9 +24,18 @@ export function useHttpClient() {
 /**
  * Hook for making HTTP requests with state management.
  *
+ * `execute` keeps one identity while `method`, `url` and the HTTP client stay the
+ * same — across the hook's own loading/data updates, parent rerenders, and inline
+ * options or callbacks — so `useEffect(() => { void execute() }, [execute])`
+ * runs once per request target instead of looping. The current headers, body,
+ * `signal` and callbacks are read when `execute` is called, so a later manual
+ * call always sends what the latest committed render passed. Changing `method`, `url` or
+ * the client does replace `execute` (it selects a different request) and
+ * re-runs such an effect.
+ *
  * @param method - HTTP method
  * @param url - Request URL
- * @param options - Request options
+ * @param options - Request options, read at call time
  * @returns Request state and execute function
  *
  * @example
@@ -34,8 +43,8 @@ export function useHttpClient() {
  * const { data, loading, error, execute } = useHttp<User[]>('GET', '/api/users')
  *
  * useEffect(() => {
- *   execute()
- * }, [])
+ *   void execute()
+ * }, [execute])
  *
  * if (loading) return <Spinner />
  * if (error) return <Error message={error.message} />
@@ -44,12 +53,12 @@ export function useHttpClient() {
  */
 export function useHttp(method, url, options) {
     const client = useHttpClient();
-    const { immediate = false, onSuccess, onError, ...requestConfig } = options ?? {};
-    const [state, setState] = useState({
+    const immediate = options?.immediate ?? false;
+    const [state, setState] = useState(() => ({
         data: null,
         loading: immediate,
         error: null,
-    });
+    }));
     // Track mounted state to avoid state updates after unmount
     const mountedRef = useRef(true);
     useEffect(() => {
@@ -58,9 +67,20 @@ export function useHttp(method, url, options) {
             mountedRef.current = false;
         };
     }, []);
+    // Publish options during commit, before consumers' layout effects. A render
+    // that suspends or is discarded must not change a mounted action's request.
+    // This only updates our own ref: no DOM access or state update is involved.
+    const optionsRef = useRef(options);
+    useInsertionEffect(() => {
+        optionsRef.current = options;
+    }, [options]);
     const execute = useCallback(async () => {
         if (!mountedRef.current)
             return null;
+        // Deliberately NOT a dependency of this callback: options describe the
+        // request being sent, while method/url/client decide WHICH request execute
+        // performs. Reading them here keeps this action stable for effect deps.
+        const { immediate: _immediate, onSuccess, onError, ...requestConfig } = optionsRef.current ?? {};
         setState((prev) => ({ ...prev, loading: true, error: null }));
         try {
             let response;
@@ -97,11 +117,14 @@ export function useHttp(method, url, options) {
             }
             return null;
         }
-    }, [client, method, url, requestConfig, onSuccess, onError]);
+    }, [client, method, url]);
     const reset = useCallback(() => {
         setState({ data: null, loading: false, error: null });
     }, []);
-    // Execute immediately if requested
+    // Execute immediately if requested — mount only, as it has always been.
+    // `immediate` and `execute` are deliberately not dependencies: re-running this
+    // would turn a state update into a second request, which is the historical
+    // contract of this option (and every useGet(url, { immediate: true })'s).
     useEffect(() => {
         if (immediate) {
             execute();

package/dist/hooks/useHttp.js.map

@@ -1 +1 @@
-{"version":3,"file":"useHttp.js","sourceRoot":"","sources":["../../src/hooks/useHttp.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useHttp.js","sourceRoot":"","sources":["../../src/hooks/useHttp.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useProfileForm.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Profile editing over the app's bonded form and auth clients.
+ *
+ * @module
+ */
+import type { FieldRegistration } from '@molecule/app-forms';
+import { type UseFormOptions, type UseFormResult } from './useForm.js';
+/** Configuration for a profile form; transport stays in the auth bond. */
+export interface UseProfileFormOptions<TUser, TValues extends Record<string, unknown>> extends Omit<UseFormOptions<TValues>, 'defaultValues'> {
+    /** Complete controlled-field defaults, including blank write-only fields. */
+    defaultValues: TValues;
+    /** Stable account identity; changing accounts discards the previous account's edits. */
+    getIdentity: (user: TUser) => string;
+    /** Maps the current/saved user into controlled values, e.g. nullable text to ''. */
+    toValues: (user: TUser) => TValues;
+    /**
+     * Maps ONLY changed fields into an API patch. Omit blank optional credentials
+     * here; preserve undefined/absent fields rather than turning them into null.
+     * The second argument is the complete value snapshot taken at submit time.
+     */
+    toPatch: (changes: Partial<TValues>, values: Readonly<TValues>) => Partial<TUser>;
+    /**
+     * Propagates the server's saved user to other caches, then navigates if needed.
+     * Awaited before submission finishes. The auth client already persists and
+     * publishes the saved user; never seed caches from the submitted patch.
+     */
+    onSaved?: (user: TUser) => void | Promise<void>;
+}
+/** Controlled profile form state and native form bindings. */
+export interface UseProfileFormResult<TUser, TValues extends Record<string, unknown>> extends Omit<UseFormResult<TValues>, 'register' | 'handleSubmit' | 'reset'> {
+    /** The shared auth user's current profile. */
+    user: TUser | null;
+    /** A user has been loaded; disable submission until this is true. */
+    ready: boolean;
+    /**
+     * The latest save/propagation failure. Rejected saves retain edits; a failed
+     * onSaved callback can be retried by submit without repeating the mutation.
+     */
+    error: unknown;
+    /** Native input/textarea bindings with the field's concrete value type. */
+    register: <K extends keyof TValues>(name: K, options?: Parameters<UseFormResult<TValues>['register']>[1]) => Omit<FieldRegistration, 'value'> & {
+        value: TValues[K];
+    };
+    /** Bind to the native form, with a type="submit" button inside it. */
+    formProps: {
+        onSubmit: (event: React.FormEvent<HTMLFormElement>) => void;
+    };
+    /**
+     * Validates and saves one submit-time snapshot. Concurrent submits share the
+     * same promise. Resolves undefined on validation, save or propagation failure.
+     */
+    submit: () => Promise<TUser | undefined>;
+    /** Discards edits and restores the newest loaded/saved profile baseline. */
+    reset: () => void;
+}
+/**
+ * Owns load → edit → submit → publish for the signed-in user's profile.
+ *
+ * Same-account background updates refresh untouched fields but preserve dirty
+ * controls. Submission snapshots the registered values before asynchronous
+ * validation, sends only changed fields through `toPatch`, and uses the auth
+ * client's configured updateProfile transport. The saved server response becomes
+ * the clean baseline; edits made while saving remain dirty. No request is made
+ * for a patch with no fields. A failed request retains the edits and shared user.
+ *
+ * @param options - Controlled defaults, identity and wire adapters, optional cache/navigation callback.
+ * @returns Form state, typed control bindings, native submit binding and save error.
+ */
+export declare function useProfileForm<TUser, TValues extends Record<string, unknown>>(options: UseProfileFormOptions<TUser, TValues>): UseProfileFormResult<TUser, TValues>;
+//# sourceMappingURL=useProfileForm.d.ts.map

package/dist/hooks/useProfileForm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useProfileForm.d.ts","sourceRoot":"","sources":["../../src/hooks/useProfileForm.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAG5D,OAAO,EAAW,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAE/E,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB,CAAC,KAAK,EAAE,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,IAAI,CACjG,cAAc,CAAC,OAAO,CAAC,EACvB,eAAe,CAChB;IACC,6EAA6E;IAC7E,aAAa,EAAE,OAAO,CAAA;IACtB,wFAAwF;IACxF,WAAW,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,CAAA;IACpC,oFAAoF;IACpF,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAA;IAClC;;;;OAIG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,KAAK,CAAC,CAAA;IACjF;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAChD;AAED,8DAA8D;AAC9D,MAAM,WAAW,oBAAoB,CAAC,KAAK,EAAE,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,IAAI,CAChG,aAAa,CAAC,OAAO,CAAC,EACtB,UAAU,GAAG,cAAc,GAAG,OAAO,CACtC;IACC,8CAA8C;IAC9C,IAAI,EAAE,KAAK,GAAG,IAAI,CAAA;IAClB,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAA;IACd;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAA;IACd,2EAA2E;IAC3E,QAAQ,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,EAChC,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,UAAU,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,KACxD,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,GAAG;QAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;KAAE,CAAA;IAC7D,sEAAsE;IACtE,SAAS,EAAE;QAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,eAAe,CAAC,KAAK,IAAI,CAAA;KAAE,CAAA;IAC1E;;;OAGG;IACH,MAAM,EAAE,MAAM,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAA;IACxC,4EAA4E;IAC5E,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3E,OAAO,EAAE,qBAAqB,CAAC,KAAK,EAAE,OAAO,CAAC,GAC7C,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,CAsLtC"}

package/dist/hooks/useProfileForm.js

@@ -0,0 +1,188 @@
+/**
+ * Profile editing over the app's bonded form and auth clients.
+ *
+ * @module
+ */
+import { useCallback, useInsertionEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useAuth, useAuthClient } from './useAuth.js';
+import { useForm } from './useForm.js';
+/**
+ * Owns load → edit → submit → publish for the signed-in user's profile.
+ *
+ * Same-account background updates refresh untouched fields but preserve dirty
+ * controls. Submission snapshots the registered values before asynchronous
+ * validation, sends only changed fields through `toPatch`, and uses the auth
+ * client's configured updateProfile transport. The saved server response becomes
+ * the clean baseline; edits made while saving remain dirty. No request is made
+ * for a patch with no fields. A failed request retains the edits and shared user.
+ *
+ * @param options - Controlled defaults, identity and wire adapters, optional cache/navigation callback.
+ * @returns Form state, typed control bindings, native submit binding and save error.
+ */
+export function useProfileForm(options) {
+    const { defaultValues, getIdentity: _identity, toValues: _values, toPatch: _patch, onSaved: _saved, ...formOptions } = options;
+    const form = useForm({ ...formOptions, defaultValues });
+    const client = useAuthClient();
+    const { user } = useAuth();
+    const [error, setError] = useState();
+    const [isSaving, setIsSaving] = useState(false);
+    const optionsRef = useRef(options);
+    const committedClient = useRef(client);
+    const baseline = useRef({ ...defaultValues });
+    const owner = useRef(null);
+    const activeSave = useRef(null);
+    const pendingPropagation = useRef(undefined);
+    const mounted = useRef(false);
+    // Actions use committed configuration, never an abandoned concurrent render.
+    useInsertionEffect(() => {
+        optionsRef.current = options;
+        committedClient.current = client;
+    }, [options, client]);
+    useLayoutEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    const readValues = useCallback(() => {
+        const values = { ...baseline.current };
+        for (const key of Object.keys(values))
+            values[key] = form.getValue(key);
+        return values;
+    }, [form.getValue]);
+    const rebase = useCallback((next, preserveAgainst) => {
+        const current = readValues();
+        baseline.current = { ...next };
+        form.reset(next);
+        if (preserveAgainst) {
+            for (const key of Object.keys(current)) {
+                if (!Object.is(current[key], preserveAgainst[key]))
+                    form.setValue(key, current[key]);
+            }
+        }
+    }, [readValues, form.reset, form.setValue]);
+    useLayoutEffect(() => {
+        const config = optionsRef.current;
+        if (!user) {
+            if (owner.current) {
+                owner.current = null;
+                pendingPropagation.current = undefined;
+                rebase({ ...config.defaultValues });
+                setError(undefined);
+            }
+            return;
+        }
+        const identity = config.getIdentity(user);
+        const previous = owner.current;
+        const sameAccount = !previous || (previous.client === client && previous.identity === identity);
+        const previousBaseline = baseline.current;
+        // Keep this token across same-account hydration, but replace it when the
+        // account/client changes. A pending validation belongs to that exact owner.
+        if (!previous || !sameAccount)
+            owner.current = { client, identity };
+        rebase(config.toValues(user), sameAccount ? previousBaseline : undefined);
+        if (!sameAccount) {
+            pendingPropagation.current = undefined;
+            setError(undefined);
+        }
+    }, [user, client, rebase]);
+    const submit = useCallback(() => {
+        if (activeSave.current)
+            return activeSave.current;
+        const currentUser = client.getUser();
+        if (!mounted.current || !currentUser)
+            return Promise.resolve(undefined);
+        const config = optionsRef.current;
+        const identity = config.getIdentity(currentUser);
+        const submissionOwner = owner.current;
+        const ownsProfile = () => {
+            const current = client.getUser();
+            return (mounted.current &&
+                committedClient.current === client &&
+                owner.current === submissionOwner &&
+                current !== null &&
+                config.getIdentity(current) === identity);
+        };
+        const snapshot = readValues();
+        const before = { ...baseline.current };
+        const changes = {};
+        for (const key of Object.keys(snapshot)) {
+            if (!Object.is(snapshot[key], before[key]))
+                changes[key] = snapshot[key];
+        }
+        setError(undefined);
+        setIsSaving(true);
+        let saved;
+        const run = async () => {
+            try {
+                await form.handleSubmit(async () => {
+                    // Validation can await arbitrary app work. Check BEFORE toPatch and
+                    // again immediately before the mutation: its credentials are read by
+                    // updateProfile now, not when the reader originally clicked Save.
+                    if (!ownsProfile())
+                        return;
+                    const patch = config.toPatch(changes, snapshot);
+                    if (Object.keys(patch).length > 0) {
+                        if (!ownsProfile())
+                            return;
+                        saved = await client.updateProfile(patch);
+                        if (!ownsProfile()) {
+                            saved = undefined;
+                            return;
+                        }
+                        if (mounted.current)
+                            rebase(config.toValues(saved), snapshot);
+                        pendingPropagation.current = saved;
+                    }
+                    if (pendingPropagation.current !== undefined) {
+                        if (!ownsProfile()) {
+                            saved = undefined;
+                            return;
+                        }
+                        const propagated = pendingPropagation.current;
+                        await config.onSaved?.(propagated);
+                        pendingPropagation.current = undefined;
+                        saved = propagated;
+                    }
+                })();
+                return saved;
+            }
+            catch (failure) {
+                if (mounted.current)
+                    setError(failure);
+                return undefined;
+            }
+            finally {
+                activeSave.current = null;
+                if (mounted.current)
+                    setIsSaving(false);
+            }
+        };
+        activeSave.current = run();
+        return activeSave.current;
+    }, [client, readValues, form.handleSubmit, rebase]);
+    const register = useCallback((name, registerOptions) => {
+        return form.register(name, registerOptions);
+    }, [form.register]);
+    const reset = useCallback(() => {
+        form.reset(baseline.current);
+        setError(undefined);
+    }, [form.reset]);
+    const onSubmit = useCallback((event) => {
+        event.preventDefault();
+        void submit();
+    }, [submit]);
+    return {
+        ...form,
+        formState: { ...form.formState, isSubmitting: isSaving || form.isSubmitting },
+        isSubmitting: isSaving || form.isSubmitting,
+        user,
+        ready: user !== null,
+        error,
+        register,
+        reset,
+        submit,
+        formProps: { onSubmit },
+    };
+}
+//# sourceMappingURL=useProfileForm.js.map

package/dist/hooks/useProfileForm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useProfileForm.js","sourceRoot":"","sources":["../../src/hooks/useProfileForm.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAI1F,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACrD,OAAO,EAAE,OAAO,EAA2C,MAAM,cAAc,CAAA;AAyD/E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAC5B,OAA8C;IAE9C,MAAM,EACJ,aAAa,EACb,WAAW,EAAE,SAAS,EACtB,QAAQ,EAAE,OAAO,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,GAAG,WAAW,EACf,GAAG,OAAO,CAAA;IACX,MAAM,IAAI,GAAG,OAAO,CAAU,EAAE,GAAG,WAAW,EAAE,aAAa,EAAE,CAAC,CAAA;IAChE,MAAM,MAAM,GAAG,aAAa,EAAS,CAAA;IACrC,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,EAAS,CAAA;IACjC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,EAAW,CAAA;IAC7C,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC/C,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;IAClC,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,CAAA;IACtC,MAAM,QAAQ,GAAG,MAAM,CAAC,EAAE,GAAG,aAAa,EAAE,CAAC,CAAA;IAC7C,MAAM,KAAK,GAAG,MAAM,CAAqD,IAAI,CAAC,CAAA;IAC9E,MAAM,UAAU,GAAG,MAAM,CAAoC,IAAI,CAAC,CAAA;IAClE,MAAM,kBAAkB,GAAG,MAAM,CAAoB,SAAS,CAAC,CAAA;IAC/D,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IAE7B,6EAA6E;IAC7E,kBAAkB,CAAC,GAAG,EAAE;QACtB,UAAU,CAAC,OAAO,GAAG,OAAO,CAAA;QAC5B,eAAe,CAAC,OAAO,GAAG,MAAM,CAAA;IAClC,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAA;IACrB,eAAe,CAAC,GAAG,EAAE;QACnB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAA;QACtB,OAAO,GAAG,EAAE;YACV,OAAO,CAAC,OAAO,GAAG,KAAK,CAAA;QACzB,CAAC,CAAA;IACH,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,MAAM,UAAU,GAAG,WAAW,CAAC,GAAY,EAAE;QAC3C,MAAM,MAAM,GAAG,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAA;QACtC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAsB;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;QAC5F,OAAO,MAAM,CAAA;IACf,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAA;IAEnB,MAAM,MAAM,GAAG,WAAW,CACxB,CAAC,IAAa,EAAE,eAAyB,EAAQ,EAAE;QACjD,MAAM,OAAO,GAAG,UAAU,EAAE,CAAA;QAC5B,QAAQ,CAAC,OAAO,GAAG,EAAE,GAAG,IAAI,EAAE,CAAA;QAC9B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QAChB,IAAI,eAAe,EAAE,CAAC;YACpB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAsB,EAAE,CAAC;gBAC5D,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,eAAe,CAAC,GAAG,CAAC,CAAC;oBAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAA;YACtF,CAAC;QACH,CAAC;IACH,CAAC,EACD,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,CACxC,CAAA;IAED,eAAe,CAAC,GAAG,EAAE;QACnB,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAA;QACjC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;gBAClB,KAAK,CAAC,OAAO,GAAG,IAAI,CAAA;gBACpB,kBAAkB,CAAC,OAAO,GAAG,SAAS,CAAA;gBACtC,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC,aAAa,EAAE,CAAC,CAAA;gBACnC,QAAQ,CAAC,SAAS,CAAC,CAAA;YACrB,CAAC;YACD,OAAM;QACR,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAA;QACzC,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAA;QAC9B,MAAM,WAAW,GAAG,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,MAAM,IAAI,QAAQ,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAA;QAC/F,MAAM,gBAAgB,GAAG,QAAQ,CAAC,OAAO,CAAA;QACzC,yEAAyE;QACzE,4EAA4E;QAC5E,IAAI,CAAC,QAAQ,IAAI,CAAC,WAAW;YAAE,KAAK,CAAC,OAAO,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA;QACnE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QACzE,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,kBAAkB,CAAC,OAAO,GAAG,SAAS,CAAA;YACtC,QAAQ,CAAC,SAAS,CAAC,CAAA;QACrB,CAAC;IACH,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAE1B,MAAM,MAAM,GAAG,WAAW,CAAC,GAA+B,EAAE;QAC1D,IAAI,UAAU,CAAC,OAAO;YAAE,OAAO,UAAU,CAAC,OAAO,CAAA;QACjD,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,EAAE,CAAA;QACpC,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,WAAW;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;QACvE,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAA;QACjC,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,WAAW,CAAC,CAAA;QAChD,MAAM,eAAe,GAAG,KAAK,CAAC,OAAO,CAAA;QACrC,MAAM,WAAW,GAAG,GAAY,EAAE;YAChC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAA;YAChC,OAAO,CACL,OAAO,CAAC,OAAO;gBACf,eAAe,CAAC,OAAO,KAAK,MAAM;gBAClC,KAAK,CAAC,OAAO,KAAK,eAAe;gBACjC,OAAO,KAAK,IAAI;gBAChB,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,KAAK,QAAQ,CACzC,CAAA;QACH,CAAC,CAAA;QACD,MAAM,QAAQ,GAAG,UAAU,EAAE,CAAA;QAC7B,MAAM,MAAM,GAAG,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAA;QACtC,MAAM,OAAO,GAAqB,EAAE,CAAA;QACpC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAsB,EAAE,CAAC;YAC7D,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;QAC1E,CAAC;QACD,QAAQ,CAAC,SAAS,CAAC,CAAA;QACnB,WAAW,CAAC,IAAI,CAAC,CAAA;QACjB,IAAI,KAAwB,CAAA;QAC5B,MAAM,GAAG,GAAG,KAAK,IAAgC,EAAE;YACjD,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE;oBACjC,oEAAoE;oBACpE,qEAAqE;oBACrE,kEAAkE;oBAClE,IAAI,CAAC,WAAW,EAAE;wBAAE,OAAM;oBAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;oBAC/C,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBAClC,IAAI,CAAC,WAAW,EAAE;4BAAE,OAAM;wBAC1B,KAAK,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAA;wBACzC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;4BACnB,KAAK,GAAG,SAAS,CAAA;4BACjB,OAAM;wBACR,CAAC;wBACD,IAAI,OAAO,CAAC,OAAO;4BAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAA;wBAC7D,kBAAkB,CAAC,OAAO,GAAG,KAAK,CAAA;oBACpC,CAAC;oBACD,IAAI,kBAAkB,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;wBAC7C,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;4BACnB,KAAK,GAAG,SAAS,CAAA;4BACjB,OAAM;wBACR,CAAC;wBACD,MAAM,UAAU,GAAG,kBAAkB,CAAC,OAAO,CAAA;wBAC7C,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC,UAAU,CAAC,CAAA;wBAClC,kBAAkB,CAAC,OAAO,GAAG,SAAS,CAAA;wBACtC,KAAK,GAAG,UAAU,CAAA;oBACpB,CAAC;gBACH,CAAC,CAAC,EAAE,CAAA;gBACJ,OAAO,KAAK,CAAA;YACd,CAAC;YAAC,OAAO,OAAO,EAAE,CAAC;gBACjB,IAAI,OAAO,CAAC,OAAO;oBAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;gBACtC,OAAO,SAAS,CAAA;YAClB,CAAC;oBAAS,CAAC;gBACT,UAAU,CAAC,OAAO,GAAG,IAAI,CAAA;gBACzB,IAAI,OAAO,CAAC,OAAO;oBAAE,WAAW,CAAC,KAAK,CAAC,CAAA;YACzC,CAAC;QACH,CAAC,CAAA;QACD,UAAU,CAAC,OAAO,GAAG,GAAG,EAAE,CAAA;QAC1B,OAAO,UAAU,CAAC,OAAO,CAAA;IAC3B,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAA;IAEnD,MAAM,QAAQ,GAAG,WAAW,CAC1B,CACE,IAAO,EACP,eAAmE,EACT,EAAE;QAC5D,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAEzC,CAAA;IACH,CAAC,EACD,CAAC,IAAI,CAAC,QAAQ,CAAC,CAChB,CAAA;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;QAC5B,QAAQ,CAAC,SAAS,CAAC,CAAA;IACrB,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;IAChB,MAAM,QAAQ,GAAG,WAAW,CAC1B,CAAC,KAAuC,EAAQ,EAAE;QAChD,KAAK,CAAC,cAAc,EAAE,CAAA;QACtB,KAAK,MAAM,EAAE,CAAA;IACf,CAAC,EACD,CAAC,MAAM,CAAC,CACT,CAAA;IAED,OAAO;QACL,GAAG,IAAI;QACP,SAAS,EAAE,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,IAAI,IAAI,CAAC,YAAY,EAAE;QAC7E,YAAY,EAAE,QAAQ,IAAI,IAAI,CAAC,YAAY;QAC3C,IAAI;QACJ,KAAK,EAAE,IAAI,KAAK,IAAI;QACpB,KAAK;QACL,QAAQ;QACR,KAAK;QACL,MAAM;QACN,SAAS,EAAE,EAAE,QAAQ,EAAE;KACxB,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -6,6 +6,33 @@
  * chat, workspace, editor, preview), so framework-agnostic providers plug
  * into React idioms.
  *
+ * **Editable account/profile forms:** `useProfileForm` composes the bonded form
+ * and auth clients. It hydrates asynchronous user data without erasing dirty
+ * fields, snapshots controlled values on native form submission, submits only
+ * changed fields through an app-supplied adapter, and persists/publishes the
+ * server's saved user. Use its `onSaved` callback to update other query caches
+ * from that response before navigating. Configure the endpoint, method and JSON
+ * envelope once in `AuthClientConfig`; no page-local session store is needed.
+ *
+ * @example
+ * ```tsx
+ * const profile = useProfileForm<User, { name: string; email: string }>({
+ *   defaultValues: { name: '', email: '' },
+ *   getIdentity: (user) => user.id,
+ *   toValues: (user) => ({ name: user.name ?? '', email: user.email ?? '' }),
+ *   toPatch: (changes) => changes,
+ *   onSaved: async (user) => {
+ *     // Set/invalidate the app's profile query keys using the saved response.
+ *     // Navigate only after those writes complete.
+ *   },
+ * })
+ * <form {...profile.formProps}>
+ *   <input {...profile.register('name')} />
+ *   <input {...profile.register('email', { email: true })} type="email" />
+ *   <button type="submit" disabled={!profile.ready || profile.isSubmitting}>Save</button>
+ * </form>
+ * ```
+ *
  * @example
  * ```tsx
  * import { MoleculeProvider, useAuth, useTheme, useTranslation } from '@molecule/app-react'
@@ -48,6 +75,23 @@
  * ```
  *
  * @remarks
+ * - `useProfileForm` needs `AuthProvider` (or `MoleculeProvider auth={client}`)
+ *   and uses the bonded forms provider, just like `useForm`. `defaultValues`
+ *   and `toValues` must cover every registered control; map nullable text to
+ *   `''` there. Add optional write-only controls such as `password: ''` to both,
+ *   then omit a blank password in `toPatch`: `({ password, ...changes }) =>
+ *   ({ ...changes, ...(password?.trim() ? { password } : {}) })`. `changes`
+ *   contains only edited fields, so do not fill omitted fields with null or
+ *   copy every property of the auth user into the request. `reset()` discards
+ *   edits to the newest baseline. A changed `getIdentity(user)` clears the old
+ *   account's edits. Field comparisons are shallow, matching form providers.
+ *   A submission whose account or auth client changes, or whose form unmounts,
+ *   during asynchronous validation is discarded before any mutation or saved
+ *   callback. Same-account background hydration does not discard the submit.
+ *   The hook captures save failures in `error`; render that error with the
+ *   app's normal API-error presentation. Use native `<form>` submit semantics,
+ *   and pass the typed `register()` props through custom controls to their
+ *   actual input/textarea elements.
  * - **Every hook throws when its provider is not mounted.** `MoleculeProvider` wires ONLY the
  *   services you pass as props — it is a convenience wrapper, not a default registry. The map:
  *   `useAuth`→`auth`, `useTranslation`/`useT`→`i18n`, `useTheme`→`theme`, `useRouter`→`router`,
@@ -104,6 +148,7 @@
 export * from './agent-identity.js';
 export * from './contexts.js';
 export * from './hooks/index.js';
+export * from './hooks/useProfileForm.js';
 export * from './providers.js';
 export * from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkJG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,2BAA2B,CAAA;AACzC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -6,6 +6,33 @@
  * chat, workspace, editor, preview), so framework-agnostic providers plug
  * into React idioms.
  *
+ * **Editable account/profile forms:** `useProfileForm` composes the bonded form
+ * and auth clients. It hydrates asynchronous user data without erasing dirty
+ * fields, snapshots controlled values on native form submission, submits only
+ * changed fields through an app-supplied adapter, and persists/publishes the
+ * server's saved user. Use its `onSaved` callback to update other query caches
+ * from that response before navigating. Configure the endpoint, method and JSON
+ * envelope once in `AuthClientConfig`; no page-local session store is needed.
+ *
+ * @example
+ * ```tsx
+ * const profile = useProfileForm<User, { name: string; email: string }>({
+ *   defaultValues: { name: '', email: '' },
+ *   getIdentity: (user) => user.id,
+ *   toValues: (user) => ({ name: user.name ?? '', email: user.email ?? '' }),
+ *   toPatch: (changes) => changes,
+ *   onSaved: async (user) => {
+ *     // Set/invalidate the app's profile query keys using the saved response.
+ *     // Navigate only after those writes complete.
+ *   },
+ * })
+ * <form {...profile.formProps}>
+ *   <input {...profile.register('name')} />
+ *   <input {...profile.register('email', { email: true })} type="email" />
+ *   <button type="submit" disabled={!profile.ready || profile.isSubmitting}>Save</button>
+ * </form>
+ * ```
+ *
  * @example
  * ```tsx
  * import { MoleculeProvider, useAuth, useTheme, useTranslation } from '@molecule/app-react'
@@ -48,6 +75,23 @@
  * ```
  *
  * @remarks
+ * - `useProfileForm` needs `AuthProvider` (or `MoleculeProvider auth={client}`)
+ *   and uses the bonded forms provider, just like `useForm`. `defaultValues`
+ *   and `toValues` must cover every registered control; map nullable text to
+ *   `''` there. Add optional write-only controls such as `password: ''` to both,
+ *   then omit a blank password in `toPatch`: `({ password, ...changes }) =>
+ *   ({ ...changes, ...(password?.trim() ? { password } : {}) })`. `changes`
+ *   contains only edited fields, so do not fill omitted fields with null or
+ *   copy every property of the auth user into the request. `reset()` discards
+ *   edits to the newest baseline. A changed `getIdentity(user)` clears the old
+ *   account's edits. Field comparisons are shallow, matching form providers.
+ *   A submission whose account or auth client changes, or whose form unmounts,
+ *   during asynchronous validation is discarded before any mutation or saved
+ *   callback. Same-account background hydration does not discard the submit.
+ *   The hook captures save failures in `error`; render that error with the
+ *   app's normal API-error presentation. Use native `<form>` submit semantics,
+ *   and pass the typed `register()` props through custom controls to their
+ *   actual input/textarea elements.
  * - **Every hook throws when its provider is not mounted.** `MoleculeProvider` wires ONLY the
  *   services you pass as props — it is a convenience wrapper, not a default registry. The map:
  *   `useAuth`→`auth`, `useTranslation`/`useT`→`i18n`, `useTheme`→`theme`, `useRouter`→`router`,
@@ -104,6 +148,7 @@
 export * from './agent-identity.js';
 export * from './contexts.js';
 export * from './hooks/index.js';
+export * from './hooks/useProfileForm.js';
 export * from './providers.js';
 export * from './types.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkJG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,2BAA2B,CAAA;AACzC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-react",
-  "version": "1.7.1",
+  "version": "1.9.0",
   "description": "React framework bindings for molecule.dev",
   "type": "module",
   "main": "dist/index.js",
@@ -58,7 +58,7 @@
     }
   },
   "devDependencies": {
-    "@molecule/app-ai-models": "1.4.0",
+    "@molecule/app-ai-models": "1.4.1",
     "@molecule/app-bonds-default-react": "1.1.5",
     "@molecule/app-i18n": "1.0.3",
     "@testing-library/dom": "10.4.1",
@@ -68,7 +68,7 @@
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "typescript": "6.0.3",
-    "vitest": "4.1.11"
+    "vitest": "4.1.12"
   },
   "repository": {
     "type": "git",