@molecule/app-react-native 3.0.5 → 3.0.7

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-11-06T02:49:48.362Z
+Generated: 2026-11-09T15:44:47.787Z
 -->
 
 # @molecule/app-react-native
@@ -78,25 +78,30 @@ interface AuthState<T = UserProfile> {
    * never signs out. See {@link AuthStatus}.
    */
   status: AuthStatus
+
   /**
    * Whether auth state has been initialized.
    */
   initialized: boolean
+
   /**
    * 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, 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
+
   /**
    * Whether an auth operation is in progress.
    */
   loading: boolean
+
   /**
    * Last auth error (if any).
    */
@@ -117,58 +122,82 @@ interface AuthClient<
 > {
   /** 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. */
+
+  /** Exchanges a stored refresh token, or re-reads `currentUserEndpoint` with the existing access token/session cookie when the API has no refresh credential. */
   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`.)_
+_(Member comments are shortened to their first sentence to fit; the full declaration is in `node_modules/@molecule/app-auth/dist/types.d.ts`.)_
 
 #### `FormController`
 
@@ -182,72 +211,77 @@ interface FormController<T extends FormValuesConstraint<T> = Record<string, unkn
    * Gets the current form state.
    */
   getState(): FormState<T>
+
   /**
    * Gets the value of a specific field.
    */
   getValue(name: string): unknown
   getValue<K extends keyof T>(name: K): T[K]
+
   /**
    * Gets all form values.
    */
   getValues(): T
+
   /**
    * Sets the value of a specific field.
    */
   setValue(
     name: string,
     value: unknown,
-    options?: {
-      shouldValidate?: boolean
-      shouldDirty?: boolean
-      shouldTouch?: boolean
-    },
+    options?: { shouldValidate?: boolean; shouldDirty?: boolean; shouldTouch?: boolean },
   ): void
+
   /**
    * Sets multiple values at once.
    */
-  setValues(
-    values: Partial<T>,
-    options?: {
-      shouldValidate?: boolean
-    },
-  ): void
+  setValues(values: Partial<T>, options?: { shouldValidate?: boolean }): void
+
   /**
    * Gets the error for a specific field.
    */
   getError(name: string): string | undefined
+
   /**
    * Sets the error for a specific field.
    */
   setError(name: string, error: string | undefined): void
+
   /**
    * Clears the error for a specific field.
    */
   clearError<K extends keyof T>(name: K): void
+
   /**
    * Clears all errors.
    */
   clearErrors(): void
+
   /**
    * Gets the field state for a specific field.
    */
   getFieldState<K extends keyof T>(name: K): FieldState<T[K]>
+
   /**
    * Registers a field for form management.
    */
   register(nameOrOptions: string | RegisterOptions, options?: RegisterOptions): FieldRegistration
+
   /**
    * Unregisters a field.
    */
   unregister(name: string): void
+
   /**
    * Validates a specific field.
    */
   validateField<K extends keyof T>(name: K): Promise<boolean>
+
   /**
    * Validates all fields.
    */
   validate(): Promise<boolean>
+
   /**
    * Resets the form and clears errors, touched fields and submission state.
    *
@@ -259,6 +293,7 @@ interface FormController<T extends FormValuesConstraint<T> = Record<string, unkn
    * record and cancels a pending submit.
    */
   reset(values?: Partial<T>): void
+
   /**
    * Applies externally loaded values without clearing submission state.
    *
@@ -269,6 +304,7 @@ interface FormController<T extends FormValuesConstraint<T> = Record<string, unkn
    * submit. Equal-content baselines cause no update.
    */
   updateValues(values: Partial<T>, resetOptions?: FormResetOptions): void
+
   /**
    * Handles form submission.
    */
@@ -276,14 +312,17 @@ interface FormController<T extends FormValuesConstraint<T> = Record<string, unkn
     onSubmit: (values: T) => void | Promise<void>,
     onError?: (errors: Partial<Record<keyof T, string>>) => void,
   ): (event?: { preventDefault?: () => void }) => Promise<void>
+
   /**
    * Sets focus to a field.
    */
   setFocus(name: keyof T): void
+
   /**
    * Subscribes to form state changes.
    */
   subscribe(callback: (state: FormState<T>) => void): () => void
+
   /**
    * Destroys the form controller.
    */
@@ -317,26 +356,32 @@ 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.
    */
   mode?: 'onSubmit' | 'onChange' | 'onBlur' | 'all'
+
   /**
    * Revalidation mode.
    */
   reValidateMode?: 'onChange' | 'onBlur' | 'onSubmit'
+
   /**
    * Whether to focus the first error field on submit.
    */
   shouldFocusError?: boolean
+
   /**
    * Form-level validation function.
    */
@@ -358,54 +403,65 @@ interface HttpClient {
    * Base URL for all requests.
    */
   baseURL: string
+
   /**
    * Default headers for all requests.
    */
   defaultHeaders: Record<string, string>
+
   /**
    * Makes a generic HTTP request. `data` is a field of THIS config object — the same body
    * `post(url, data, config)` takes as its second argument.
    */
   request<T = unknown>(config: FullRequestConfig): Promise<HttpResponse<T>>
+
   /**
    * Makes a GET request.
    */
   get<T = unknown>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>
+
   /**
    * Makes a POST request. `data` is the request BODY, not a config object: the wire body is
    * `data` itself, so `post(url, { data: body })` sends `{"data":body}` — pass `body` directly.
    * A config (headers, params) is the THIRD argument.
    */
   post<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
+
   /**
    * Makes a PUT request. `data` is the request BODY (second argument) — never `{ data: body }`,
    * which sends `{"data":body}`; a config is the THIRD argument.
    */
   put<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
+
   /**
    * Makes a PATCH request. `data` is the request BODY (second argument) — never `{ data: body }`,
    * which sends `{"data":body}`; a config is the THIRD argument.
    */
   patch<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
+
   /**
    * Makes a DELETE request.
    */
   delete<T = unknown>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>
+
   /**
    * Adds a request interceptor.
    * Returns a function to remove the interceptor.
    */
   addRequestInterceptor(interceptor: RequestInterceptor): () => void
+
   /**
    * Adds a response interceptor.
    * Returns a function to remove the interceptor.
    */
   addResponseInterceptor(interceptor: ResponseInterceptor): () => void
+
   /**
    * Adds an error interceptor.
    * Returns a function to remove the interceptor.
    */
   addErrorInterceptor(interceptor: ErrorInterceptor): () => void
+
   /**
    * Sets the authorization token.
    *
@@ -417,11 +473,13 @@ interface HttpClient {
    * the resolver is removed, the static token is sent again.
    */
   setAuthToken(token: string | null): void
+
   /**
    * 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`.
@@ -452,6 +510,7 @@ interface HttpClient {
    * @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).
    *
@@ -473,26 +532,32 @@ interface Router {
    * Returns the current route location (pathname, search, hash, state).
    */
   getLocation(): RouteLocation
+
   /**
    * Gets the current route params.
    */
   getParams<T extends RouteParams = RouteParams>(): T
+
   /**
    * Gets the current query params.
    */
   getQuery(): QueryParams
+
   /**
    * Gets a specific query parameter.
    */
   getQueryParam(key: string): string | undefined
+
   /**
    * Gets the current hash.
    */
   getHash(): string
+
   /**
    * Navigates to a path.
    */
   navigate(path: string, options?: NavigateOptions): void
+
   /**
    * Navigates to a named route.
    */
@@ -502,36 +567,44 @@ interface Router {
     query?: QueryParams,
     options?: NavigateOptions,
   ): void
+
   /**
    * Goes back in history.
    */
   back(): void
+
   /**
    * Goes forward in history.
    */
   forward(): void
+
   /**
    * Goes to a specific point in history.
    */
   go(delta: number): void
+
   /**
    * Updates the current query params.
    */
   setQuery(params: QueryParams, options?: NavigateOptions): void
+
   /**
    * Updates a specific query parameter.
    */
   setQueryParam(key: string, value: string | undefined, options?: NavigateOptions): void
+
   /**
    * Updates the current hash.
    */
   setHash(hash: string, options?: NavigateOptions): void
+
   /**
    * Checks if a path matches the current location.
    *
    * @returns `true` if the path matches the current route.
    */
   isActive(path: string, exact?: boolean): boolean
+
   /**
    * Matches a path pattern against a pathname.
    */
@@ -539,26 +612,32 @@ interface Router {
     pattern: string,
     pathname: string,
   ): RouteMatch<Params> | null
+
   /**
    * Generates a URL from a named route.
    */
   generatePath(name: string, params?: RouteParams, query?: QueryParams): string
+
   /**
    * Subscribes to route changes.
    */
   subscribe(listener: RouteChangeListener): () => void
+
   /**
    * Adds a navigation guard.
    */
   addGuard(guard: NavigationGuard): () => void
+
   /**
    * Registers route definitions.
    */
   registerRoutes(routes: RouteDefinition[]): void
+
   /**
    * Gets all registered routes.
    */
   getRoutes(): RouteDefinition[]
+
   /**
    * Destroys the router.
    */
@@ -576,10 +655,12 @@ interface RouterConfig {
    * Router mode.
    */
   mode?: 'history' | 'hash' | 'memory'
+
   /**
    * Base path.
    */
   basePath?: string
+
   /**
    * Initial routes.
    */
@@ -597,10 +678,12 @@ interface StoreConfig<T> {
    * Initial state value.
    */
   initialState: T
+
   /**
    * Optional name for debugging.
    */
   name?: string
+
   /**
    * Optional middleware functions.
    */
@@ -620,15 +703,18 @@ interface Store<T> {
    * Gets the current state.
    */
   getState(): T
+
   /**
    * Sets the state (partial or via updater function).
    */
   setState(partial: Partial<T> | ((state: T) => Partial<T>)): void
+
   /**
    * Subscribes to state changes.
    * Returns an unsubscribe function.
    */
   subscribe(listener: StateListener<T>): () => void
+
   /**
    * Destroys the store and cleans up subscriptions.
    */
@@ -786,21 +872,24 @@ Result of useForm hook.
 
 ```typescript
 interface UseFormResult<T extends FormValuesConstraint<T>> {
+  // State
   formState: FormState<T>
   isValid: boolean
   isDirty: boolean
   isSubmitting: boolean
+
+  // Field methods
   register: (
     name: keyof T,
-    options?: Omit<RegisterOptions, 'name'> & {
-      name?: string
-    },
+    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
   setError: (name: keyof T, error: string | undefined) => void
   clearErrors: () => void
+
+  // Form methods
   handleSubmit: (
     onSubmit: (values: T) => void | Promise<void>,
   ) => (event?: React.FormEvent) => Promise<void>
@@ -916,6 +1005,7 @@ interface UseOptimisticValueResult<T> extends OptimisticValueState<T> {
    * @param next - The value the person chose.
    */
   set: (next: T) => void
+
   /**
    * Like `set`, computed from the value shown now (`update((on) => !on)`).
    *
@@ -1018,13 +1108,9 @@ interface UseProfileFormResult<TUser, TValues extends FormValuesConstraint<TValu
   register: <K extends keyof TValues>(
     name: K,
     options?: Parameters<UseFormResult<TValues>['register']>[1],
-  ) => Omit<FieldRegistration, 'value'> & {
-    value: TValues[K]
-  }
+  ) => 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
-  }
+  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.
@@ -1178,16 +1264,20 @@ interface UseVerifyPaymentReturnOptions {
    * query parameter. Leave unset to verify only what the URL names.
    */
   provider?: string
+
   /** Set `false` to skip verification entirely (e.g. behind a feature flag). */
   enabled?: boolean
+
   /**
    * Remove the provider's query parameters from the address bar once the
    * purchase is verified, so a reload (or a shared link) cannot replay the
    * verification. Defaults to `true`.
    */
   cleanUrl?: boolean
+
   /** Called once, after the purchase verifies. */
   onVerified?: () => void
+
   /** Called when verification fails. */
   onError?: (error: Error) => void
 }
@@ -1205,14 +1295,19 @@ interface UseVerifyPaymentReturnResult {
    * flight; then `verified` or `failed`.
    */
   status: VerifyPaymentReturnStatus
+
   /** `true` when the URL identifies a purchase to verify. */
   isReturn: boolean
+
   /** The provider named by the URL (or the `provider` option). */
   provider: string | null
+
   /** The provider transaction/session id read from the URL. */
   transactionId: string | null
+
   /** Why verification failed, when it did. */
   error: Error | null
+
   /** Re-run the verification — wire this to a retry button. */
   retry: () => void
 }
@@ -1463,6 +1558,8 @@ interface UseAuthResult<
   logout: AuthClient<T>['logout']
   register: AuthClient<T, TRegister>['register']
   refresh: AuthClient<T>['refresh']
+  /** Save through the configured auth transport and persist/publish its canonical profile. */
+  updateProfile: AuthClient<T>['updateProfile']
   setUser: AuthClient<T>['setUser']
   /**
    * Adopt a session an exchange outside the client already established (an
@@ -1700,10 +1797,7 @@ interface UseChatResult {
    * once per second; `attempt` is the 1-based retry number (capped at 3). 4XX,
    * limit/quota, and signup-required errors never auto-retry.
    */
-  retryCountdown: {
-    secondsRemaining: number
-    attempt: number
-  } | null
+  retryCountdown: { secondsRemaining: number; attempt: number } | null
   /** Update the local mode state (for instant mode toggle without an AI turn). */
   setMode: (mode: 'plan' | 'execute') => void
   /** Update the local fast-mode state (for instant toggle without an AI turn). */
@@ -1981,6 +2075,18 @@ function useAIModels(projectId?: string): UseAIModelsResult
 
 **Returns:** Models, free-tier model, loading flag, and error.
 
+#### `useAsyncState(initialState)`
+
+Hook like useState but accepts Promises and supports partial state extension.
+
+```typescript
+function useAsyncState<T>(initialState: T): [T, AsyncSetState<T>, AsyncExtendState<T>]
+```
+
+- `initialState` — Initial state value
+
+**Returns:** Tuple of [state, asyncSetState, asyncExtendState]
+
 #### `useAuthClient()`
 
 Hook to access the auth client from context.
@@ -2012,6 +2118,9 @@ 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:
 `useAuth<MyUser>()`.
+Save profile edits with `updateProfile(patch)`: it uses the configured auth
+transport and publishes the saved user to every subscriber before resolving.
+An app-owned mutation instead passes its canonical response to `setUser`.
 
 For a sign-in the app runs itself (an OAuth redirect, a custom endpoint that
 already issued the token), call `setSession({ accessToken, user })`: it
@@ -2025,7 +2134,7 @@ 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`
+call (and `mapRequestBody` receives that payload as its first argument). Without it, `register`
 accepts only the base fields.
 
 ```typescript
@@ -2440,6 +2549,40 @@ function useOAuth(config?: {
 
 **Returns:** OAuth helpers: providers, getOAuthUrl, redirect, and loginViaPopup.
 
+#### `useOptimisticValue(options)`
+
+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. Taps during a save update the desired value; the newest waiting value is
+saved after it (intermediate waiting values coalesce). 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.
+Keep related fields, such as a favorite flag and its count, in the SAME value. Return both
+from the server response in `commit`, and publish that response to parent/query caches there
+if needed. Let commit reject on failure: a catch that returns old data hides the failure.
+Replace display-state setters and prop-copy effects with this hook's value and `update`.
+`pending` is for feedback, never a reason to disable the toggle or drop a tap.
+
+Render/enable the keyed control only once its initial record exists. Keep that control
+mounted through refetches of the same record. This hook does not fix a click handler that
+returns on a still-null profile, or a remount that throws its controller away. Refetches
+during a save cannot replace pending intent; changed server snapshots arriving AFTER saving
+finishes are accepted and need query-layer ordering if they can be stale. See the module
+quickstart for a complete favorite button with a server-confirmed count.
+
+```typescript
+function 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`.
+
 #### `usePasswordReset()`
 
 Hook for password reset flow with async state tracking.
@@ -2508,6 +2651,34 @@ function useProfileForm<TUser, TValues extends FormValuesConstraint<TValues>>(
 
 **Returns:** Form state, typed control bindings, native submit binding and save error.
 
+#### `usePromise(asyncFn)`
+
+Hook that wraps an async function with state tracking.
+
+For one UI action, pass `state.status === 'pending'` to `Button loading`
+from `@molecule/app-ui-react` (or to a native control's `disabled` prop).
+The control then refuses input while the request is pending and re-enables
+when the tracked call settles. Handle the returned promise's rejection;
+the hook also records the failure in `state.error`.
+
+This hook tracks the latest call: it does not serialize invocations or
+cancel their network requests. An explicit reset/cancel changes the tracked
+state, so it is not proof that an outstanding request has stopped. Use an
+app-owned queue when every click must be accepted in order.
+
+```typescript
+function usePromise<T extends (...args: any[]) => Promise<any>>(
+  asyncFn: T,
+): [
+  UsePromiseState<Awaited<ReturnType<T>>>,
+  (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>,
+]
+```
+
+- `asyncFn` — The async function to wrap
+
+**Returns:** Tuple of [state, wrappedFunction]
+
 #### `usePush(options)`
 
 Hook for push notification state and actions.
@@ -3111,7 +3282,7 @@ function MoleculeProvider({
   workspace,
   editor,
   preview,
-  awaitSession,
+  awaitSession = false,
   sessionFallback,
 }: MoleculeProviderProps): React.ReactElement
 ```
@@ -3145,7 +3316,7 @@ client before rendering to include its decided content, or leave the hold disabl
 Route-level redirects for signed-in-only pages stay with `AuthGuard` (`@molecule/app-ui-react`).
 
 ```typescript
-function SessionReady({ children, fallback }: SessionReadyProps): ReactNode
+function SessionReady({ children, fallback = null }: SessionReadyProps): ReactNode
 ```
 
 - `props` — {@link SessionReadyProps}.
@@ -3276,80 +3447,6 @@ Context for live preview provider.
 const PreviewContext: Context<PreviewProvider | null>
 ```
 
-#### `useAsyncState`
-
-Hook like useState but accepts Promises and supports partial state extension.
-
-```typescript
-const useAsyncState: <T>(initialState: T) => [T, AsyncSetState<T>, AsyncExtendState<T>]
-```
-
-- `initialState` — Initial state value
-
-**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. Taps during a save update the desired value; the newest waiting value is
-saved after it (intermediate waiting values coalesce). 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.
-Keep related fields, such as a favorite flag and its count, in the SAME value. Return both
-from the server response in `commit`, and publish that response to parent/query caches there
-if needed. Let commit reject on failure: a catch that returns old data hides the failure.
-Replace display-state setters and prop-copy effects with this hook's value and `update`.
-`pending` is for feedback, never a reason to disable the toggle or drop a tap.
-
-Render/enable the keyed control only once its initial record exists. Keep that control
-mounted through refetches of the same record. This hook does not fix a click handler that
-returns on a still-null profile, or a remount that throws its controller away. Refetches
-during a save cannot replace pending intent; changed server snapshots arriving AFTER saving
-finishes are accepted and need query-layer ordering if they can be stale. See the module
-quickstart for a complete favorite button with a server-confirmed count.
-
-```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.
-
-For one UI action, pass `state.status === 'pending'` to `Button loading`
-from `@molecule/app-ui-react` (or to a native control's `disabled` prop).
-The control then refuses input while the request is pending and re-enables
-when the tracked call settles. Handle the returned promise's rejection;
-the hook also records the failure in `state.error`.
-
-This hook tracks the latest call: it does not serialize invocations or
-cancel their network requests. An explicit reset/cancel changes the tracked
-state, so it is not proof that an outstanding request has stopped. Use an
-app-owned queue when every click must be accepted in order.
-
-```typescript
-const usePromise: <T extends (...args: any[]) => Promise<any>>(
-  asyncFn: T,
-) => [
-  UsePromiseState<Awaited<ReturnType<T>>>,
-  (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>,
-]
-```
-
-- `asyncFn` — The async function to wrap
-
-**Returns:** Tuple of [state, wrappedFunction]
-
 ## Injection Notes
 
 ### Requirements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-react-native",
-  "version": "3.0.5",
+  "version": "3.0.7",
   "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.4.1",
+    "@molecule/app-react": "3.5.0",
     "@types/node": "26.6.5",
     "react": "19.3.1",
     "typescript": "6.0.3",