@molecule/app-react-native 1.0.3 → 2.0.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-19T22:40:47.803Z
+Generated: 2026-10-25T20:03:36.978Z
 -->
 
 # @molecule/app-react-native
@@ -105,7 +105,7 @@ Provides login/logout/register flows, token management, profile
 updates, and auth state subscription.
 
 ```typescript
-interface AuthClient<T = UserProfile, TRegister extends Record<string, unknown> = Record<never, never>> {
+interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegister> = Record<never, never>> {
     /**
      * Returns the current authentication state snapshot.
      *
@@ -125,6 +125,15 @@ interface AuthClient<T = UserProfile, TRegister extends Record<string, unknown>
      * Gets the current user.
      */
     getUser(): T | null;
+    /**
+     * Optional ownership marker for the current session. Compare values only within
+     * this client: replacing or ending a session changes it, including re-adopting
+     * the same token and user. Profile updates and same-session refreshes keep it.
+     * Consumers can use it to discard stale async work without treating editable
+     * user fields as an immutable account identifier. Providers without this
+     * capability require the consumer's own stable identity check.
+     */
+    getSessionRevision?(): number;
     /**
      * Updates the cached user object (state + persistent storage) without
      * hitting the network. Intended for local refreshes after a per-app
@@ -199,6 +208,12 @@ interface AuthClient<T = UserProfile, TRegister extends Record<string, unknown>
     confirmPasswordReset(data: PasswordResetConfirm): Promise<void>;
     /**
      * Updates the current user's profile.
+     * Returns the saved profile: the answer applied onto the signed-in user field
+     * by field, with or without an `id` — a field it carries replaces the value
+     * (`null` clears it), one it omits or leaves `undefined` is kept, so a field
+     * cleared by omission must arrive as `null`. A non-object answer is returned
+     * as it came. An answer for a replaced or ended session leaves the current one
+     * untouched.
      */
     updateProfile(data: Partial<T>): Promise<T>;
     /**
@@ -254,19 +269,6 @@ interface AuthClient<T = UserProfile, TRegister extends Record<string, unknown>
      * Resolves when the session restore started by `initialize()` has settled — the point
      * after which the client knows whether this visitor is signed in.
      *
-     * Resolves IMMEDIATELY when no restore is in flight: before `initialize()` is ever
-     * called, and after it has finished. A restore that failed resolves too (it settled the
-     * question), so an HTTP client can await this before every request without risking one
-     * held forever. That is what makes the fetch-before-restore race impossible: a page that
-     * fetches viewer-dependent data on mount waits here instead of going out anonymously
-     * (see `setAuthGate` in `@molecule/app-http`).
-     *
-     * Optional: a provider that restores no session has nothing to wait for. Without it, an
-     * 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-native/dist
 ```
 
@@ -349,7 +351,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
   /**
@@ -381,7 +389,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>
   /**
@@ -467,12 +476,50 @@ interface HttpClient {
   addErrorInterceptor(interceptor: ErrorInterceptor): () => void
   /**
    * Sets the authorization token.
+   *
+   * A static token: every request carries it until the next `setAuthToken` call. A client
+   * that has a {@link HttpClient.setAuthTokenResolver | resolver} (registered through
+   * `@molecule/app-http`'s `setAuthTokenSource`) ignores this value when it assembles a
+   * request — the resolver IS the session, and reading it per request is what keeps a
+   * session adopted without an auth event from sending the previous account's bearer. Once
+   * the resolver is removed, the static token is sent again.
    */
   setAuthToken(token: string | null): void
   /**
-   * Returns the current authorization token, or `null` if not set.
+   * Returns the token the client applies to its next request: the resolver's answer when one
+   * is registered, else the static token from `setAuthToken`.
    */
   getAuthToken(): string | null
