@molecule/app-react 3.0.2 → 3.2.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-29T06:28:17.772Z
+Generated: 2026-11-03T18:02:49.265Z
 -->
 
 # @molecule/app-react
@@ -24,6 +24,18 @@ 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.
 
+**Session restore:** `useAuth().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. A restore failure other than 401/403 never signs out.
+`MoleculeProvider auth={authClient} awaitSession` (or `SessionReady` inside
+`AuthProvider`) holds public pages until that initial loading status ends,
+so their first render reads the restored user when restoration succeeds.
+`sessionFallback` remains inside the service providers. Unavailable sessions
+also render and can still have a null user. Synchronous SSR renders the
+fallback for a loading client: initialize a request-scoped client first,
+or leave the opt-in hold disabled for SSR.
+
 > **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.
@@ -57,16 +69,21 @@ import { createJWTAuthClient } from '@molecule/app-auth'
 const authClient = createJWTAuthClient({ baseURL: '/api' })
 
 function Dashboard() {
-  const { user, isAuthenticated, logout } = useAuth<{ name?: string }>()
+  const { user, status, logout } = useAuth<{ name?: string }>()
   const { t } = useTranslation()
   const { theme, toggleTheme } = useTheme()
 
-  if (!isAuthenticated) {
+  if (status === 'loading') {
+    return <p>{t('auth.restoring', undefined, { defaultValue: 'Restoring session...' })}</p>
+  }
+  if (status === 'unauthenticated') {
     return <p>{t('auth.required', undefined, { defaultValue: 'Please log in.' })}</p>
   }
   return (
     <div style={{ background: theme.colors.background }}>
-      <h1>{t('greeting.welcome', { name: user?.name }, { defaultValue: 'Welcome, {{name}}!' })}</h1>
+      <h1>
+        {t('greeting.welcome', { name: user?.name ?? '' }, { defaultValue: 'Welcome, {{name}}!' })}
+      </h1>
       <button onClick={toggleTheme}>
         {t('theme.toggle', undefined, { defaultValue: 'Toggle theme' })}
       </button>
@@ -114,7 +131,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
   /**
@@ -122,11 +142,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
   /**
@@ -180,12 +203,23 @@ interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegi
      * 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.
+     * server returned the canonical row). A non-null profile does NOT change
+     * tokens or 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.
      *
-     * 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.
+     * Passing `null` on a signed-in client, or while any session operation is
+     * pending, ends the local session: it clears the access token, refresh token
+     * and cached user, stops automatic refresh, and settles `authenticated: false`
+     * with `status: 'unauthenticated'` in one notification. Every older operation
+     * loses session ownership, and a persistent sign-out marker prevents a reload
+     * from restoring its credentials or a late cookie. A late credential exchange
+     * is revoked best-effort when a logout endpoint is configured, without blocking
+     * the caller. This method does not otherwise call the server for a settled
+     * session; use {@link logout} for explicit server revocation. On a settled
+     * anonymous client, `null` only clears the cached profile and leaves tokens
+     * and auth state unchanged.
      */
     setUser(user: T | null): void;
     /**
@@ -200,10 +234,13 @@ interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegi
      * 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.
+     * This changes token storage only: passing `null` does not by itself sign a
+     * signed-in client out, and a non-null token does not sign an anonymous
+     * client in (`authenticated` and `status` are unchanged). Use {@link logout}
+     * to end a session, or {@link setUser} with `null` for local-only sign-out.
+     * Use {@link login} / {@link register} for a credential exchange, or call
+     * {@link setSession} with the token and user to establish an already-issued
+     * session.
      */
     setAccessToken(token: string | null): void;
     /**
@@ -228,7 +265,16 @@ interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegi
      */
     login(credentials: LoginCredentials): Promise<AuthResult<T>>;
     /**
-     * Logs out the current user.
+     * Logs out the current user. The server request is best-effort: a missing
+     * logout route (404), any other HTTP failure, or a network error never makes
+     * this method reject. It always clears the access token, refresh token and
+     * cached user, stops automatic refresh, and publishes one settled
+     * `authenticated: false`, `status: 'unauthenticated'` transition. Every pending
+     * session operation loses ownership; a persistent marker prevents reload from
+     * restoring an older session, and late credentials are revoked best-effort.
+     *
+     * When the API has no logout route, set {@link AuthClientConfigOptions.logoutEndpoint}
+     * to `null` (or `''`) to skip the request. Local sign-out still happens.
      */
     logout(): Promise<void>;
     /**
@@ -280,37 +326,6 @@ interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegi
      * 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/dist
 ```
 
@@ -399,9 +414,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.
    */
@@ -424,6 +450,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.
@@ -435,6 +476,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.
    */
@@ -881,6 +930,7 @@ interface UseFormResult<T extends FormValuesConstraint<T>> {
     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>
 }
 ```
@@ -904,7 +954,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
@@ -931,11 +982,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
 }
@@ -1302,6 +1356,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.
@@ -1431,6 +1498,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
@@ -1481,7 +1562,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>
@@ -1501,8 +1584,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
 }
 ```
@@ -1982,6 +2067,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:
@@ -2185,7 +2276,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
 
