@molecule/app-react-native 3.0.1 → 3.0.3

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-28T08:44:21.978Z
+Generated: 2026-11-04T14:20:07.525Z
 -->
 
 # @molecule/app-react-native
@@ -72,7 +72,10 @@ Reactive authentication state snapshot (initialized, authenticated, user, loadin
 interface AuthState<T = UserProfile> {
   /**
    * The session's state as one value — render from this instead of combining
-   * `initialized`/`authenticated`/`loading`. See {@link AuthStatus}.
+   * `initialized`/`authenticated`/`loading`. `'loading'` is undecided, so wait
+   * and redirect only on `'unauthenticated'`; `'unavailable'` keeps the candidate
+   * for retry and can have a null profile. A restore failure other than 401/403
+   * never signs out. See {@link AuthStatus}.
    */
   status: AuthStatus
   /**
@@ -80,11 +83,14 @@ interface AuthState<T = UserProfile> {
    */
   initialized: boolean
   /**
-   * Whether the user is authenticated.
+   * Whether the client has an authenticated session. This is not a server
+   * confirmation flag: during `'unavailable'` it can be false for a retained
+   * token/cookie-only candidate with no cached profile. Use `status` for redirects.
    */
   authenticated: boolean
   /**
-   * Current user (if authenticated).
+   * Current user, or null when none is cached. In particular, an `'unavailable'`
+   * token/cookie-only restore has a retained candidate but no profile yet.
    */
   user: T | null
   /**
@@ -105,173 +111,65 @@ Provides login/logout/register flows, token management, profile
 updates, and auth state subscription.
 
 ```typescript
-interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegister> = Record<never, never>> {
-    /**
-     * Returns the current authentication state snapshot.
-     *
-     * READING the state starts the client's one session restore when nobody has called
-     * {@link initialize} yet — lazily and exactly once, sharing the promise an explicit
-     * `initialize()` returns. A hook (`useAuth()`), a subscriber, `isAuthenticated()` and
-     * `getUser()` are reads too, so a client whose entry file dropped the template's
-     * `authClient.initialize()` line still restores instead of reporting `'loading'`
-     * forever.
-     */
-    getState(): AuthState<T>;
-    /**
-     * Returns whether the user is currently authenticated.
-     */
-    isAuthenticated(): boolean;
-    /**
-     * 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
-     * mutation (e.g., the user just PATCHed their own profile and the
-     * server returned the canonical row). Does NOT change tokens.
-     *
-     * This does not sign the client in: `authenticated` and `status` are
-     * unchanged, so an anonymous client stays anonymous. Use
-     * {@link login} / {@link register} for a credential exchange, or
-     * {@link setSession} when the token was issued outside the client.
-     */
-    setUser(user: T | null): void;
-    /**
-     * Gets the current access token.
-     */
-    getAccessToken(): string | null;
-    /**
-     * Stores the access token in the configured token storage adapter (in a
-     * browser, Web Storage; `'memory'` where no browser store exists). Use this
-     * to seed the token after an out-of-band exchange (e.g. the OAuth
-     * code→token redirect) instead of writing to `localStorage` directly,
-     * which would violate the storage contract and make a stored bearer token
-     * JS-readable (XSS-exfiltratable). Pass `null` to clear it.
-     *
-     * This changes token storage only; it does not sign the client in
-     * (`authenticated` and `status` are unchanged). Use {@link login} /
-     * {@link register} for a credential exchange, or call {@link setSession}
-     * with the token and the user to establish an already-issued session.
-     */
-    setAccessToken(token: string | null): void;
-    /**
-     * Adopts a session an out-of-band exchange already established: stores the
-     * access token (and the refresh token when given), caches the user, and
-     * sets the COMPLETE state — `initialized`, `authenticated`, `status:
-     * 'authenticated'`, no error — in one update, with one subscriber
-     * notification. Every hook reading the shared client sees the user as
-     * signed in immediately.
-     *
-     * This is the way to seed an OAuth/custom sign-in. Calling
-     * {@link setAccessToken} and {@link setUser} instead does NOT sign the
-     * client in.
-     */
-    setSession(session: AuthSessionSeed<T>): void;
-    /**
-     * Gets the refresh token.
-     */
-    getRefreshToken(): string | null;
-    /**
-     * Logs in with credentials.
-     */
-    login(credentials: LoginCredentials): Promise<AuthResult<T>>;
-    /**
-     * Logs out the current user.
-     */
-    logout(): Promise<void>;
-    /**
-     * Registers a new user. Accepts the base fields plus the app's own fields
-     * (`TRegister`) at the top level — see {@link RegisterData}.
-     */
-    register(data: RegisterData<TRegister>): Promise<AuthResult<T>>;
-    /**
-     * Refreshes the access token.
-     */
-    refresh(): Promise<AuthResult<T>>;
-    /**
-     * Requests a password reset.
-     */
-    requestPasswordReset(data: PasswordResetRequest): Promise<void>;
-    /**
-     * Confirms a password reset.
-     */
-    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>;
-    /**
-     * Changes the current user's password.
-     */
-    changePassword(oldPassword: string, newPassword: string): Promise<void>;
-    /**
-     * Initializes auth state (e.g., from stored tokens).
-     *
-     * LAZY and IDEMPOTENT: the first read of the state ({@link getState},
-     * {@link subscribe}, `useAuth()`) starts this same restore when nobody has called
-     * `initialize()`, and every later call shares the one promise instead of sending a
-     * second request. An app that keeps the template's explicit call behaves exactly as
-     * before; an app that loses that line still restores its session.
-     *
-     * With a stored token AND a stored user it marks the session `'authenticated'`
-     * SYNCHRONOUSLY — before its first `await` — so the first render is the
-     * signed-in UI and no page waits on a verification round trip. Any check
-     * (a refresh, the cookie-restore probe) settles behind that render, and only an
-     * explicit 401/403 ends the session; a network/5xx/404 failure keeps it and
-     * reports `'unavailable'`. With no stored user the client stays `'loading'`
-     * until the cookie restore decides.
-     *
-     * Do not put this call (or a `/me` request of your own) in front of the first
-     * render, and do not render a loading screen over a session it just restored:
-     * `whenRestored()` already resolves as soon as the restore has settled, and the
-     * HTTP gate built on it holds requests for exactly that window.
-     */
-    initialize(): Promise<void>;
-    /**
-     * Re-checks a restored session against the server, in the background — the
-     * boot-time validation an app with a stored token needs when a revoked or
-     * expired token must sign the user out. Call it AFTER the first render
-     * (`initialize()` restores synchronously from storage; this costs one request).
-     *
-     * - The server confirms the user: the session is refreshed and {@link AuthState.status}
-     *   stays `'authenticated'`.
-     * - The server answers 401 or 403: the token is dead — the stored session is
-     *   cleared and the status becomes `'unauthenticated'`.
-     * - The server cannot confirm the session — a network failure, a 5xx, or a 404
-     *   from a misconfigured {@link AuthClientConfig.currentUserEndpoint}: the
-     *   session (token AND user) is KEPT and the status becomes `'unavailable'`, so
-     *   the app can retry instead of signing the user out over a bad connection or a
-     *   route that does not exist. The 404 error names `currentUserEndpoint`.
-     *
-     * Do not hand-write this beside the client: a parallel token/user store for a
-     * "validating"/"unavailable" flag is the race this method removes.
-     *
-     * Optional: a provider with no restorable session has nothing to validate.
-     */
-    validateSession?(): Promise<void>;
-    /**
-     * Resolves when the session restore started by `initialize()` has settled — the point
-     * after which the client knows whether this visitor is signed in.
-     *
-// … truncated — the full declaration is in node_modules/@molecule/app-react-native/dist
+interface AuthClient<
+  T = UserProfile,
+  TRegister extends RegisterExtraShape<TRegister> = Record<never, never>,
+> {
+  /** Returns the current authentication state snapshot. */
+  getState(): AuthState<T>
+  /** Returns whether the user is currently authenticated. */
+  isAuthenticated(): boolean
+  /** Gets the current user. */
+  getUser(): T | null
+  /** Optional ownership marker for the current session. */
+  getSessionRevision?(): number
+  /** Updates the cached user object (state + persistent storage) without hitting the network. */
+  setUser(user: T | null): void
+  /** Gets the current access token. */
+  getAccessToken(): string | null
+  /** Stores the access token in the configured token storage adapter (in a browser, Web Storage; `'memory'` where no browser store exists). */
+  setAccessToken(token: string | null): void
+  /** Adopts a session an out-of-band exchange already established: stores the access token (and the refresh token when given), caches the user, and sets the COMPLET… */
+  setSession(session: AuthSessionSeed<T>): void
+  /** Gets the refresh token. */
+  getRefreshToken(): string | null
+  /** Logs in with credentials. */
+  login(credentials: LoginCredentials): Promise<AuthResult<T>>
+  /** Logs out the current user. */
+  logout(): Promise<void>
+  /** Registers a new user. */
+  register(data: RegisterData<TRegister>): Promise<AuthResult<T>>
+  /** Refreshes the access token. */
+  refresh(): Promise<AuthResult<T>>
+  /** Requests a password reset. */
+  requestPasswordReset(data: PasswordResetRequest): Promise<void>
+  /** Confirms a password reset. */
+  confirmPasswordReset(data: PasswordResetConfirm): Promise<void>
+  /** Updates the current user's profile. */
+  updateProfile(data: Partial<T>): Promise<T>
+  /** Changes the current user's password. */
+  changePassword(oldPassword: string, newPassword: string): Promise<void>
+  /** Initializes auth state (e.g., from stored tokens). */
+  initialize(): Promise<void>
+  /** Re-checks a restored session against the server, in the background — the boot-time validation an app with a stored token needs when a revoked or expired token… */
+  validateSession?(): Promise<void>
+  /** Resolves when the session restore started by `initialize()` has settled — the point after which the client knows whether this visitor is signed in. */
+  whenRestored?(): Promise<void>
+  /** Subscribes to auth state changes. */
+  subscribe(callback: (state: AuthState<T>) => void): () => void
+  /** Subscribes to auth state changes (alias for subscribe). */
+  onAuthChange(callback: (state: AuthState<T>) => void): () => void
+  /** Gets the current access token (alias for getAccessToken). */
+  getToken?(): string | null
+  /** Adds an auth event listener. */
+  addEventListener(listener: AuthEventListener<T>): () => void
+  /** Destroys the auth client. */
+  destroy(): void
+}
 ```
 
+_(Member comments are shortened to their first sentence to fit; the full declaration is in `node_modules/@molecule/app-react-native/dist`.)_
+
 #### `FormController`
 
 Form controller interface.
@@ -357,9 +255,20 @@ interface FormController<T extends FormValuesConstraint<T> = Record<string, unkn
    * `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`).
+   * reads clean (`isDirty === false`). A changed non-null `id` replaces the
+   * record and cancels a pending submit.
    */
   reset(values?: Partial<T>): void
+  /**
+   * Applies externally loaded values without clearing submission state.
+   *
+   * The new clean baseline is the original `defaultValues` plus this latest
+   * record, never a merge of earlier records. With `keepDirtyValues`, edited
+   * fields retain their values while pristine fields take the loaded values.
+   * A changed non-null `id` still replaces the record and cancels a pending
+   * submit. Equal-content baselines cause no update.
+   */
+  updateValues(values: Partial<T>, resetOptions?: FormResetOptions): void
   /**
    * Handles form submission.
    */
@@ -382,6 +291,21 @@ interface FormController<T extends FormValuesConstraint<T> = Record<string, unkn
 }
 ```
 
+#### `FormResetOptions`
+
+Options controlling how externally supplied values replace a form's baseline.
+
+```typescript
+interface FormResetOptions {
+  /**
+   * Keep fields whose current value differs from their baseline when `values`
+   * changes. Pristine fields still take the new values. False by default, so a
+   * new record can replace edits from the previous record.
+   */
+  keepDirtyValues?: boolean
+}
+```
+
 #### `FormOptions`
 
 Form creation options.
@@ -393,6 +317,14 @@ interface FormOptions<T extends FormValuesConstraint<T>> {
    * is created. Mutating this object afterwards does not change the baseline.
    */
   defaultValues?: Partial<T>
+  /**
+   * Externally loaded values, merged over `defaultValues` as the clean
+   * baseline. Framework bindings also apply later content changes; use
+   * `resetOptions.keepDirtyValues` to preserve edits while pristine fields fill.
+   */
+  values?: Partial<T>
+  /** Controls how framework bindings apply changed `values`. */
+  resetOptions?: FormResetOptions
   /**
    * Validation mode.
    */
@@ -869,8 +801,11 @@ interface UseFormResult<T extends FormValuesConstraint<T>> {
   getError: (name: keyof T) => string | undefined
   setError: (name: keyof T, error: string | undefined) => void
   clearErrors: () => void
-  handleSubmit: (onSubmit: (values: T) => void | Promise<void>) => (event?: React.FormEvent) => void
+  handleSubmit: (
+    onSubmit: (values: T) => void | Promise<void>,
+  ) => (event?: React.FormEvent) => Promise<void>
   reset: (values?: Partial<T>) => void
+  updateValues: (values: Partial<T>, resetOptions?: FormResetOptions) => void
   validate: () => Promise<boolean>
 }
 ```
@@ -894,7 +829,8 @@ Result of useHttp hook.
 ```typescript
 interface UseHttpResult<T> extends UseHttpState<T> {
   /**
-   * Runs the request and resolves with its data, or `null` on failure.
+   * Runs the request and resolves with its own data, or `null` on failure,
+   * even when a newer request or `reset` has superseded its displayed state.
    *
    * 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
@@ -921,11 +857,14 @@ interface UseHttpOptions<T> extends RequestConfig {
    */
   immediate?: boolean
   /**
-   * Callback when request succeeds.
+   * Callback for each request that succeeds while mounted, including a request
+   * superseded by another `execute` or `reset`. Read `data` from the hook when
+   * only the newest request's result should drive the UI.
    */
   onSuccess?: (data: T) => void
   /**
-   * Callback when request fails.
+   * Callback for each request that fails while mounted, including a request
+   * superseded by another `execute` or `reset`.
    */
   onError?: (error: Error) => void
 }
@@ -965,6 +904,27 @@ interface UseOAuthReturn {
 }
 ```
 
+#### `UseOptimisticValueResult`
+
+What {@link useOptimisticValue} returns: the state to render and the two ways to change it.
+
+```typescript
+interface UseOptimisticValueResult<T> extends OptimisticValueState<T> {
+  /**
+   * Shows `next` at once and saves it, after any save already running.
+   *
+   * @param next - The value the person chose.
+   */
+  set: (next: T) => void
+  /**
+   * Like `set`, computed from the value shown now (`update((on) => !on)`).
+   *
+   * @param change - Computes the next value from the value shown now.
+   */
+  update: (change: (current: T) => T) => void
+}
+```
+
 #### `UsePasswordResetReturn`
 
 Return type for usePasswordReset hook.
@@ -1287,6 +1247,19 @@ interface ProviderProps {
 }
 ```
 
+#### `SessionReadyProps`
+
+Props for the `SessionReady` component.
+
+```typescript
+interface SessionReadyProps {
+  /** What renders once the initial restore settles — signed in, signed out, or unavailable. */
+  children: ReactNode
+  /** What renders while the session restore is still undecided; default nothing. */
+  fallback?: ReactNode
+}
+```
+
 #### `StateProviderProps`
 
 Props for state provider component.
@@ -1416,6 +1389,20 @@ Properties for molecule provider.
 interface MoleculeProviderProps extends ProviderProps {
   state?: StateProvider
   auth?: AuthClient<unknown>
+  /**
+   * Render the app only once `auth` leaves its initial loading status ({@link SessionReadyProps}).
+   * After a full page load a returning visitor's session is restored by one request, and until
+   * it answers `useAuth().user` is `null` on every page — a public page's signed-in action
+   * (`if (!user) return`, a redirect to `/login`) then treats a signed-in visitor as signed out.
+   * When restoration succeeds, every page's first render reads the restored user. An
+   * `'unavailable'` session also renders, but remains unconfirmed and may have a null user.
+   * A visitor with no session to restore settles in microtasks without a request.
+   * Ignored without `auth`. Synchronous SSR renders the fallback for a loading client:
+   * initialize a request-scoped client first, or leave this disabled for SSR.
+   */
+  awaitSession?: boolean
+  /** Rendered instead of the app while {@link MoleculeProviderProps.awaitSession} waits; default nothing. */
+  sessionFallback?: ReactNode
   theme?: ThemeProvider
   router?: Router
   i18n?: I18nProvider
@@ -1466,7 +1453,9 @@ interface UseAuthResult<
    * The session state as one value — render from this instead of combining
    * `initialized`/`authenticated`/`loading`. A stored token AND user make it
    * `'authenticated'` on the first render; only `'loading'` means "no decision
-   * yet", so a route guard waits on that and nothing else.
+   * yet", so a route guard waits on that and nothing else. `'unavailable'` keeps
+   * a session candidate for retry and can have a null profile; redirect only on
+   * `'unauthenticated'`.
    */
   status: AuthState<T>['status']
   state: AuthState<T>
@@ -1486,8 +1475,10 @@ interface UseAuthResult<
    * `authenticated` read signed out.
    */
   setSession: AuthClient<T>['setSession']
+  /** Whether a session is authenticated locally; this can be false while unavailable. */
   isAuthenticated: boolean
   isLoading: boolean
+  /** The cached profile, which can be null while an unavailable candidate is retained. */
   user: T | null
 }
 ```
@@ -2011,6 +2002,12 @@ function useAuthClient<
 
 Hook for authentication state and actions.
 
+`status === 'loading'` is undecided: wait for it and redirect only on
+`status === 'unauthenticated'`. `'unavailable'` keeps the session candidate
+for retry, but `isAuthenticated` can be false and `user` can be null while a
+token/cookie-only restore has no cached profile. A restore failure other than
+401/403 never signs out.
+
 Pass the app's user type — the SAME type used for the auth client and its
 config (`createJWTAuthClient<MyUser>`, `AuthClientConfig<MyUser>`) — so
 `user` and `setSession`/`setUser` are typed for the pages:
@@ -2214,7 +2211,7 @@ function useForm<T extends FormValuesConstraint<T> = Record<string, unknown>>(
 ): UseFormResult<T>
 ```
 
-- `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.
+- `options` — Form options. `defaultValues`, `mode` and the form-level `validate` are forwarded to the provider. When `values` changes by content, it becomes the new baseline; `resetOptions.keepDirtyValues` retains edited fields while pristine fields take the loaded values. Omit the options entirely for a form whose fields are registered with their own defaults.
 
 **Returns:** Form state and methods
 
@@ -3114,6 +3111,8 @@ function MoleculeProvider({
   workspace,
   editor,
   preview,
+  awaitSession,
+  sessionFallback,
 }: MoleculeProviderProps): React.ReactElement
 ```
 
@@ -3121,6 +3120,38 @@ function MoleculeProvider({
 
 **Returns:** The rendered combined provider element.
 
+#### `SessionReady(props)`
+
+Renders its children once `useAuth().status` has left `'loading'` (signed in, signed out,
+or `'unavailable'`), and `fallback` until then. It never redirects. An unavailable session
+is unconfirmed and may still have `user === null`; handle that status separately from sign-out.
+
+After a full page load a returning visitor's session is restored by one request. Until it
+answers, `useAuth().user` is `null` everywhere, so a public page that renders a signed-in action
+at once lets that action run against "signed out": a Follow button whose handler starts with
+`if (!user) return` ignores the click, one that redirects to `/login` signs the visitor out of
+the flow. Wrapping the routes (or passing `awaitSession` to `MoleculeProvider`) makes every
+page's first render read the restored user when restoration succeeds.
+
+A visitor with no session to restore settles in microtasks without a request. Must render
+inside the auth context (`AuthProvider`, or `MoleculeProvider` with `auth`). A client that
+nobody initialized starts its restore on this first read.
+The bundled JWT client bounds each auth request (default 10 seconds) and settles a timeout
+as `'unavailable'`. Custom clients must also settle their initial session status.
+
+Synchronous SSR renders the fallback while a client is loading. Initialize a request-scoped
+client before rendering to include its decided content, or leave the hold disabled for SSR.
+
+Route-level redirects for signed-in-only pages stay with `AuthGuard` (`@molecule/app-ui-react`).
+
+```typescript
+function SessionReady({ children, fallback }: SessionReadyProps): ReactNode
+```
+
+- `props` — {@link SessionReadyProps}.
+
+**Returns:** The children once the session is decided, otherwise the fallback.
+
 ### Constants
 
 #### `DEFAULT_AGENT_NAME`
@@ -3257,6 +3288,27 @@ const useAsyncState: <T>(initialState: T) => [T, AsyncSetState<T>, AsyncExtendSt
 
 **Returns:** Tuple of [state, asyncSetState, asyncExtendState]
 
+#### `useOptimisticValue`
+
+A server-backed value — a favorite, follow, like or bookmark button, a rating, a quantity, a
+setting switch — that changes on the first render after a tap and is saved one change at a
+time, in order. A tap during a save is saved right after it; only a failure of the newest
+change puts the server value back. See `createOptimisticValue` in `@molecule/app-state`.
+
+`value` is the server's value from props or a query. A new `value` is taken only when it
+differs (by `equals`) from the one the hook last received, and only while nothing is being
+saved, so a parent re-render or a refetch of older data never flips the button mid-save. The
+latest `commit` and `onError` are always used. Give the component a `key` per record, so one
+record's pending change never shows on another.
+
+```typescript
+const useOptimisticValue: <T>(options: OptimisticValueOptions<T>) => UseOptimisticValueResult<T>
+```
+
+- `options` — The server's current value and how to save a change.
+
+**Returns:** The value to render, whether a save is pending, the newest failure, and `set`/`update`.
+
 #### `usePromise`
 
 Hook that wraps an async function with state tracking.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-react-native",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "React Native framework bindings for molecule.dev",
   "homepage": "https://www.molecule.dev/packages/app-react-native",
   "type": "module",
@@ -33,7 +33,7 @@
     "directory": "packages/app/frameworks/react-native"
   },
   "devDependencies": {
-    "@molecule/app-react": "3.0.1",
+    "@molecule/app-react": "3.3.1",
     "@types/node": "26.6.5",
     "react": "19.3.1",
     "typescript": "6.0.3",