+  /**
+   * Registers the LIVE token resolver every request of this client reads, or clears it with
+   * `null`.
+   *
+   * `@molecule/app-http`'s `setAuthTokenSource()` calls this on every client it bonds, and the
+   * client MUST consult the resolver again each time it assembles a request (and report it from
+   * `getAuthToken()`). A session can change with no auth event and no observable state change —
+   * `authClient.setSession()` with the same profile data, or the OAuth callback's
+   * `setAccessToken()` — so a token pushed only at bond time or on `login`/`logout` events
+   * leaves every later request carrying the PREVIOUS session's bearer while the UI shows the
+   * new one.
+   *
+   * The resolved token takes the static token's place, with the same precedence: an
+   * `Authorization` header passed per request or in the client's default headers wins over it
+   * exactly where it won over a static token in this transport.
+   *
+   * A resolver that returns `null` (or `undefined`) means "this session has no body token": the
+   * request carries no `Authorization` header of the client's own. A cookie-session API issues
+   * no bearer, and the server prefers the header over the fresh cookie, so a kept bearer
+   * authenticates as the prior — possibly deleted — session.
+   *
+   * Optional, so an implementation written against the previous interface still conforms.
+   * `setAuthTokenSource()` follows such a client through a request interceptor instead, pushing
+   * the source with `setAuthToken` before each request: that request carries the change only
+   * when the transport applies its token after running its interceptors, so a transport that
+   * applies it earlier sends a session adopted mid-page from the following request on.
+   *
+   * @param resolver - Returns the current access token (or null/undefined), or `null` to clear.
+   */
+  setAuthTokenResolver?(resolver: AuthTokenResolver | null): void
   /**
    * Registers a handler for authentication errors (401).
    *
@@ -786,12 +833,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>
 }
 ```
 
@@ -805,7 +858,12 @@ interface UseFormResult<T extends Record<string, unknown>> {
   isValid: boolean
   isDirty: boolean
   isSubmitting: boolean
-  register: (name: keyof T, options?: RegisterOptions) => FieldRegistration
+  register: (
+    name: keyof T,
+    options?: Omit<RegisterOptions, 'name'> & {
+      name?: string
+    },
+  ) => FieldRegistration
   getValue: <K extends keyof T>(name: K) => T[K]
   setValue: <K extends keyof T>(name: K, value: T[K]) => void
   getError: (name: keyof T) => string | undefined
@@ -835,6 +893,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
 }
@@ -844,6 +909,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 {
   /**
@@ -928,6 +998,80 @@ 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
+  /**
+   * Optional additional account identity check; changing it discards prior edits.
+   * By default ownership follows the auth client's session revision, so editable
+   * fields can change during a save. Providers without getSessionRevision must
+   * supply this callback with an identity that remains stable across profile 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.
@@ -980,11 +1124,14 @@ interface UsePushOptions {
 Return type for useSignup hook.
 
 ```typescript
-interface UseSignupReturn<T = unknown> {
+interface UseSignupReturn<
+  T = unknown,
+  TRegister extends RegisterExtraShape<TRegister> = Record<never, never>,
+> {
   status: UsePromiseState<AuthResult<T>>['status']
   value: UsePromiseState<AuthResult<T>>['value']
   error: UsePromiseState<AuthResult<T>>['error']
-  signup: (data: RegisterData) => Promise<AuthResult<T>>
+  signup: (data: RegisterData<TRegister>) => Promise<AuthResult<T>>
   reset: () => void
 }
 ```
@@ -1271,7 +1418,10 @@ interface UseAuthOptions {
 Hook result for useAuth.
 
 ```typescript
-interface UseAuthResult<T = unknown> {
+interface UseAuthResult<
+  T = unknown,
+  TRegister extends RegisterExtraShape<TRegister> = Record<never, never>,
+> {
   /**
    * The session state as one value — render from this instead of combining
    * `initialized`/`authenticated`/`loading`. A stored token AND user make it
@@ -1282,7 +1432,7 @@ interface UseAuthResult<T = unknown> {
   state: AuthState<T>
   login: AuthClient<T>['login']
   logout: AuthClient<T>['logout']
-  register: AuthClient<T>['register']
+  register: AuthClient<T, TRegister>['register']
   refresh: AuthClient<T>['refresh']
   setUser: AuthClient<T>['setUser']
   /**
@@ -1293,7 +1443,7 @@ interface UseAuthResult<T = unknown> {
    *
    * `setUser` alone does NOT sign the client in, and `setAccessToken` changes
    * storage only — using those two for a caller-issued session leaves every
-   * `authenticated` read signed out (xr-molecule-flash-m178).
+   * `authenticated` read signed out.
    */
   setSession: AuthClient<T>['setSession']
   isAuthenticated: boolean
@@ -1394,6 +1544,8 @@ Options for {@link UseChatResult.sendMessage}.
 
 ```typescript
 interface SendMessageOptions {
+  /** Reuse a queued message's UUID when delivering it after reconnecting. */
+  messageId?: string
   /**
    * Skip the optimistic local user-message bubble. The text is still sent to
    * the server. Used for ask_user responses: the answer is folded into the
@@ -1692,6 +1844,34 @@ How far the return-page verification has got.
 type VerifyPaymentReturnStatus = 'idle' | 'verifying' | 'verified' | 'failed'
 ```
 
+#### `UseTShorthandOptions`
+
+Options for the shorthand form of {@link UseTFunction}: the fallback text is
+passed positionally, so only `count` remains here.
+
+```typescript
+type UseTShorthandOptions = Omit<TranslateOptions, 'defaultValue'>
+```
+
+#### `UseTFunction`
+
+Translation function returned by `useT()`.
+
+Two compatible call forms:
+
+- `t(key, values?, options?)` — the {@link I18nProvider.t} signature.
+- `t(key, fallback, options?)` — a string second argument is the inline
+  English `defaultValue`, with optional `count` for pluralization.
+
+Its identity is stable while the i18n provider instance is unchanged, so it
+can be used directly as an effect dependency.
+
+```typescript
+type UseTFunction = I18nProvider['t'] & {
+  (key: string, fallback: string, options?: UseTShorthandOptions): string
+}
+```
+
 ### Functions
 
 #### `useAppState()`