@@ -3113,6 +3204,8 @@ function MoleculeProvider({
   workspace,
   editor,
   preview,
+  awaitSession = false,
+  sessionFallback,
 }: MoleculeProviderProps): React.ReactElement
 ```
 
@@ -3120,6 +3213,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.
+
+_(description truncated — read the full text in `node_modules/@molecule/app-react/dist/session-ready.d.ts`.)_
+
+```typescript
+function SessionReady({ children, fallback = null }: SessionReadyProps): ReactNode
+```
+
+- `props` — {@link SessionReadyProps}.
+
+**Returns:** The children once the session is decided, otherwise the fallback.
+
 ### Constants
 
 #### `DEFAULT_AGENT_NAME`
@@ -3252,7 +3377,7 @@ Peer dependencies:
 
 - `@molecule/app-auth` ^3.0.0
 - `@molecule/app-ai-models` ^1.0.1
-- `@molecule/app-forms` ^2.0.0
+- `@molecule/app-forms` ^2.2.0
 - `@molecule/app-utilities` ^1.0.1
 - `@molecule/app-http` ^1.0.1
 - `@molecule/app-i18n` ^1.0.1

package/dist/hooks/useAuth.d.ts

@@ -19,6 +19,12 @@ export declare function useAuthClient<T = unknown, TRegister extends RegisterExt
 /**
  * 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:
@@ -44,13 +50,13 @@ export declare function useAuthClient<T = unknown, TRegister extends RegisterExt
  *
  * @example
  * ```tsx
- * const { user, isAuthenticated, login, logout } = useAuth<{ id: string; name?: string }>()
+ * const { user, status, login, logout } = useAuth<{ id: string; name?: string }>()
  * const { register } = useAuth<MyUser, { username: string }>()
  * await register({ email, password, username }) // `username` is typed
  *
- * if (isAuthenticated) {
- *   return <div>Welcome, {user?.name}!</div>
- * }
+ * if (status === 'loading') return <p>Restoring session...</p>
+ * if (status === 'unauthenticated') return <Navigate to="/login" replace />
+ * return <div>Welcome, {user?.name}!</div>
  * ```
  */
 export declare function useAuth<T = unknown, TRegister extends RegisterExtraShape<TRegister> = Record<never, never>>(options?: UseAuthOptions): UseAuthResult<T, TRegister>;

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

@@ -1 +1 @@
-{"version":3,"file":"useAuth.d.ts","sourceRoot":"","sources":["../../src/hooks/useAuth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EACV,UAAU,EAKV,kBAAkB,EACnB,MAAM,oBAAoB,CAAA;AAI3B,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhE;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,CAAC,GAAG,OAAO,EACX,SAAS,SAAS,kBAAkB,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,KACnE,UAAU,CAAC,CAAC,EAAE,SAAS,CAAC,CAU5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,OAAO,CACrB,CAAC,GAAG,OAAO,EACX,SAAS,SAAS,kBAAkB,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACtE,OAAO,CAAC,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,EAAE,SAAS,CAAC,CA2EvD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI,CAG/C;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAG5C"}
+{"version":3,"file":"useAuth.d.ts","sourceRoot":"","sources":["../../src/hooks/useAuth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EACV,UAAU,EAKV,kBAAkB,EACnB,MAAM,oBAAoB,CAAA;AAI3B,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhE;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,CAAC,GAAG,OAAO,EACX,SAAS,SAAS,kBAAkB,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,KACnE,UAAU,CAAC,CAAC,EAAE,SAAS,CAAC,CAU5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,OAAO,CACrB,CAAC,GAAG,OAAO,EACX,SAAS,SAAS,kBAAkB,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACtE,OAAO,CAAC,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,EAAE,SAAS,CAAC,CA2EvD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI,CAG/C;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAG5C"}

package/dist/hooks/useAuth.js

@@ -28,6 +28,12 @@ export 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:
@@ -53,13 +59,13 @@ export function useAuthClient() {
  *
  * @example
  * ```tsx
- * const { user, isAuthenticated, login, logout } = useAuth<{ id: string; name?: string }>()
+ * const { user, status, login, logout } = useAuth<{ id: string; name?: string }>()
  * const { register } = useAuth<MyUser, { username: string }>()
  * await register({ email, password, username }) // `username` is typed
  *
- * if (isAuthenticated) {
- *   return <div>Welcome, {user?.name}!</div>
- * }
+ * if (status === 'loading') return <p>Restoring session...</p>
+ * if (status === 'unauthenticated') return <Navigate to="/login" replace />
+ * return <div>Welcome, {user?.name}!</div>
  * ```
  */
 export function useAuth(options) {

package/dist/hooks/useAuth.js.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"useChat.d.ts","sourceRoot":"","sources":["../../src/hooks/useChat.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,OAAO,KAAK,EAIV,WAAW,EACX,YAAY,EAGb,MAAM,uBAAuB,CAAA;AAK9B,OAAO,KAAK,EAAsB,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AA8cpF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAc1F;AAiBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAQ5F;AAyDD;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAK9C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAU9C;AAkDD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAm4E9D"}
+{"version":3,"file":"useChat.d.ts","sourceRoot":"","sources":["../../src/hooks/useChat.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,OAAO,KAAK,EAIV,WAAW,EACX,YAAY,EAGb,MAAM,uBAAuB,CAAA;AAK9B,OAAO,KAAK,EAAsB,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AA8cpF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAc1F;AAiBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAQ5F;AAyDD;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAK9C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAU9C;AAkDD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAo4E9D"}

package/dist/hooks/useChat.js

@@ -1519,6 +1519,7 @@ export function useChat(options) {
                     type: 'verification',
                     status: event.status,
                     ...(event.output ? { output: event.output } : {}),
+                    ...(event.renderCheckUnavailable ? { renderCheckUnavailable: true } : {}),
                     workspaces: event.workspaces,
                     ...(event.categories ? { categories: event.categories } : {}),
                 });