@@ -1774,8 +1954,12 @@ function useAIModels(projectId?: string): UseAIModelsResult
 
 Hook to access the auth client from context.
 
+Pass the same generics the client was created with —
+`useAuthClient<MyUser, { username: string }>()` — so `register()` accepts
+the app's own fields.
+
 ```typescript
-function useAuthClient(): AuthClient<T, Record<never, never>>
+function useAuthClient(): AuthClient<T, TRegister>
 ```
 
 **Returns:** The auth client from context
@@ -1798,8 +1982,14 @@ To create an account, use `const { register } = useAuth<MyUser>()` and
 `await register({ email, password, name })`. Registration returns the auth
 client's `AuthResult<MyUser>`; there is no separate `useRegister` hook.
 
+An app whose API takes its OWN registration fields passes the client's
+second generic here too — `useAuth<MyUser, { username: string }>()` — so
+`register({ email, password, username })` is typed exactly like the client
+call (and `requestBody` receives the same payload). Without it, `register`
+accepts only the base fields.
+
 ```typescript
-function useAuth(options?: UseAuthOptions): UseAuthResult<T>
+function useAuth(options?: UseAuthOptions): UseAuthResult<T, TRegister>
 ```
 
 - `options` — Hook options
@@ -1968,11 +2158,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
 
@@ -2016,6 +2210,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',
@@ -2026,7 +2229,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
 
@@ -2231,6 +2434,29 @@ 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. Session ownership comes from the auth client, independently of mutable
+profile fields; an explicit getIdentity adds the caller's identity check.
+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.
+
 #### `usePush(options)`
 
 Hook for push notification state and actions.
@@ -2323,7 +2549,7 @@ function useIsActive(path: string, exact?: boolean): boolean
 Hook for user registration with async state tracking.
 
 ```typescript
-function useSignup(): UseSignupReturn<T>
+function useSignup(): UseSignupReturn<T, TRegister>
 ```
 
 **Returns:** Signup state and action
@@ -2505,15 +2731,32 @@ function useTranslation(): UseTranslationResult
 
 Hook to get just the translation function.
 
+The returned function keeps ONE identity for as long as the provider
+instance is unchanged, so it is safe as an effect dependency: an effect
+written as `useEffect(..., [t])` does not re-run on ordinary re-renders or on
+a locale change. The hook still re-renders the calling component on every
+locale notification (including `addTranslations` for the active locale), so
+text it reads while rendering is current. A value memoized on `[t]` alone
+keeps the old text after a locale switch: `useMemo(() => t(...), [t])`, or a
+`React.memo` child that receives `t` as a prop. Call `useT()` inside that
+child, or add `useLocale()` to the dependencies.
+
+Call it in either of two compatible forms:
+
+- `t(key, values?, options?)` — the provider signature from
+  `@molecule/app-i18n`, e.g. `t('cart.total', { total })`.
+- `t(key, fallback, options?)` — a shorthand for the common inline-English
+  call: a string second argument is the `defaultValue`, so
+  `t('cart.empty', 'Your cart is empty')` equals
+  `t('cart.empty', undefined, { defaultValue: 'Your cart is empty' })`.
+  Interpolation and pluralization still work:
+  `t('cart.items', '{{count}} items', { count: 3 })`.
+
 ```typescript
-function useT(): (
-  key: string,
-  values?: InterpolationValues,
-  options?: { defaultValue?: string; count?: number },
-) => string
+function useT(): UseTFunction
 ```
 
-**Returns:** The translation function
+**Returns:** The translation function (stable identity while the provider is unchanged).
 
 #### `useLocale()`
 
@@ -2988,7 +3231,7 @@ Peer dependencies:
 
 - `@molecule/app-keyboard` ^1.0.1
 - `@molecule/app-lifecycle` ^1.0.1
-- `@molecule/app-react` ^1.0.1
+- `@molecule/app-react` ^2.0.0
 - `react` ^18.0.0 || ^19.0.0
 - `react-native` >=0.72.0
 - `react-native-safe-area-context` >=4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-react-native",
-  "version": "1.0.3",
+  "version": "2.0.0",
   "description": "React Native framework bindings for molecule.dev",
   "homepage": "https://www.molecule.dev/packages/app-react-native",
   "type": "module",
@@ -33,16 +33,16 @@
     "directory": "packages/app/frameworks/react-native"
   },
   "devDependencies": {
-    "@molecule/app-react": "1.6.7",
-    "@types/node": "26.1.2",
-    "react": "19.2.8",
+    "@molecule/app-react": "2.0.0",
+    "@types/node": "26.6.5",
+    "react": "19.3.1",
     "typescript": "6.0.3",
-    "vitest": "4.1.11"
+    "vitest": "4.1.12"
   },
   "peerDependencies": {
     "@molecule/app-keyboard": "^1.0.1",
     "@molecule/app-lifecycle": "^1.0.1",
-    "@molecule/app-react": "^1.0.1",
+    "@molecule/app-react": "^2.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-native": ">=0.72.0",
     "react-native-safe-area-context": ">=4.0.0"