@molecule/app-react-native 1.0.1 → 1.0.3

package/README.md

@@ -3,15 +3,11 @@ 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-08-04T01:52:27.270Z
+Generated: 2026-10-19T22:40:47.803Z
 -->
 
 # @molecule/app-react-native
 
-> **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.
-
 React Native framework bindings for molecule.dev.
 
 Re-exports every hook and provider from `@molecule/app-react` (they are pure
@@ -19,6 +15,10 @@ React — no DOM dependency) and adds RN-specific hooks: `useAppState`
 (foreground/background), `useBackHandler` (Android back button),
 `useKeyboardHeight`, and `useSafeArea`.
 
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
 ## Quick Start
 
 ```tsx
@@ -64,140 +64,17 @@ npm install @molecule/app-react-native @molecule/app-keyboard @molecule/app-life
 
 ### Interfaces
 
-#### `AgentIdentity`
-
-Display identity for the AI coding agent and the host product, used to
-interpolate the `{{agentName}}` / `{{productName}}` tokens in shared chat/IDE
-copy. A consuming app sets these to its own agent + product brand names; the
-shared packages fall back to {@link DEFAULT_AGENT_IDENTITY} when it does not.
-
-```typescript
-interface AgentIdentity {
-  /** Display name of the AI coding agent. Defaults to {@link DEFAULT_AGENT_NAME}. */
-  agentName: string
-  /** Display name of the host product / IDE. Defaults to {@link DEFAULT_PRODUCT_NAME}. */
-  productName: string
-}
-```
-
-#### `AuthClient`
-
-Auth client interface that all auth bond packages must implement.
-Provides login/logout/register flows, token management, profile
-updates, and auth state subscription.
-
-```typescript
-interface AuthClient<T = UserProfile> {
-  /**
-   * 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
-  /**
-   * 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.
-   */
-  setUser(user: T | null): void
-  /**
-   * Gets the current access token.
-   */
-  getAccessToken(): string | null
-  /**
-   * Stores the access token in the configured token storage adapter (in-memory
-   * by default). 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 in-memory-default storage contract and make the bearer
-   * token JS-readable (XSS-exfiltratable). Pass `null` to clear it.
-   */
-  setAccessToken(token: string | null): 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): 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>
-  /**
-   * 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): () => void
-  /**
-   * Destroys the auth client.
-   */
-  destroy(): void
-}
-```
-
-#### `AuthProviderProps`
-
-Props for auth provider component.
-
-```typescript
-interface AuthProviderProps<T = unknown> extends ProviderProps {
-  client: AuthClient<T>
-}
-```
-
 #### `AuthState`
 
 Reactive authentication state snapshot (initialized, authenticated, user, loading, and error).
 
 ```typescript
 interface AuthState<T = UserProfile> {
+  /**
+   * The session's state as one value — render from this instead of combining
+   * `initialized`/`authenticated`/`loading`. See {@link AuthStatus}.
+   */
+  status: AuthStatus
   /**
    * Whether auth state has been initialized.
    */
@@ -221,24 +98,176 @@ interface AuthState<T = UserProfile> {
 }
 ```
 
-#### `ChatProviderProps`
-
-Props for the ChatProvider React component.
-
-```typescript
-interface ChatProviderProps extends ProviderProps {
-  provider: ChatProvider
-}
-```
-
-#### `EditorProviderProps`
+#### `AuthClient`
 
-Props for editor provider component.
+Auth client interface that all auth bond packages must implement.
+Provides login/logout/register flows, token management, profile
+updates, and auth state subscription.
 
 ```typescript
-interface EditorProviderProps extends ProviderProps {
-  provider: EditorProvider
-}
+interface AuthClient<T = UserProfile, TRegister extends Record<string, unknown> = 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;
+    /**
+     * 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.
+     */
+    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.
+     *
+     * 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
 ```
 
 #### `FormController`
@@ -393,7 +422,8 @@ interface HttpClient {
    */
   defaultHeaders: Record<string, string>
   /**
-   * Makes a generic HTTP request.
+   * 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>>
   /**
@@ -401,15 +431,19 @@ interface HttpClient {
    */
   get<T = unknown>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>
   /**
-   * Makes a POST request.
+   * 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.
+   * 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.
+   * 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>>
   /**
@@ -448,77 +482,6 @@ interface HttpClient {
 }
 ```
 
-#### `HttpProviderProps`
-
-Props for http provider component.
-
-```typescript
-interface HttpProviderProps extends ProviderProps {
-  client: HttpClient
-}
-```
-
-#### `I18nProviderProps`
-
-Props for i18n provider component.
-
-```typescript
-interface I18nProviderProps extends ProviderProps {
-  provider: I18nProvider
-}
-```
-
-#### `LoggerProviderProps`
-
-Props for logger provider component.
-
-```typescript
-interface LoggerProviderProps extends ProviderProps {
-  provider: LoggerProvider
-}
-```
-
-#### `MoleculeProviderProps`
-
-Properties for molecule provider.
-
-```typescript
-interface MoleculeProviderProps extends ProviderProps {
-  state?: StateProvider
-  auth?: AuthClient<unknown>
-  theme?: ThemeProvider
-  router?: Router
-  i18n?: I18nProvider
-  http?: HttpClient
-  storage?: StorageProvider
-  logger?: LoggerProvider
-  chat?: ChatProvider
-  workspace?: WorkspaceProvider
-  editor?: EditorProvider
-  preview?: PreviewProvider
-}
-```
-
-#### `PreviewProviderProps`
-
-Props for preview provider component.
-
-```typescript
-interface PreviewProviderProps extends ProviderProps {
-  provider: PreviewProvider
-}
-```
-
-#### `ProviderProps`
-
-Props for provider components.
-
-```typescript
-interface ProviderProps {
-  children: ReactNode
-}
-```
-
 #### `Router`
 
 Client-side router providing navigation, guards, route matching, and history control.
@@ -645,74 +608,24 @@ interface RouterConfig {
 }
 ```
 
-#### `RouterProviderProps`
-
-Props for router provider component.
-
-```typescript
-interface RouterProviderProps extends ProviderProps {
-  router: Router
-}
-```
-
-#### `SendMessageOptions`
+#### `StoreConfig`
 
-Options for {@link UseChatResult.sendMessage}.
+Configuration for creating a store (initial state, optional name, and middleware chain).
 
 ```typescript
-interface SendMessageOptions {
-  /**
-   * 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
-   * ask_user tool card (a checkmark on the chosen option, or the custom text
-   * shown in-card) rather than echoed as a separate message below it.
-   */
-  suppressUserMessage?: boolean
+interface StoreConfig<T> {
   /**
-   * Mark this send as issued automatically on the user's behalf (e.g. an
-   * auto-fix prompt). The optimistic local bubble and the persisted message are
-   * flagged `automatic` so the chat renders it in the distinct auto-sent style
-   * (agent avatar + accent border) instead of looking like the user typed it.
+   * Initial state value.
    */
-  automatic?: boolean
+  initialState: T
   /**
-   * Mark this send as the answer to the pending `ask_user` question. The most
-   * recent unanswered `ask_user` tool call in the store is resolved in place —
-   * its `output` is set to this answer — so the chosen option stays checked
-   * across remounts (e.g. the discovery→IDE transition) instead of relying on
-   * ephemeral component state that the answer's selection would otherwise lose.
-   * Distinct from {@link suppressUserMessage} (which the post-boot kickoff also
-   * sets) so resolving never misfires on a non-ask_user suppressed send.
+   * Optional name for debugging.
    */
-  askUserAnswer?: boolean
+  name?: string
   /**
-   * Mark an {@link automatic} send as directly requested by the user (e.g. the
-   * editor's "Fix with AI" action, the broken-preview overlay's "Fix with AI"
-   * button) rather than dispatched autonomously by the platform. A user Stop
-   * suppresses autonomous automatic sends until the user re-engages; a
-   * user-initiated one IS that re-engagement — it clears the stop and sends.
+   * Optional middleware functions.
    */
-  userInitiated?: boolean
-}
-```
-
-#### `StateProviderProps`
-
-Props for state provider component.
-
-```typescript
-interface StateProviderProps extends ProviderProps {
-  provider: StateProvider
-}
-```
-
-#### `StorageProviderProps`
-
-Props for storage provider component.
-
-```typescript
-interface StorageProviderProps extends ProviderProps {
-  provider: StorageProvider
+  middleware?: StoreMiddleware<T>[]
 }
 ```
 
@@ -744,30 +657,9 @@ interface Store<T> {
 }
 ```
 
-#### `StoreConfig`
+#### `Theme`
 
-Configuration for creating a store (initial state, optional name, and middleware chain).
-
-```typescript
-interface StoreConfig<T> {
-  /**
-   * Initial state value.
-   */
-  initialState: T
-  /**
-   * Optional name for debugging.
-   */
-  name?: string
-  /**
-   * Optional middleware functions.
-   */
-  middleware?: StoreMiddleware<T>[]
-}
-```
-
-#### `Theme`
-
-Complete theme definition.
+Complete theme definition.
 
 ```typescript
 interface Theme {
@@ -784,36 +676,14 @@ interface Theme {
 }
 ```
 
-#### `ThemeProviderProps`
-
-Props for theme provider component.
-
-```typescript
-interface ThemeProviderProps extends ProviderProps {
-  provider: ThemeProvider
-  initialTheme?: string
-}
-```
-
-#### `UseAIModelsResult`
+#### `UseBackHandlerOptions`
 
-Result returned by `useAIModels`.
+Options for the useBackHandler hook.
 
 ```typescript
-interface UseAIModelsResult {
-  /** Available models, or an empty array while loading. */
-  models: AppModelDefinition[]
-  /**
-   * Per-mode server default model ids for the requester's tier, or `undefined`
-   * while loading or on servers that don't provide them.
-   */
-  defaults: AppModeModelDefaults | undefined
-  /** The single model marked `freeTier: true`, or `undefined`. */
-  freeTierModel: AppModelDefinition | undefined
-  /** `true` while the initial fetch is in flight. */
-  loading: boolean
-  /** Error from the initial fetch, or `null`. */
-  error: Error | null
+interface UseBackHandlerOptions {
+  /** Whether the handler is enabled. Defaults to true. */
+  enabled?: boolean
 }
 ```
 
@@ -830,45 +700,54 @@ interface UseAppStateResult {
 }
 ```
 
-#### `UseAuthOptions`
+#### `UseKeyboardHeightResult`
 
-Hook options for useAuth.
+Result from the useKeyboardHeight hook.
 
 ```typescript
-interface UseAuthOptions {
-  /**
-   * Whether to automatically refresh the token on mount.
-   */
-  autoRefresh?: boolean
+interface UseKeyboardHeightResult {
+  /** Current keyboard height in points (0 when hidden) */
+  keyboardHeight: number
+  /** Whether the keyboard is currently visible */
+  isKeyboardVisible: boolean
 }
 ```
 
-#### `UseAuthResult`
+#### `AgentIdentity`
 
-Hook result for useAuth.
+Display identity for the AI coding agent and the host product, used to
+interpolate the `{{agentName}}` / `{{productName}}` tokens in shared chat/IDE
+copy. A consuming app sets these to its own agent + product brand names; the
+shared packages fall back to {@link DEFAULT_AGENT_IDENTITY} when it does not.
 
 ```typescript
-interface UseAuthResult<T = unknown> {
-  state: AuthState<T>
-  login: AuthClient<T>['login']
-  logout: AuthClient<T>['logout']
-  register: AuthClient<T>['register']
-  refresh: AuthClient<T>['refresh']
-  setUser: AuthClient<T>['setUser']
-  isAuthenticated: boolean
-  isLoading: boolean
-  user: T | null
+interface AgentIdentity {
+  /** Display name of the AI coding agent. Defaults to {@link DEFAULT_AGENT_NAME}. */
+  agentName: string
+  /** Display name of the host product / IDE. Defaults to {@link DEFAULT_PRODUCT_NAME}. */
+  productName: string
 }
 ```
 
-#### `UseBackHandlerOptions`
+#### `UseAIModelsResult`
 
-Options for the useBackHandler hook.
+Result returned by `useAIModels`.
 
 ```typescript
-interface UseBackHandlerOptions {
-  /** Whether the handler is enabled. Defaults to true. */
-  enabled?: boolean
+interface UseAIModelsResult {
+  /** Available models, or an empty array while loading. */
+  models: AppModelDefinition[]
+  /**
+   * Per-mode server default model ids for the requester's tier, or `undefined`
+   * while loading or on servers that don't provide them.
+   */
+  defaults: AppModeModelDefaults | undefined
+  /** The single model marked `freeTier: true`, or `undefined`. */
+  freeTierModel: AppModelDefinition | undefined
+  /** `true` while the initial fetch is in flight. */
+  loading: boolean
+  /** Error from the initial fetch, or `null`. */
+  error: Error | null
 }
 ```
 
@@ -885,130 +764,6 @@ interface UseChangePasswordReturn {
 }
 ```
 
-#### `UseChatOptions`
-
-Hook options for useChat.
-
-```typescript
-interface UseChatOptions {
-  /** Chat endpoint (e.g., '/projects/123/chat'). */
-  endpoint: string
-  /** Project ID for context. */
-  projectId?: string
-  /**
-   * Display name of the AI coding agent, interpolated into user-facing chat
-   * copy (e.g. the stalled-stream notice). The host passes its own agent brand
-   * name; defaults to the neutral `DEFAULT_AGENT_NAME` so the shared hook never
-   * names a specific product.
-   */
-  agentName?: string
-  /** Load history on mount. */
-  loadOnMount?: boolean
-  /** Called when a file is created or modified by a tool call (path + new content). */
-  onFileChange?: (path: string, content: string) => void
-  /** Called when the AI switches between plan and execute modes. */
-  onModeChange?: (mode: 'plan' | 'execute') => void
-  /** Called when the backend assigns or confirms a conversation ID. */
-  onConversationId?: (id: string) => void
-  /** Called for every streaming event — useful for notifications, sounds, etc. */
-  onStreamEvent?: (event: ChatStreamEvent) => void
-}
-```
-
-#### `UseChatResult`
-
-Hook result for useChat.
-
-```typescript
-interface UseChatResult {
-  messages: ChatMessage[]
-  isLoading: boolean
-  /**
-   * True while a backend turn for this conversation streams WITHOUT this client
-   * owning the request — a turn started in another tab, by a teammate, or any
-   * server-side continuation. Detected from pushed (broadcast) chat events and
-   * confirmed/cleared against the server's `streaming` history flag, so the Stop
-   * control can stay visible and functional whenever ANY backend turn is live —
-   * not only for sends this hook instance made.
-   */
-  isRemoteStreaming: boolean
-  /**
-   * Tell the hook a pushed (broadcast) chat event arrived for this conversation.
-   * The host (ChatPanel) calls this from its push-channel handler; the hook then
-   * confirms against the server's `streaming` flag and, while a remote turn is
-   * live, keeps `isRemoteStreaming` true until the server reports it finished.
-   */
-  noteRemoteStreamEvent: () => void
-  error: string | null
-  /** Metadata about a limit-related error (for contextual upgrade CTAs). */
-  errorMeta: {
-    limitType?: string
-    requiresSignup?: boolean
-  } | null
-  /** Current agent mode — plan (read-only research) or execute (full access). */
-  mode: 'plan' | 'execute'
-  /**
-   * Whether the conversation runs at the provider's fast/priority speed tier
-   * (server-persisted per conversation; hydrated from the history load's
-   * `fastMode` meta field, when the server provides one). Only meaningful for
-   * models that support a fast tier — the server ignores it otherwise.
-   */
-  fastMode: boolean
-  /**
-   * Transient label for a background phase (e.g. the post-response verification
-   * pass — "Type-checking the API", "Linting"), set by `status` stream events.
-   * The UI shows it in place of the spinner's generic rotating messages; `null`
-   * when no such phase is active.
-   */
-  streamingStatus: string | null
-  /**
-   * Active 5XX backoff-retry countdown, or `null` when none is pending. After a
-   * backend server error (HTTP 5XX) the hook does NOT surface a terminal error —
-   * it shows this cancelable countdown and, when it elapses, auto-resumes the
-   * turn where the user left off (`resume:true`). `secondsRemaining` ticks down
-   * 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
-  /** 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). */
-  setFastMode: (fastMode: boolean) => void
-  sendMessage: (
-    message: string,
-    attachments?: ChatAttachment[],
-    options?: SendMessageOptions,
-  ) => Promise<void>
-  abort: () => void
-  /**
-   * Cancel a pending 5XX auto-retry. Clears the countdown and surfaces the
-   * original error (via `error`) so the user sees why the turn failed.
-   */
-  cancelRetry: () => void
-  clearHistory: () => Promise<void>
-  /** Edit the content of a queued (not yet sent) message. */
-  editQueuedMessage: (msgId: string, newContent: string) => void
-  /** Remove a queued (not yet sent) message from the queue. */
-  deleteQueuedMessage: (msgId: string) => void
-  /** Remove queued auto-fix messages whose content references the given file path. */
-  clearQueuedForFile: (filePath: string) => void
-  /**
-   * Append an inline transcript card (model / mode / skills / custom notice) as a
-   * `role:'system'` card-message in the ONE message store. Used by the host (ChatPanel)
-   * to render a TEAMMATE's broadcast `card` event live — this client's OWN cards arrive
-   * through the stream and are appended internally. De-duped by the server-assigned id.
-   */
-  appendCardMessage: (
-    id: string,
-    timestamp: number,
-    card: NonNullable<ChatMessage['cardEvent']>,
-  ) => void
-}
-```
-
 #### `UseDeviceResult`
 
 Hook return type.
@@ -1027,30 +782,6 @@ interface UseDeviceResult {
 }
 ```
 
-#### `UseEditorResult`
-
-Hook result for useEditor.
-
-```typescript
-interface UseEditorResult {
-  tabs: EditorTab[]
-  activeFile: string | null
-  openFile: (file: EditorFile) => void
-  closeFile: (path: string) => void
-  getContent: () => string | null
-  setContent: (path: string, content: string) => void
-  setActiveTab: (path: string) => void
-  mount: EditorProvider['mount']
-  dispose: () => void
-  focus: () => void
-  openDiff: (file: DiffFile) => void
-  closeDiff: () => void
-  pinTab: (path: string) => void
-  addExtraLib: (content: string, filePath: string) => void
-  onFixWithAI: (callback: (request: FixWithAIRequest) => void) => () => void
-}
-```
-
 #### `UseFormOptions`
 
 Options for useForm hook.
@@ -1086,24 +817,15 @@ interface UseFormResult<T extends Record<string, unknown>> {
 }
 ```
 
-#### `UseHttpOptions`
+#### `UseHttpState`
 
-Options for useHttp hook.
+State for async HTTP operations.
 
 ```typescript
-interface UseHttpOptions<T> extends RequestConfig {
-  /**
-   * Whether to execute the request immediately on mount.
-   */
-  immediate?: boolean
-  /**
-   * Callback when request succeeds.
-   */
-  onSuccess?: (data: T) => void
-  /**
-   * Callback when request fails.
-   */
-  onError?: (error: Error) => void
+interface UseHttpState<T> {
+  data: T | null
+  loading: boolean
+  error: Error | null
 }
 ```
 
@@ -1118,28 +840,24 @@ interface UseHttpResult<T> extends UseHttpState<T> {
 }
 ```
 
-#### `UseHttpState`
-
-State for async HTTP operations.
-
-```typescript
-interface UseHttpState<T> {
-  data: T | null
-  loading: boolean
-  error: Error | null
-}
-```
-
-#### `UseKeyboardHeightResult`
+#### `UseHttpOptions`
 
-Result from the useKeyboardHeight hook.
+Options for useHttp hook.
 
 ```typescript
-interface UseKeyboardHeightResult {
-  /** Current keyboard height in points (0 when hidden) */
-  keyboardHeight: number
-  /** Whether the keyboard is currently visible */
-  isKeyboardVisible: boolean
+interface UseHttpOptions<T> extends RequestConfig {
+  /**
+   * Whether to execute the request immediately on mount.
+   */
+  immediate?: boolean
+  /**
+   * Callback when request succeeds.
+   */
+  onSuccess?: (data: T) => void
+  /**
+   * Callback when request fails.
+   */
+  onError?: (error: Error) => void
 }
 ```
 
@@ -1210,32 +928,6 @@ interface UsePlatformResult {
 }
 ```
 
-#### `UsePreviewResult`
-
-Hook result for usePreview.
-
-```typescript
-interface UsePreviewResult {
-  state: PreviewState
-  setUrl: (url: string) => void
-  refresh: () => void
-  setDevice: (device: DeviceFrame) => void
-  openExternal: () => void
-  /**
-   * Records a navigation the running preview reported via its `molecule:navigate`
-   * message — updates the displayed current location without reloading the iframe.
-   * Pass `isReplace` when the preview REPLACED its current history entry (a
-   * `replaceState` redirect/canonicalization) so the forward stack is preserved
-   * instead of truncated (a `pushState`, the default, truncates forward).
-   */
-  recordNavigation: (url: string, isReplace?: boolean) => void
-  /** Navigates the preview to the previous navigation-history entry (Back). */
-  back: () => void
-  /** Navigates the preview to the next navigation-history entry (Forward). */
-  forward: () => void
-}
-```
-
 #### `UsePromiseState`
 
 Extended promise state with actions.
@@ -1250,19 +942,6 @@ interface UsePromiseState<T> {
 }
 ```
 
-#### `UsePushOptions`
-
-Options for the usePush hook (e.g. check permission on mount).
-
-```typescript
-interface UsePushOptions {
-  /**
-   * Whether to check permission status on mount.
-   */
-  checkOnMount?: boolean
-}
-```
-
 #### `UsePushResult`
 
 Hook return type.
@@ -1283,20 +962,16 @@ interface UsePushResult {
 }
 ```
 
-#### `UseRouterResult`
+#### `UsePushOptions`
 
-Hook result for useRouter.
+Options for the usePush hook (e.g. check permission on mount).
 
 ```typescript
-interface UseRouterResult {
-  location: Router['getLocation'] extends () => infer R ? R : never
-  params: Record<string, string>
-  query: QueryParams
-  navigate: Router['navigate']
-  navigateTo: Router['navigateTo']
-  back: Router['back']
-  forward: Router['forward']
-  isActive: Router['isActive']
+interface UsePushOptions {
+  /**
+   * Whether to check permission status on mount.
+   */
+  checkOnMount?: boolean
 }
 ```
 
@@ -1345,44 +1020,54 @@ interface UseStorageValueResult<T> {
 }
 ```
 
-#### `UseStoreOptions`
-
-Hook options for useStore.
-
-```typescript
-interface UseStoreOptions<T, S> {
-  selector?: (state: T) => S
-  equalityFn?: (a: S, b: S) => boolean
-}
-```
-
-#### `UseThemeResult`
+#### `UseVerifyPaymentReturnOptions`
 
-Hook result for useTheme.
+Options for {@link useVerifyPaymentReturn}.
 
 ```typescript
-interface UseThemeResult {
-  theme: Theme
-  themeName: string
-  setTheme: (name: string) => void
-  toggleTheme: () => void
-  mode: 'light' | 'dark'
+interface UseVerifyPaymentReturnOptions {
+  /**
+   * Provider name to verify with, when the return URL carries no `provider`
+   * 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
 }
 ```
 
-#### `UseTranslationResult`
+#### `UseVerifyPaymentReturnResult`
 
-Hook result for useTranslation.
+State of the post-checkout verification.
 
 ```typescript
-interface UseTranslationResult {
-  t: I18nProvider['t']
-  locale: string
-  setLocale: I18nProvider['setLocale']
-  locales: ReturnType<I18nProvider['getLocales']>
-  formatNumber: I18nProvider['formatNumber']
-  formatDate: I18nProvider['formatDate']
-  direction: 'ltr' | 'rtl'
+interface UseVerifyPaymentReturnResult {
+  /**
+   * `idle` when this page load is not a checkout return (no transaction id in
+   * the URL) or auth is still hydrating; `verifying` while the API call is in
+   * 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
 }
 ```
 
@@ -1405,207 +1090,812 @@ interface UseVersionResult {
 }
 ```
 
-#### `UseWorkspaceResult`
+#### `ProviderProps`
 
-Hook result for useWorkspace.
+Props for provider components.
 
 ```typescript
-interface UseWorkspaceResult {
-  layout: WorkspaceLayout
-  activePanel: PanelId | null
-  collapsedPanels: Set<PanelId>
-  togglePanel: (panelId: PanelId) => void
-  resizePanel: (panelId: PanelId, size: number) => void
-  setActivePanel: (panelId: PanelId) => void
-  resetLayout: () => void
+interface ProviderProps {
+  children: ReactNode
 }
 ```
 
-#### `WorkspaceProviderProps`
+#### `StateProviderProps`
 
-Props for workspace provider component.
+Props for state provider component.
 
 ```typescript
-interface WorkspaceProviderProps extends ProviderProps {
-  provider: WorkspaceProvider
+interface StateProviderProps extends ProviderProps {
+  provider: StateProvider
 }
 ```
 
-### Types
-
-#### `AsyncExtendState`
+#### `AuthProviderProps`
 
-Async-capable extendState function for partial updates.
+Props for auth provider component.
 
 ```typescript
-type AsyncExtendState<T> = (
-  partial: Partial<T> | ((prev: T) => Partial<T>) | Promise<Partial<T> | ((prev: T) => Partial<T>)>,
-) => void
+interface AuthProviderProps<T = unknown> extends ProviderProps {
+  client: AuthClient<T>
+}
 ```
 
-#### `AsyncSetState`
+#### `ThemeProviderProps`
 
-Async-capable setState function.
+Props for theme provider component.
 
 ```typescript
-type AsyncSetState<T> = (value: T | ((prev: T) => T) | Promise<T | ((prev: T) => T)>) => void
+interface ThemeProviderProps extends ProviderProps {
+  provider: ThemeProvider
+  initialTheme?: string
+}
 ```
 
-#### `UseCapacitorAppResult`
+#### `RouterProviderProps`
 
-Hook return type.
+Props for router provider component.
 
 ```typescript
-type UseCapacitorAppResult = CapacitorAppState & {
-  initialize: () => Promise<void>
+interface RouterProviderProps extends ProviderProps {
+  router: Router
 }
 ```
 
-### Functions
-
-#### `AuthProvider(props)`
+#### `I18nProviderProps`
 
-Provider for authentication.
+Props for i18n provider component.
 
 ```typescript
-function AuthProvider({
-  client,
-  children,
-}: AuthProviderProps<T>): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+interface I18nProviderProps extends ProviderProps {
+  provider: I18nProvider
+}
 ```
 
-- `props` — Component props (see {@link AuthProviderProps}).
+#### `HttpProviderProps`
 
-**Returns:** The rendered auth provider element.
+Props for http provider component.
 
-#### `ChatProvider(props)`
+```typescript
+interface HttpProviderProps extends ProviderProps {
+  client: HttpClient
+}
+```
 
-Provider for AI chat.
+#### `StorageProviderProps`
+
+Props for storage provider component.
 
 ```typescript
-function ChatProvider({
-  provider,
-  children,
-}: ChatProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+interface StorageProviderProps extends ProviderProps {
+  provider: StorageProvider
+}
 ```
 
-- `props` — Component props (see {@link ChatProviderProps}).
+#### `LoggerProviderProps`
 
-**Returns:** The rendered chat provider element.
+Props for logger provider component.
 
-#### `EditorProvider(props)`
+```typescript
+interface LoggerProviderProps extends ProviderProps {
+  provider: LoggerProvider
+}
+```
 
-Provider for code editor.
+#### `ChatProviderProps`
+
+Props for the ChatProvider React component.
 
 ```typescript
-function EditorProvider({
-  provider,
-  children,
-}: EditorProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+interface ChatProviderProps extends ProviderProps {
+  provider: ChatProvider
+}
 ```
 
-- `props` — Component props (see {@link EditorProviderProps}).
+#### `WorkspaceProviderProps`
 
-**Returns:** The rendered editor provider element.
+Props for workspace provider component.
 
-#### `HttpProvider(props)`
+```typescript
+interface WorkspaceProviderProps extends ProviderProps {
+  provider: WorkspaceProvider
+}
+```
+
+#### `EditorProviderProps`
+
+Props for editor provider component.
+
+```typescript
+interface EditorProviderProps extends ProviderProps {
+  provider: EditorProvider
+}
+```
+
+#### `PreviewProviderProps`
+
+Props for preview provider component.
+
+```typescript
+interface PreviewProviderProps extends ProviderProps {
+  provider: PreviewProvider
+}
+```
+
+#### `MoleculeProviderProps`
+
+Properties for molecule provider.
+
+```typescript
+interface MoleculeProviderProps extends ProviderProps {
+  state?: StateProvider
+  auth?: AuthClient<unknown>
+  theme?: ThemeProvider
+  router?: Router
+  i18n?: I18nProvider
+  http?: HttpClient
+  storage?: StorageProvider
+  logger?: LoggerProvider
+  chat?: ChatProvider
+  workspace?: WorkspaceProvider
+  editor?: EditorProvider
+  preview?: PreviewProvider
+}
+```
+
+#### `UseStoreOptions`
+
+Hook options for useStore.
+
+```typescript
+interface UseStoreOptions<T, S> {
+  selector?: (state: T) => S
+  equalityFn?: (a: S, b: S) => boolean
+}
+```
+
+#### `UseAuthOptions`
+
+Hook options for useAuth.
+
+```typescript
+interface UseAuthOptions {
+  /**
+   * Whether to automatically refresh the token on mount.
+   */
+  autoRefresh?: boolean
+}
+```
+
+#### `UseAuthResult`
+
+Hook result for useAuth.
+
+```typescript
+interface UseAuthResult<T = unknown> {
+  /**
+   * 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.
+   */
+  status: AuthState<T>['status']
+  state: AuthState<T>
+  login: AuthClient<T>['login']
+  logout: AuthClient<T>['logout']
+  register: AuthClient<T>['register']
+  refresh: AuthClient<T>['refresh']
+  setUser: AuthClient<T>['setUser']
+  /**
+   * Adopt a session an exchange outside the client already established (an
+   * OAuth code→token redirect, the app's own sign-in endpoint) in ONE update:
+   * the token and user are stored and the hook's consumers see the client as
+   * `authenticated` immediately.
+   *
+   * `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).
+   */
+  setSession: AuthClient<T>['setSession']
+  isAuthenticated: boolean
+  isLoading: boolean
+  user: T | null
+}
+```
+
+#### `UseThemeResult`
+
+Hook result for useTheme.
+
+```typescript
+interface UseThemeResult {
+  theme: Theme
+  themeName: string
+  setTheme: (name: string) => void
+  toggleTheme: () => void
+  mode: 'light' | 'dark'
+}
+```
+
+#### `UseRouterResult`
+
+Hook result for useRouter.
+
+```typescript
+interface UseRouterResult {
+  location: Router['getLocation'] extends () => infer R ? R : never
+  params: Record<string, string>
+  query: QueryParams
+  navigate: Router['navigate']
+  navigateTo: Router['navigateTo']
+  back: Router['back']
+  forward: Router['forward']
+  isActive: Router['isActive']
+}
+```
+
+#### `UseTranslationResult`
+
+Hook result for useTranslation.
+
+```typescript
+interface UseTranslationResult {
+  t: I18nProvider['t']
+  locale: string
+  setLocale: I18nProvider['setLocale']
+  locales: ReturnType<I18nProvider['getLocales']>
+  formatNumber: I18nProvider['formatNumber']
+  formatDate: I18nProvider['formatDate']
+  direction: 'ltr' | 'rtl'
+}
+```
+
+#### `UseChatOptions`
+
+Hook options for useChat.
+
+```typescript
+interface UseChatOptions {
+  /** Chat endpoint (e.g., '/projects/123/chat'). */
+  endpoint: string
+  /** Project ID for context. */
+  projectId?: string
+  /**
+   * Display name of the AI coding agent, interpolated into user-facing chat
+   * copy (e.g. the stalled-stream notice). The host passes its own agent brand
+   * name; defaults to the neutral `DEFAULT_AGENT_NAME` so the shared hook never
+   * names a specific product.
+   */
+  agentName?: string
+  /** Load history on mount. */
+  loadOnMount?: boolean
+  /**
+   * This client may only WATCH the conversation (e.g. a read-only project
+   * viewer): the hook never issues chat POSTs on its behalf — no resume
+   * request after a reload, no auto-retries. A live turn is followed through
+   * the remote-watch path instead: pushed broadcast frames (applyRemoteEvent)
+   * render it in real time and the history reconcile poll backstops gaps, with
+   * `isRemoteStreaming` driving the activity indicator.
+   */
+  readOnly?: boolean
+  /** Called when a file is created or modified by a tool call (path + new content). */
+  onFileChange?: (path: string, content: string) => void
+  /** Called when the AI switches between plan and execute modes. */
+  onModeChange?: (mode: 'plan' | 'execute') => void
+  /** Called when the backend assigns or confirms a conversation ID. */
+  onConversationId?: (id: string) => void
+  /** Called for every streaming event — useful for notifications, sounds, etc. */
+  onStreamEvent?: (event: ChatStreamEvent) => void
+}
+```
+
+#### `SendMessageOptions`
+
+Options for {@link UseChatResult.sendMessage}.
+
+```typescript
+interface SendMessageOptions {
+  /**
+   * 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
+   * ask_user tool card (a checkmark on the chosen option, or the custom text
+   * shown in-card) rather than echoed as a separate message below it.
+   */
+  suppressUserMessage?: boolean
+  /**
+   * Mark this send as issued automatically on the user's behalf (e.g. an
+   * auto-fix prompt). The optimistic local bubble and the persisted message are
+   * flagged `automatic` so the chat renders it in the distinct auto-sent style
+   * (agent avatar + accent border) instead of looking like the user typed it.
+   */
+  automatic?: boolean
+  /**
+   * Mark this send as the answer to the pending `ask_user` question. The most
+   * recent unanswered `ask_user` tool call in the store is resolved in place —
+   * its `output` is set to this answer — so the chosen option stays checked
+   * across remounts (e.g. the discovery→IDE transition) instead of relying on
+   * ephemeral component state that the answer's selection would otherwise lose.
+   * Distinct from {@link suppressUserMessage} (which the post-boot kickoff also
+   * sets) so resolving never misfires on a non-ask_user suppressed send.
+   */
+  askUserAnswer?: boolean
+  /**
+   * Mark an {@link automatic} send as directly requested by the user (e.g. the
+   * editor's "Fix with AI" action, the broken-preview overlay's "Fix with AI"
+   * button) rather than dispatched autonomously by the platform. A user Stop
+   * suppresses autonomous automatic sends until the user re-engages; a
+   * user-initiated one IS that re-engagement — it clears the stop and sends.
+   */
+  userInitiated?: boolean
+  /**
+   * Send on the SIDE CHANNEL: a human-to-human message (e.g. a team note) the
+   * server intercepts before running any agent turn. When the provider supports
+   * `sendSideMessage`, the send goes out IMMEDIATELY on an independent request —
+   * it never queues behind an active turn, never takes over the streaming
+   * state, and never tears down remote-turn tracking (a viewer's note while
+   * watching a teammate's turn must not stop the watching). Falls back to the
+   * normal send path on providers without side-channel support.
+   */
+  sideChannel?: boolean
+  /**
+   * Mark this send as composed through voice dictation — the mic button's
+   * transcript was still present in the composer at submit. The optimistic
+   * bubble and the persisted message are flagged `viaDictation` so the chat
+   * renders a mic badge on the message, live and after a reload.
+   */
+  viaDictation?: boolean
+}
+```
+
+#### `UseChatResult`
+
+Hook result for useChat.
+
+```typescript
+interface UseChatResult {
+  messages: ChatMessage[]
+  isLoading: boolean
+  /**
+   * True while a backend turn for this conversation streams WITHOUT this client
+   * owning the request — a turn started in another tab, by a teammate, or any
+   * server-side continuation. Detected from pushed (broadcast) chat events and
+   * confirmed/cleared against the server's `streaming` history flag, so the Stop
+   * control can stay visible and functional whenever ANY backend turn is live —
+   * not only for sends this hook instance made.
+   */
+  isRemoteStreaming: boolean
+  /**
+   * Tell the hook a pushed (broadcast) chat event arrived for this conversation.
+   * The host (ChatPanel) calls this from its push-channel handler; the hook then
+   * confirms against the server's `streaming` flag and, while a remote turn is
+   * live, keeps `isRemoteStreaming` true until the server reports it finished.
+   */
+  noteRemoteStreamEvent: () => void
+  error: string | null
+  /**
+   * Metadata about a limit-related error, for a contextual call-to-action.
+   * `limitType` names the RULE the backend enforced; `billingAction` names the
+   * REMEDY it resolved (e.g. `add_funds`, `add_payment_method`,
+   * `raise_spend_cap`, `upgrade`, `none`) and is what the button should be
+   * built from — the same limit needs a different button per account.
+   * `upgradeTier` is the plan an upgrade would move to, explicitly `null` when
+   * there is no higher tier. The backend owns these vocabularies, so the
+   * action/tier are plain strings here.
+   */
+  errorMeta: {
+    limitType?: string
+    requiresSignup?: boolean
+    billingAction?: string
+    upgradeTier?: string | null
+  } | null
+  /** Current agent mode — plan (read-only research) or execute (full access). */
+  mode: 'plan' | 'execute'
+  /**
+   * Whether the conversation runs at the provider's fast/priority speed tier
+   * (server-persisted per conversation; hydrated from the history load's
+   * `fastMode` meta field, when the server provides one). Only meaningful for
+   * models that support a fast tier — the server ignores it otherwise.
+   */
+  fastMode: boolean
+  /**
+   * Transient label for a background phase (e.g. the post-response verification
+   * pass — "Type-checking the API", "Linting"), set by `status` stream events.
+   * The UI shows it in place of the spinner's generic rotating messages; `null`
+   * when no such phase is active.
+   */
+  streamingStatus: string | null
+  /**
+   * Commands the executor detached with `run_in_background`, newest last. Each
+   * appears here the moment it starts and is replaced in place when it finishes,
+   * so the UI can show work that outlives the tool call that started it.
+   */
+  backgroundTasks: BackgroundTaskState[]
+  /**
+   * Active 5XX backoff-retry countdown, or `null` when none is pending. After a
+   * backend server error (HTTP 5XX) the hook does NOT surface a terminal error —
+   * it shows this cancelable countdown and, when it elapses, auto-resumes the
+   * turn where the user left off (`resume:true`). `secondsRemaining` ticks down
+   * 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
+  /** 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). */
+  setFastMode: (fastMode: boolean) => void
+  sendMessage: (
+    message: string,
+    attachments?: ChatAttachment[],
+    options?: SendMessageOptions,
+  ) => Promise<void>
+  abort: () => void
+  /**
+   * Cancel a pending 5XX auto-retry. Clears the countdown and surfaces the
+   * original error (via `error`) so the user sees why the turn failed.
+   */
+  cancelRetry: () => void
+  clearHistory: () => Promise<void>
+  /** Edit the content of a queued (not yet sent) message. */
+  editQueuedMessage: (msgId: string, newContent: string) => void
+  /** Remove a queued (not yet sent) message from the queue. */
+  deleteQueuedMessage: (msgId: string) => void
+  /** Remove queued auto-fix messages whose content references the given file path. */
+  clearQueuedForFile: (filePath: string) => void
+  /**
+   * Append an inline transcript card (model / mode / skills / custom notice) as a
+   * `role:'system'` card-message in the ONE message store. Used by the host (ChatPanel)
+   * to render a TEAMMATE's broadcast `card` event live — this client's OWN cards arrive
+   * through the stream and are appended internally. De-duped by the server-assigned id.
+   */
+  appendCardMessage: (
+    id: string,
+    timestamp: number,
+    card: NonNullable<ChatMessage['cardEvent']>,
+  ) => void
+  /**
+   * Append a COMPLETE, non-streaming chat message (a `message` stream event — e.g.
+   * a teammate's human-only team note) to the ONE message store. Used by the host
+   * (ChatPanel) to render a TEAMMATE's broadcast `message` event live — this
+   * client's OWN `message` events arrive through the stream and are appended
+   * internally. De-duped by the server-assigned message id.
+   */
+  appendCompleteMessage: (message: ChatMessage) => void
+  /**
+   * Ingest ONE pushed (broadcast) stream frame from a turn running elsewhere —
+   * a teammate's send, another tab, a server-side continuation — into the ONE
+   * message store, through the same content applier as an own SSE stream: text/
+   * thinking deltas, tool events, verification, cards, complete messages, done.
+   * The host (ChatPanel) calls this from its push-channel handler for every
+   * broadcast frame of the OPEN conversation. Own echoes are dropped while a
+   * local send is in flight (the SSE stream is authoritative for the sender);
+   * complete id-carrying items (cards, team notes) always apply, de-duped.
+   */
+  applyRemoteEvent: (event: ChatStreamEvent) => void
+  /**
+   * Reload history and converge the local view on the server transcript (and
+   * re-enter a still-streaming turn). The page-lifecycle events run this
+   * automatically; the host should ALSO call it whenever its chat push channel
+   * (re)connects — a broadcast sent while that socket was down (a teammate's
+   * team note against a backgrounded tab or a slept laptop) is otherwise lost
+   * until the next lifecycle event happens to fire. Cheap when nothing changed:
+   * an identical transcript is never re-applied.
+   */
+  reconcileHistory: () => Promise<void>
+}
+```
 
-Provider for HTTP client.
+#### `UseWorkspaceResult`
+
+Hook result for useWorkspace.
 
 ```typescript
-function HttpProvider({
-  client,
-  children,
-}: HttpProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+interface UseWorkspaceResult {
+  layout: WorkspaceLayout
+  activePanel: PanelId | null
+  collapsedPanels: Set<PanelId>
+  togglePanel: (panelId: PanelId) => void
+  resizePanel: (panelId: PanelId, size: number) => void
+  setActivePanel: (panelId: PanelId) => void
+  resetLayout: () => void
+}
+```
+
+#### `UseEditorResult`
+
+Hook result for useEditor.
+
+```typescript
+interface UseEditorResult {
+  tabs: EditorTab[]
+  activeFile: string | null
+  openFile: (file: EditorFile) => void
+  closeFile: (path: string) => void
+  getContent: () => string | null
+  setContent: (path: string, content: string) => void
+  setActiveTab: (path: string) => void
+  mount: EditorProvider['mount']
+  dispose: () => void
+  focus: () => void
+  openDiff: (file: DiffFile) => void
+  closeDiff: () => void
+  pinTab: (path: string) => void
+  addExtraLib: (content: string, filePath: string) => void
+  onFixWithAI: (callback: (request: FixWithAIRequest) => void) => () => void
+}
+```
+
+#### `UsePreviewResult`
+
+Hook result for usePreview.
+
+```typescript
+interface UsePreviewResult {
+  state: PreviewState
+  setUrl: (url: string) => void
+  refresh: () => void
+  setDevice: (device: DeviceFrame) => void
+  openExternal: () => void
+  /**
+   * Records a navigation the running preview reported via its `molecule:navigate`
+   * message — updates the displayed current location without reloading the iframe.
+   * Pass `isReplace` when the preview REPLACED its current history entry (a
+   * `replaceState` redirect/canonicalization) so the forward stack is preserved
+   * instead of truncated (a `pushState`, the default, truncates forward).
+   */
+  recordNavigation: (url: string, isReplace?: boolean) => void
+  /** Navigates the preview to the previous navigation-history entry (Back). */
+  back: () => void
+  /** Navigates the preview to the next navigation-history entry (Forward). */
+  forward: () => void
+}
+```
+
+### Types
+
+#### `AsyncSetState`
+
+Async-capable setState function.
+
+```typescript
+type AsyncSetState<T> = (value: T | ((prev: T) => T) | Promise<T | ((prev: T) => T)>) => void
+```
+
+- `value` — The new state value, an updater function receiving previous state, or a Promise resolving to either.
+
+#### `AsyncExtendState`
+
+Async-capable extendState function for partial updates.
+
+```typescript
+type AsyncExtendState<T> = (
+  partial: Partial<T> | ((prev: T) => Partial<T>) | Promise<Partial<T> | ((prev: T) => Partial<T>)>,
+) => void
+```
+
+#### `UseCapacitorAppResult`
+
+Hook return type.
+
+```typescript
+type UseCapacitorAppResult = CapacitorAppState & {
+  initialize: () => Promise<void>
+}
+```
+
+#### `VerifyPaymentReturnStatus`
+
+How far the return-page verification has got.
+
+```typescript
+type VerifyPaymentReturnStatus = 'idle' | 'verifying' | 'verified' | 'failed'
+```
+
+### Functions
+
+#### `useAppState()`
+
+Tracks whether the app is in the foreground, background, or inactive.
+
+Uses React Native's `AppState` API under the hood. Falls back to
+'active' on platforms where AppState is unavailable.
+
+```typescript
+function useAppState(): UseAppStateResult
+```
+
+**Returns:** Current app state and whether the app is active.
+
+#### `useBackHandler(handler, options)`
+
+Registers a handler for the Android hardware back button.
+
+Return `true` from the handler to prevent the default back behavior,
+or `false` to allow it.
+
+```typescript
+function useBackHandler(handler: () => boolean, options?: UseBackHandlerOptions): void
+```
+
+- `handler` — Callback invoked when the hardware back button is pressed.
+- `options` — Optional configuration.
+
+#### `useKeyboardHeight()`
+
+Tracks soft keyboard visibility and height.
+
+Uses React Native's `Keyboard` API. Falls back to hidden state
+on platforms where Keyboard is unavailable.
+
+```typescript
+function useKeyboardHeight(): UseKeyboardHeightResult
+```
+
+**Returns:** Current keyboard height and visibility state.
+
+#### `useSafeArea()`
+
+Returns the current safe area insets from `react-native-safe-area-context`.
+
+Must be used within a `SafeAreaProvider`. Falls back to zero insets
+if the context is unavailable.
+
+```typescript
+function useSafeArea(): SafeAreaInsets
+```
+
+**Returns:** Safe area insets for the current device.
+
+#### `resetAIModelsCache()`
+
+Test-only: drops every cached model list so the next `useAIModels` call
+refetches. Exposed for unit tests; do not call from production code.
+
+```typescript
+function resetAIModelsCache(): void
+```
+
+#### `useAIModels(projectId)`
+
+Subscribes to the cached AI model catalog. The first mount of a scope
+triggers a single `GET /ai/models` fetch; subsequent mounts return the
+cached result.
+
+```typescript
+function useAIModels(projectId?: string): UseAIModelsResult
 ```
 
-- `props` — Component props (see {@link HttpProviderProps}).
+- `projectId` — Optional project scope: includes that project's custom ("bring your own AI") models on servers that support them.
+
+**Returns:** Models, free-tier model, loading flag, and error.
+
+#### `useAuthClient()`
+
+Hook to access the auth client from context.
+
+```typescript
+function useAuthClient(): AuthClient<T, Record<never, never>>
+```
+
+**Returns:** The auth client from context
+
+#### `useAuth(options)`
+
+Hook for authentication state and actions.
+
+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>()`.
+
+For a sign-in the app runs itself (an OAuth redirect, a custom endpoint that
+already issued the token), call `setSession({ accessToken, user })`: it
+adopts the token and profile atomically and every consumer of this hook sees
+`status: 'authenticated'` at once. `setUser` alone does not sign in.
+
+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.
+
+```typescript
+function useAuth(options?: UseAuthOptions): UseAuthResult<T>
+```
+
+- `options` — Hook options
+
+**Returns:** Auth state and action methods
+
+#### `useUser()`
+
+Hook to get just the authenticated user.
+
+```typescript
+function useUser(): T | null
+```
 
-**Returns:** The rendered HTTP provider element.
+**Returns:** The authenticated user or null
 
-#### `I18nProvider(props)`
+#### `useIsAuthenticated()`
 
-Provider for internationalization.
+Hook to check if user is authenticated.
 
 ```typescript
-function I18nProvider({
-  provider,
-  children,
-}: I18nProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function useIsAuthenticated(): boolean
 ```
 
-- `props` — Component props (see {@link I18nProviderProps}).
+**Returns:** Whether the user is authenticated
 
-**Returns:** The rendered i18n provider element.
+#### `useCapacitorApp(options)`
 
-#### `LoggerProvider(props)`
+Hook for Capacitor app initialization and state management.
 
-Provider for logging.
+Creates a `CapacitorApp` coordinator on mount, subscribes to state changes,
+and auto-initializes. Cleans up listeners on unmount via `destroy()`.
 
 ```typescript
-function LoggerProvider({
-  provider,
-  children,
-}: LoggerProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function useCapacitorApp(options?: CapacitorAppOptions): UseCapacitorAppResult
 ```
 
-- `props` — Component props (see {@link LoggerProviderProps}).
-
-**Returns:** The rendered logger provider element.
+- `options` — Capacitor app configuration options
 
-#### `MoleculeProvider(props)`
+**Returns:** Current app state and an `initialize` function for manual re-initialization
 
-Combined provider for all molecule services.
+#### `useChangePassword()`
 
-Provides a convenient way to wrap your app with all molecule providers at once.
-Only providers that are passed will be included.
+Hook for changing password with async state tracking.
 
 ```typescript
-function MoleculeProvider({
-  children,
-  state,
-  auth,
-  theme,
-  router,
-  i18n,
-  http,
-  storage,
-  logger,
-  chat,
-  workspace,
-  editor,
-  preview,
-}: MoleculeProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function useChangePassword(): UseChangePasswordReturn
 ```
 
-- `props` — Component props (see {@link MoleculeProviderProps}) — each service is optional, and ONLY the services passed are provided to the tree.
+**Returns:** Change password state and action
 
-**Returns:** The rendered combined provider element.
+#### `convergeHistory(prev, history)`
 
-#### `PreviewProvider(props)`
+Converge a live store on a fresh server history WITHOUT rewinding anything
+already on screen. This is the ONE place a server transcript is applied to a
+local view — the page-lifecycle/push reconcile, the remote-turn poll, the
+dropped-stream reconcile and the resume poll all go through it, because two
+paths that almost agree is how a message came to vanish and come back
+(reported 2026-09-21).
 
-Provider for live preview.
+Per message id the further-along copy wins ({@link messageProgress}); a TIE
+keeps the local copy, so an unchanged transcript returns the same object
+references and a poll neither churns React nor rewinds. Messages only the
+server has are added in the server's order (filling gaps a watcher missed);
+messages only the store has ({@link localOnlyMessages} — an answer still
+carrying its local id, a session-local card, a turn the server has not
+persisted yet) are kept after them.
 
 ```typescript
-function PreviewProvider({
-  provider,
-  children,
-}: PreviewProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function convergeHistory(prev: ChatMessage[], history: ChatMessage[]): ChatMessage[]
 ```
 
-- `props` — Component props (see {@link PreviewProviderProps}).
+- `prev` — The store's current messages.
+- `history` — The messages from the server's history endpoint.
 
-**Returns:** The rendered preview provider element.
+**Returns:** The converged message list.
 
-#### `resetAIModelsCache()`
+#### `localOnlyMessages(prev, history)`
 
-Test-only: drops every cached model list so the next `useAIModels` call
-refetches. Exposed for unit tests; do not call from production code.
+The messages only the local store holds, given a server history: optimistic
+bubbles and session-local cards, minus the optimistic ECHO of a send the
+server already persisted. A local user message carries a local id
+(`user-N`), the server's copy a server id, so ids never match — content does.
+Without this, the dashboard's first prompt (auto-sent by the workspace,
+then merged back in from history by the remote-stream poll) rendered as two
+identical user bubbles in every new project (2026-09-08).
 
 ```typescript
-function resetAIModelsCache(): void
+function localOnlyMessages(prev: ChatMessage[], history: ChatMessage[]): ChatMessage[]
 ```
 
+- `prev` — The store's current messages.
+- `history` — The server's history.
+
+**Returns:** The local-only messages to keep after the merged history.
+
 #### `resetChatStoresForTests()`
 
 Test-only: clear all conversation stores. The store is module-level (it must
@@ -1616,201 +1906,181 @@ outlive component mounts), so it persists across test cases — reset it in a
 function resetChatStoresForTests(): void
 ```
 
-#### `RouterProvider(props)`
+#### `useChatProvider()`
 
-Provider for routing.
+Access the chat provider from context.
 
 ```typescript
-function RouterProvider({
-  router,
-  children,
-}: RouterProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function useChatProvider(): ChatProvider
 ```
 
-- `props` — Component props (see {@link RouterProviderProps}).
+**Returns:** The ChatProvider instance from the nearest ChatContext.
 
-**Returns:** The rendered router provider element.
+#### `useChat(options)`
 
-#### `StateProvider(props)`
+Hook for AI chat with streaming support.
 
-Provider for state management.
+Manages message state, sends messages to the backend, and handles
+SSE streaming responses.
 
 ```typescript
-function StateProvider({
-  provider,
-  children,
-}: StateProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function useChat(options: UseChatOptions): UseChatResult
 ```
 
-- `props` — Component props (see {@link StateProviderProps}).
-
-**Returns:** The rendered state provider element.
-
-#### `StorageProvider(props)`
-
-Provider for storage.
-
-```typescript
-function StorageProvider({
-  provider,
-  children,
-}: StorageProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
-```
+- `options` — Chat configuration including endpoint URL, project ID, and whether to load history on mount.
 
-- `props` — Component props (see {@link StorageProviderProps}).
+**Returns:** Chat state and controls: messages, isLoading, error, sendMessage, abort, and clearHistory.
 
-**Returns:** The rendered storage provider element.
+#### `useDevice()`
 
-#### `ThemeProvider(props)`
+Hook for device information.
 
-Provider for theming.
+Uses module-level `getProvider()` — device info is a singleton, not context-provided.
+Device info is static and doesn't change at runtime, so this uses `useMemo`.
 
 ```typescript
-function ThemeProvider({
-  provider,
-  children,
-}: ThemeProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function useDevice(): UseDeviceResult
 ```
 
-- `props` — Component props (see {@link ThemeProviderProps}).
-
-**Returns:** The rendered theme provider element.
+**Returns:** Device information and utility methods
 
-#### `useAIModels(projectId)`
+#### `useEditorProvider()`
 
-Subscribes to the cached AI model catalog. The first mount of a scope
-triggers a single `GET /ai/models` fetch; subsequent mounts return the
-cached result.
+Access the editor provider from context.
 
 ```typescript
-function useAIModels(projectId?: string): UseAIModelsResult
+function useEditorProvider(): EditorProvider
 ```
 
-- `projectId` — Optional project scope: includes that project's custom ("bring your own AI") models on servers that support them.
-
-**Returns:** Models, free-tier model, loading flag, and error.
-
-#### `useAppState()`
+**Returns:** The EditorProvider instance from the nearest EditorContext.
 
-Tracks whether the app is in the foreground, background, or inactive.
+#### `useEditor()`
 
-Uses React Native's `AppState` API under the hood. Falls back to
-'active' on platforms where AppState is unavailable.
+Hook for code editor management.
 
 ```typescript
-function useAppState(): UseAppStateResult
+function useEditor(): UseEditorResult
 ```
 
-**Returns:** Current app state and whether the app is active.
+**Returns:** Editor state and controls: tabs, activeFile, openFile, closeFile, getContent, setContent, setActiveTab, mount, dispose, and focus.
 
-#### `useAuth(options)`
+#### `useForm(options)`
 
-Hook for authentication state and actions.
+Hook for form state management.
 
 ```typescript
-function useAuth(options?: UseAuthOptions): UseAuthResult<T>
+function useForm(options: UseFormOptions<T>): UseFormResult<T>
 ```
 
-- `options` — Hook options
+- `options` — Form options including createForm from a forms provider
 
-**Returns:** Auth state and action methods
+**Returns:** Form state and methods
 
-#### `useAuthClient()`
+#### `useWatch(form, name)`
 
-Hook to access the auth client from context.
+Hook to watch a specific field value.
 
 ```typescript
-function useAuthClient(): AuthClient<T>
+function useWatch(form: FormController<T>, name: K): T[K]
 ```
 
-**Returns:** The auth client from context
+- `form` — Form controller
+- `name` — Field name to watch
 
-#### `useBackHandler(handler, options)`
+**Returns:** Current field value
 
-Registers a handler for the Android hardware back button.
+#### `useFieldState(form, name)`
 
-Return `true` from the handler to prevent the default back behavior,
-or `false` to allow it.
+Hook to get field-level state.
 
 ```typescript
-function useBackHandler(handler: () => boolean, options?: UseBackHandlerOptions): void
+function useFieldState(form: FormController<T>, name: keyof T): FieldState<T[keyof T]>
 ```
 
-- `handler` — Callback invoked when the hardware back button is pressed.
-- `options` — Optional configuration.
+- `form` — Form controller
+- `name` — Field name
 
-#### `useCapacitorApp(options)`
+**Returns:** Field state (value, error, touched, dirty, valid)
 
-Hook for Capacitor app initialization and state management.
+#### `useHttpClient()`
 
-Creates a `CapacitorApp` coordinator on mount, subscribes to state changes,
-and auto-initializes. Cleans up listeners on unmount via `destroy()`.
+Hook to access the HTTP client from context.
 
 ```typescript
-function useCapacitorApp(options?: CapacitorAppOptions): UseCapacitorAppResult
+function useHttpClient(): HttpClient
 ```
 
-- `options` — Capacitor app configuration options
-
-**Returns:** Current app state and an `initialize` function for manual re-initialization
+**Returns:** The HTTP client from context
 
-#### `useChangePassword()`
+#### `useHttp(method, url, options)`
 
-Hook for changing password with async state tracking.
+Hook for making HTTP requests with state management.
 
 ```typescript
-function useChangePassword(): UseChangePasswordReturn
+function useHttp(
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  url: string,
+  options?: UseHttpOptions<T>,
+): UseHttpResult<T>
 ```
 
-**Returns:** Change password state and action
+- `method` — HTTP method
+- `url` — Request URL
+- `options` — Request options
 
-#### `useChat(options)`
+**Returns:** Request state and execute function
 
-Hook for AI chat with streaming support.
+#### `useGet(url, options)`
 
-Manages message state, sends messages to the backend, and handles
-SSE streaming responses.
+Hook for GET requests.
 
 ```typescript
-function useChat(options: UseChatOptions): UseChatResult
+function useGet(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
 ```
 
-- `options` — Chat configuration including endpoint URL, project ID, and whether to load history on mount.
+- `url` — Request URL to fetch from.
+- `options` — HTTP request options including callbacks and request config.
 
-**Returns:** Chat state and controls: messages, isLoading, error, sendMessage, abort, and clearHistory.
+**Returns:** Request state (data, loading, error) and controls (execute, reset).
 
-#### `useChatProvider()`
+#### `usePost(url, options)`
 
-Access the chat provider from context.
+Hook for POST requests.
 
 ```typescript
-function useChatProvider(): ChatProvider
+function usePost(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
 ```
 
-**Returns:** The ChatProvider instance from the nearest ChatContext.
+- `url` — Request URL to post to.
+- `options` — HTTP request options including body data and callbacks.
 
-#### `useChildLogger(parentName, context)`
+**Returns:** Request state (data, loading, error) and controls (execute, reset).
 
-Hook to create a child logger with additional context.
+#### `usePut(url, options)`
+
+Hook for PUT requests.
 
 ```typescript
-function useChildLogger(parentName: string, context: Record<string, unknown>): Logger
+function usePut(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
 ```
 
-- `parentName` — Parent logger name
-- `context` — Additional context to include in logs
+- `url` — Request URL to send the PUT request to.
+- `options` — HTTP request options including body data and callbacks.
 
-**Returns:** Child logger instance
+**Returns:** Request state (data, loading, error) and controls (execute, reset).
 
-#### `useCurrentTheme()`
+#### `usePatch(url, options)`
 
-Hook to get just the current theme object.
+Hook for PATCH requests.
 
 ```typescript
-function useCurrentTheme(): Theme
+function usePatch(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
 ```
 
-**Returns:** The current theme
+- `url` — Request URL to send the PATCH request to.
+- `options` — HTTP request options including partial body data and callbacks.
+
+**Returns:** Request state (data, loading, error) and controls (execute, reset).
 
 #### `useDelete(url, options)`
 
@@ -1825,189 +2095,175 @@ function useDelete(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
 
 **Returns:** Request state (data, loading, error) and controls (execute, reset).
 
-#### `useDevice()`
-
-Hook for device information.
+#### `useLoggerProvider()`
 
-Uses module-level `getProvider()` — device info is a singleton, not context-provided.
-Device info is static and doesn't change at runtime, so this uses `useMemo`.
+Hook to access the logger provider from context.
 
 ```typescript
-function useDevice(): UseDeviceResult
+function useLoggerProvider(): LoggerProvider
 ```
 
-**Returns:** Device information and utility methods
+**Returns:** The logger provider from context
 
-#### `useDirection()`
+#### `useLogger(name, config)`
 
-Hook to get the text direction.
+Hook to get a logger instance.
 
 ```typescript
-function useDirection(): 'ltr' | 'rtl'
+function useLogger(name: string, config?: Partial<LoggerConfig>): Logger
 ```
 
-**Returns:** The text direction ('ltr' or 'rtl')
-
-#### `useEditor()`
-
-Hook for code editor management.
-
-```typescript
-function useEditor(): UseEditorResult
-```
+- `name` — Logger name (usually component or module name)
+- `config` — Optional logger configuration
 
-**Returns:** Editor state and controls: tabs, activeFile, openFile, closeFile, getContent, setContent, setActiveTab, mount, dispose, and focus.
+**Returns:** Logger instance
 
-#### `useEditorProvider()`
+#### `useRootLogger()`
 
-Access the editor provider from context.
+Hook to get the root logger.
 
 ```typescript
-function useEditorProvider(): EditorProvider
+function useRootLogger(): Logger
 ```
 
-**Returns:** The EditorProvider instance from the nearest EditorContext.
+**Returns:** Root logger instance
 
-#### `useFieldState(form, name)`
+#### `useChildLogger(parentName, context)`
 
-Hook to get field-level state.
+Hook to create a child logger with additional context.
 
 ```typescript
-function useFieldState(form: FormController<T>, name: keyof T): FieldState<T[keyof T]>
+function useChildLogger(parentName: string, context: Record<string, unknown>): Logger
 ```
 
-- `form` — Form controller
-- `name` — Field name
+- `parentName` — Parent logger name
+- `context` — Additional context to include in logs
 
-**Returns:** Field state (value, error, touched, dirty, valid)
+**Returns:** Child logger instance
 
-#### `useForm(options)`
+#### `useLogin()`
 
-Hook for form state management.
+Hook for login with async state tracking.
+Registration is available through `const { register } = useAuth()`;
+call `register({ email, password, name })` to create an account. There is
+no separate `useRegister` hook. Use `usePromise(register)` when the form
+needs the same pending/error tracking as this login hook.
 
 ```typescript
-function useForm(options: UseFormOptions<T>): UseFormResult<T>
+function useLogin(): UseLoginReturn<T>
 ```
 
-- `options` — Form options including createForm from a forms provider
+**Returns:** Login state and action
 
-**Returns:** Form state and methods
+#### `useOAuth(config)`
 
-#### `useGet(url, options)`
+Hook for OAuth authentication.
 
-Hook for GET requests.
+Reads OAuth configuration from the provided config and provides
+helpers to build OAuth URLs and start a login (full-page or popup).
+Automatically handles OAuth callbacks by detecting `code` and `state`
+URL parameters and exchanging them for a session — and, when the callback is
+running inside a popup we opened, relaying the result to the opener instead.
 
 ```typescript
-function useGet(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
+function useOAuth(config?: {
+  baseURL?: string
+  oauthProviders?: string[]
+  oauthEndpoint?: string
+  loginEndpoint?: string
+  onSuccess?: () => void
+  onError?: (error: string) => void
+}): UseOAuthReturn
 ```
 
-- `url` — Request URL to fetch from.
-- `options` — HTTP request options including callbacks and request config.
-
-**Returns:** Request state (data, loading, error) and controls (execute, reset).
-
-#### `useHttp(method, url, options)`
-
-Hook for making HTTP requests with state management.
-
-```typescript
-function useHttp(
-  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
-  url: string,
-  options?: UseHttpOptions<T>,
-): UseHttpResult<T>
-```
+- `config` — Optional OAuth configuration override.
+- `config.baseURL` — Base URL for the API server (e.g. "https://api.example.com").
+- `config.oauthProviders` — List of supported OAuth provider names (e.g. ["google", "github"]).
+- `config.oauthEndpoint` — Path prefix for OAuth routes (defaults to "/oauth").
+- `config.loginEndpoint` — Path for the OAuth login POST endpoint (defaults to "/users/log-in/oauth").
+- `config.onSuccess` — Callback after successful OAuth login.
+- `config.onError` — Callback on OAuth login failure.
 
-- `method` — HTTP method
-- `url` — Request URL
-- `options` — Request options
+**Returns:** OAuth helpers: providers, getOAuthUrl, redirect, and loginViaPopup.
 
-**Returns:** Request state and execute function
+#### `usePasswordReset()`
 
-#### `useHttpClient()`
+Hook for password reset flow with async state tracking.
 
-Hook to access the HTTP client from context.
+Provides separate tracking for the request and confirm steps.
 
 ```typescript
-function useHttpClient(): HttpClient
+function usePasswordReset(): UsePasswordResetReturn
 ```
 
-**Returns:** The HTTP client from context
+**Returns:** Password reset state and actions
 
-#### `useI18nError(error)`
+#### `usePlatform()`
 
-Translates an error at render time so the displayed message updates automatically
-when the locale changes.
+Hook for platform detection.
 
-**Always use this hook to display errors in React components** — accessing
-`error.message` directly bypasses re-translation and leaves stale text after a
-locale switch. If `error` is an `I18nError` (thrown via `throw new I18nError(key)`),
-its key is translated using the current locale. For plain `Error` instances,
-`error.message` is returned unchanged.
+Uses module-level functions — platform is a singleton, not context-provided.
+Platform info is static and doesn't change at runtime, so this uses `useMemo`.
 
 ```typescript
-function useI18nError(error: Error | null | undefined): string | null
+function usePlatform(): UsePlatformResult
 ```
 
-- `error` — The error to translate, or `null`/`undefined`.
-
-**Returns:** The translated error string, or `null` if no error.
+**Returns:** Platform information and utility methods
 
-#### `useI18nProvider()`
+#### `usePreviewProvider()`
 
-Hook to access the i18n provider from context.
+Access the preview provider from context.
 
 ```typescript
-function useI18nProvider(): I18nProvider
+function usePreviewProvider(): PreviewProvider
 ```
 
-**Returns:** The i18n provider from context
+**Returns:** The PreviewProvider instance from the nearest PreviewContext.
 
-#### `useIsActive(path, exact)`
+#### `usePreview()`
 
-Hook to check if a path is active.
+Hook for live preview management.
 
 ```typescript
-function useIsActive(path: string, exact?: boolean): boolean
+function usePreview(): UsePreviewResult
 ```
 
-- `path` — The path to check
-- `exact` — Whether to match exactly (default: false)
+**Returns:** Preview state and controls: state (url, isLoading, device, error, isConnected), setUrl, refresh, setDevice, and openExternal.
 
-**Returns:** Whether the path is active
+#### `usePush(options)`
 
-#### `useIsAuthenticated()`
+Hook for push notification state and actions.
 
-Hook to check if user is authenticated.
+Uses module-level `getProvider()` — push is a singleton, not context-provided.
 
 ```typescript
-function useIsAuthenticated(): boolean
+function usePush(options?: UsePushOptions): UsePushResult
 ```
 
-**Returns:** Whether the user is authenticated
+- `options` — Hook options
 
-#### `useKeyboardHeight()`
+**Returns:** Push notification state and action methods
 
-Tracks soft keyboard visibility and height.
+#### `useRouterInstance()`
 
-Uses React Native's `Keyboard` API. Falls back to hidden state
-on platforms where Keyboard is unavailable.
+Hook to access the router from context.
 
 ```typescript
-function useKeyboardHeight(): UseKeyboardHeightResult
+function useRouterInstance(): Router
 ```
 
-**Returns:** Current keyboard height and visibility state.
+**Returns:** The router from context
 
-#### `useLocale()`
+#### `useRouter()`
 
-Hook to get the current locale.
+Hook for routing state and actions.
 
 ```typescript
-function useLocale(): string
+function useRouter(): UseRouterResult
 ```
 
-**Returns:** The current locale code
+**Returns:** Router state and navigation methods
 
 #### `useLocation()`
 
@@ -2019,491 +2275,574 @@ function useLocation(): RouteLocation
 
 **Returns:** The current route location
 
-#### `useLogger(name, config)`
+#### `useParams()`
 
-Hook to get a logger instance.
+Hook to get route parameters.
 
 ```typescript
-function useLogger(name: string, config?: Partial<LoggerConfig>): Logger
+function useParams(): T
 ```
 
-- `name` — Logger name (usually component or module name)
-- `config` — Optional logger configuration
-
-**Returns:** Logger instance
+**Returns:** The current route parameters
 
-#### `useLoggerProvider()`
+#### `useQuery()`
 
-Hook to access the logger provider from context.
+Hook to get query parameters.
 
 ```typescript
-function useLoggerProvider(): LoggerProvider
+function useQuery(): T
 ```
 
-**Returns:** The logger provider from context
+**Returns:** The current query parameters
 
-#### `useLogin()`
+#### `useNavigate()`
 
-Hook for login with async state tracking.
+Hook to get the navigate function.
 
 ```typescript
-function useLogin(): UseLoginReturn<T>
+function useNavigate(): (path: string, options?: NavigateOptions) => void
 ```
 
-**Returns:** Login state and action
+**Returns:** The navigate function
 
-#### `useNavigate()`
+#### `useIsActive(path, exact)`
 
-Hook to get the navigate function.
+Hook to check if a path is active.
 
 ```typescript
-function useNavigate(): (path: string, options?: NavigateOptions) => void
+function useIsActive(path: string, exact?: boolean): boolean
 ```
 
-**Returns:** The navigate function
+- `path` — The path to check
+- `exact` — Whether to match exactly (default: false)
 
-#### `useOAuth(config)`
+**Returns:** Whether the path is active
 
-Hook for OAuth authentication.
+#### `useSignup()`
 
-Reads OAuth configuration from the provided config and provides
-helpers to build OAuth URLs and start a login (full-page or popup).
-Automatically handles OAuth callbacks by detecting `code` and `state`
-URL parameters and exchanging them for a session — and, when the callback is
-running inside a popup we opened, relaying the result to the opener instead.
+Hook for user registration with async state tracking.
 
 ```typescript
-function useOAuth(config?: {
-  baseURL?: string
-  oauthProviders?: string[]
-  oauthEndpoint?: string
-  loginEndpoint?: string
-  onSuccess?: () => void
-  onError?: (error: string) => void
-}): UseOAuthReturn
+function useSignup(): UseSignupReturn<T>
 ```
 
-- `config` — Optional OAuth configuration override.
-- `config.baseURL` — Base URL for the API server (e.g. "https://api.example.com").
-- `config.oauthProviders` — List of supported OAuth provider names (e.g. ["google", "github"]).
-- `config.oauthEndpoint` — Path prefix for OAuth routes (defaults to "/oauth").
-- `config.loginEndpoint` — Path for the OAuth login POST endpoint (defaults to "/users/log-in/oauth").
-- `config.onSuccess` — Callback after successful OAuth login.
-- `config.onError` — Callback on OAuth login failure.
+**Returns:** Signup state and action
+
+#### `useStorageProvider()`
+
+Hook to access the storage provider from context.
+
+```typescript
+function useStorageProvider(): StorageProvider
+```
+
+**Returns:** The storage provider from context
+
+#### `useStorageValue(key, options)`
+
+Hook to manage a single storage value with React state sync.
 
-**Returns:** OAuth helpers: providers, getOAuthUrl, redirect, and loginViaPopup.
+```typescript
+function useStorageValue(key: string, options?: UseStorageValueOptions<T>): UseStorageValueResult<T>
+```
 
-#### `useParams()`
+- `key` — Storage key
+- `options` — Hook options
 
-Hook to get route parameters.
+**Returns:** Storage value state (value, loading, error) and mutators (setValue, removeValue).
+
+#### `useStorage()`
+
+Hook for simple storage operations without React state sync.
 
 ```typescript
-function useParams(): T
+function useStorage(): {
+  get: <T>(key: string) => Promise<T | null>
+  set: <T>(key: string, value: T) => Promise<void>
+  remove: (key: string) => Promise<void>
+  clear: () => Promise<void>
+  keys: () => Promise<string[]>
+}
 ```
 
-**Returns:** The current route parameters
+**Returns:** Storage operation methods
 
-#### `usePasswordReset()`
+#### `useStateProvider()`
 
-Hook for password reset flow with async state tracking.
+Hook to access the state provider from context.
 
-Provides separate tracking for the request and confirm steps.
+The context comes from `<StateProvider provider={…}>` or from
+`<MoleculeProvider>` — which supplies the provider bonded under
+`@molecule/app-state` by default, so a scaffolded app needs no `state` prop.
+
+Only hooks that read the context call this; `useStore(store)` takes its store
+as an argument and works with no provider at all.
 
 ```typescript
-function usePasswordReset(): UsePasswordResetReturn
+function useStateProvider(): StateProvider
 ```
 
-**Returns:** Password reset state and actions
+**Returns:** The state provider from context
 
-#### `usePatch(url, options)`
+#### `useStore(store, options)`
 
-Hook for PATCH requests.
+Hook to subscribe to a store with optional selector and equality function.
+
+The store is the argument, so this hook needs NO `StateProvider`: it reads
+`store.getState()` and subscribes with `store.subscribe()`, and never touches
+the state context. A store minted outside the `state` bond — the direct
+`createStoreWithActions()` / `createStore()` a provider package exports — is
+therefore as valid here as one `@molecule/app-state`'s `createStore()` made.
 
 ```typescript
-function usePatch(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
+function useStore(store: Store<T>, options?: UseStoreOptions<T, S>): S
 ```
 
-- `url` — Request URL to send the PATCH request to.
-- `options` — HTTP request options including partial body data and callbacks.
-
-**Returns:** Request state (data, loading, error) and controls (execute, reset).
+- `store` — The store to subscribe to
+- `options` — Hook options (selector, equalityFn)
 
-#### `usePlatform()`
+**Returns:** The selected state
 
-Hook for platform detection.
+#### `useSetStore(store)`
 
-Uses module-level functions — platform is a singleton, not context-provided.
-Platform info is static and doesn't change at runtime, so this uses `useMemo`.
+Hook to get the store's setState function.
 
 ```typescript
-function usePlatform(): UsePlatformResult
+function useSetStore(store: Store<T>): (partial: Partial<T> | ((state: T) => Partial<T>)) => void
 ```
 
-**Returns:** Platform information and utility methods
+- `store` — The store to get setState from
 
-#### `usePost(url, options)`
+**Returns:** The setState function
 
-Hook for POST requests.
+#### `useStoreAction(store, action)`
+
+Hook to create a bound action for a store.
 
 ```typescript
-function usePost(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
+function useStoreAction(
+  store: Store<T>,
+  action: (setState: Store<T>['setState'], getState: Store<T>['getState']) => (...args: Args) => R,
+): (...args: Args) => R
 ```
 
-- `url` — Request URL to post to.
-- `options` — HTTP request options including body data and callbacks.
+- `store` — The store to bind to
+- `action` — The action function that receives setState and getState
 
-**Returns:** Request state (data, loading, error) and controls (execute, reset).
+**Returns:** A bound action function
 
-#### `usePreview()`
+#### `useThemeProvider()`
 
-Hook for live preview management.
+Hook to access the theme provider from context.
 
 ```typescript
-function usePreview(): UsePreviewResult
+function useThemeProvider(): ThemeProvider
 ```
 
-**Returns:** Preview state and controls: state (url, isLoading, device, error, isConnected), setUrl, refresh, setDevice, and openExternal.
+**Returns:** The theme provider from context
 
-#### `usePreviewProvider()`
+#### `useTheme()`
 
-Access the preview provider from context.
+Hook for theme state and actions.
 
 ```typescript
-function usePreviewProvider(): PreviewProvider
+function useTheme(): UseThemeResult
 ```
 
-**Returns:** The PreviewProvider instance from the nearest PreviewContext.
-
-#### `usePush(options)`
+**Returns:** Theme state and actions
 
-Hook for push notification state and actions.
+#### `useCurrentTheme()`
 
-Uses module-level `getProvider()` — push is a singleton, not context-provided.
+Hook to get just the current theme object.
 
 ```typescript
-function usePush(options?: UsePushOptions): UsePushResult
+function useCurrentTheme(): Theme
 ```
 
-- `options` — Hook options
-
-**Returns:** Push notification state and action methods
+**Returns:** The current theme
 
-#### `usePut(url, options)`
+#### `useThemeMode()`
 
-Hook for PUT requests.
+Hook to get just the theme mode (light/dark).
 
 ```typescript
-function usePut(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
+function useThemeMode(): 'light' | 'dark'
 ```
 
-- `url` — Request URL to send the PUT request to.
-- `options` — HTTP request options including body data and callbacks.
-
-**Returns:** Request state (data, loading, error) and controls (execute, reset).
+**Returns:** The current theme mode
 
-#### `useQuery()`
+#### `useThemeColors()`
 
-Hook to get query parameters.
+Hook to get theme colors.
 
 ```typescript
-function useQuery(): T
+function useThemeColors(): ThemeColors
 ```
 
-**Returns:** The current query parameters
+**Returns:** The current theme colors
 
-#### `useRootLogger()`
+#### `useI18nProvider()`
 
-Hook to get the root logger.
+Hook to access the i18n provider from context.
 
 ```typescript
-function useRootLogger(): Logger
+function useI18nProvider(): I18nProvider
 ```
 
-**Returns:** Root logger instance
+**Returns:** The i18n provider from context
 
-#### `useRouter()`
+#### `useTranslation()`
 
-Hook for routing state and actions.
+Hook for internationalization.
 
 ```typescript
-function useRouter(): UseRouterResult
+function useTranslation(): UseTranslationResult
 ```
 
-**Returns:** Router state and navigation methods
+**Returns:** Translation function and locale management
 
-#### `useRouterInstance()`
+#### `useT()`
 
-Hook to access the router from context.
+Hook to get just the translation function.
 
 ```typescript
-function useRouterInstance(): Router
+function useT(): (
+  key: string,
+  values?: InterpolationValues,
+  options?: { defaultValue?: string; count?: number },
+) => string
 ```
 
-**Returns:** The router from context
-
-#### `useSafeArea()`
+**Returns:** The translation function
 
-Returns the current safe area insets from `react-native-safe-area-context`.
+#### `useLocale()`
 
-Must be used within a `SafeAreaProvider`. Falls back to zero insets
-if the context is unavailable.
+Hook to get the current locale.
 
 ```typescript
-function useSafeArea(): SafeAreaInsets
+function useLocale(): string
 ```
 
-**Returns:** Safe area insets for the current device.
+**Returns:** The current locale code
 
-#### `useSetStore(store)`
+#### `useDirection()`
 
-Hook to get the store's setState function.
+Hook to get the text direction.
 
 ```typescript
-function useSetStore(store: Store<T>): (partial: Partial<T> | ((state: T) => Partial<T>)) => void
+function useDirection(): 'ltr' | 'rtl'
 ```
 
-- `store` — The store to get setState from
+**Returns:** The text direction ('ltr' or 'rtl')
 
-**Returns:** The setState function
+#### `useI18nError(error)`
 
-#### `useSignup()`
+Translates an error at render time so the displayed message updates automatically
+when the locale changes.
 
-Hook for user registration with async state tracking.
+**Always use this hook to display errors in React components** — accessing
+`error.message` directly bypasses re-translation and leaves stale text after a
+locale switch. If `error` is an `I18nError` (thrown via `throw new I18nError(key)`),
+its key is translated using the current locale. For plain `Error` instances,
+`error.message` is returned unchanged.
 
 ```typescript
-function useSignup(): UseSignupReturn<T>
+function useI18nError(error: Error | null | undefined): string | null
 ```
 
-**Returns:** Signup state and action
+- `error` — The error to translate, or `null`/`undefined`.
 
-#### `useStateProvider()`
+**Returns:** The translated error string, or `null` if no error.
 
-Hook to access the state provider from context.
+#### `useVerifyPaymentReturn(options)`
+
+Reads the payment id a provider put in the return URL and confirms the
+purchase server-side with `POST /users/:id/verify-payment/:provider`.
+
+**This is why a hosted checkout returns the buyer to the APP and not the
+API.** Session cookies are host-only on the app's origin, so a top-level
+redirect from the provider straight to an authenticated API callback on a
+different host arrives with NO credentials — it answers 401 and the paid plan
+is never granted. The request this hook makes is a same-origin call from a
+loaded app page, so the credentials apply. It waits for auth to hydrate
+first: after the redirect the page is a cold load, and the session is
+restored from the httpOnly cookie via `GET /users/me`.
+
+Verification is idempotent server-side (first-claim-wins on the transaction),
+and this hook additionally runs at most once per transaction id per page.
+Safe on pages that are also reached normally: with no id in the URL it stays
+`idle` and issues no request.
 
 ```typescript
-function useStateProvider(): StateProvider
+function useVerifyPaymentReturn(
+  options?: UseVerifyPaymentReturnOptions,
+): UseVerifyPaymentReturnResult
 ```
 
-**Returns:** The state provider from context
+- `options` — Provider fallback + lifecycle callbacks (see {@link UseVerifyPaymentReturnOptions}).
 
-#### `useStorage()`
+**Returns:** The verification state (see {@link UseVerifyPaymentReturnResult}).
 
-Hook for simple storage operations without React state sync.
+#### `useVersion()`
+
+Hook for version state and update actions.
+
+Uses module-level `getProvider()` — version is a singleton, not context-provided.
 
 ```typescript
-function useStorage(): {
-  get: <T>(key: string) => Promise<T | null>
-  set: <T>(key: string, value: T) => Promise<void>
-  remove: (key: string) => Promise<void>
-  clear: () => Promise<void>
-  keys: () => Promise<string[]>
-}
+function useVersion(): UseVersionResult
 ```
 
-**Returns:** Storage operation methods
+**Returns:** Version state and action methods
 
-#### `useStorageProvider()`
+#### `useWorkspaceProvider()`
 
-Hook to access the storage provider from context.
+Access the workspace provider from context.
 
 ```typescript
-function useStorageProvider(): StorageProvider
+function useWorkspaceProvider(): WorkspaceProvider
 ```
 
-**Returns:** The storage provider from context
+**Returns:** The result.
 
-#### `useStorageValue(key, options)`
+#### `useWorkspace()`
 
-Hook to manage a single storage value with React state sync.
+Hook for IDE workspace layout management.
 
 ```typescript
-function useStorageValue(key: string, options?: UseStorageValueOptions<T>): UseStorageValueResult<T>
+function useWorkspace(): UseWorkspaceResult
 ```
 
-- `key` — Storage key
-- `options` — Hook options
-
-**Returns:** Storage value state (value, loading, error) and mutators (setValue, removeValue).
+**Returns:** The workspace state and management methods.
 
-#### `useStore(store, options)`
+#### `StateProvider(props)`
 
-Hook to subscribe to a store with optional selector and equality function.
+Provider for state management.
 
 ```typescript
-function useStore(store: Store<T>, options?: UseStoreOptions<T, S>): S
+function StateProvider({
+  provider,
+  children,
+}: StateProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-- `store` — The store to subscribe to
-- `options` — Hook options (selector, equalityFn)
+- `props` — Component props (see {@link StateProviderProps}).
 
-**Returns:** The selected state
+**Returns:** The rendered state provider element.
 
-#### `useStoreAction(store, action)`
+#### `AuthProvider(props)`
 
-Hook to create a bound action for a store.
+Provider for authentication.
 
 ```typescript
-function useStoreAction(
-  store: Store<T>,
-  action: (setState: Store<T>['setState'], getState: Store<T>['getState']) => (...args: Args) => R,
-): (...args: Args) => R
+function AuthProvider({
+  client,
+  children,
+}: AuthProviderProps<T>): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-- `store` — The store to bind to
-- `action` — The action function that receives setState and getState
+- `props` — Component props (see {@link AuthProviderProps}).
 
-**Returns:** A bound action function
+**Returns:** The rendered auth provider element.
 
-#### `useT()`
+#### `ThemeProvider(props)`
 
-Hook to get just the translation function.
+Provider for theming.
 
 ```typescript
-function useT(): (
-  key: string,
-  values?: InterpolationValues,
-  options?: { defaultValue?: string; count?: number },
-) => string
+function ThemeProvider({
+  provider,
+  children,
+}: ThemeProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** The translation function
+- `props` — Component props (see {@link ThemeProviderProps}).
 
-#### `useTheme()`
+**Returns:** The rendered theme provider element.
 
-Hook for theme state and actions.
+#### `RouterProvider(props)`
+
+Provider for routing.
 
 ```typescript
-function useTheme(): UseThemeResult
+function RouterProvider({
+  router,
+  children,
+}: RouterProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** Theme state and actions
+- `props` — Component props (see {@link RouterProviderProps}).
 
-#### `useThemeColors()`
+**Returns:** The rendered router provider element.
 
-Hook to get theme colors.
+#### `I18nProvider(props)`
+
+Provider for internationalization.
 
 ```typescript
-function useThemeColors(): ThemeColors
+function I18nProvider({
+  provider,
+  children,
+}: I18nProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** The current theme colors
+- `props` — Component props (see {@link I18nProviderProps}).
 
-#### `useThemeMode()`
+**Returns:** The rendered i18n provider element.
 
-Hook to get just the theme mode (light/dark).
+#### `HttpProvider(props)`
+
+Provider for HTTP client.
 
 ```typescript
-function useThemeMode(): 'light' | 'dark'
+function HttpProvider({
+  client,
+  children,
+}: HttpProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** The current theme mode
+- `props` — Component props (see {@link HttpProviderProps}).
 
-#### `useThemeProvider()`
+**Returns:** The rendered HTTP provider element.
 
-Hook to access the theme provider from context.
+#### `StorageProvider(props)`
+
+Provider for storage.
 
 ```typescript
-function useThemeProvider(): ThemeProvider
+function StorageProvider({
+  provider,
+  children,
+}: StorageProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** The theme provider from context
+- `props` — Component props (see {@link StorageProviderProps}).
 
-#### `useTranslation()`
+**Returns:** The rendered storage provider element.
 
-Hook for internationalization.
+#### `LoggerProvider(props)`
+
+Provider for logging.
 
 ```typescript
-function useTranslation(): UseTranslationResult
+function LoggerProvider({
+  provider,
+  children,
+}: LoggerProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** Translation function and locale management
+- `props` — Component props (see {@link LoggerProviderProps}).
 
-#### `useUser()`
+**Returns:** The rendered logger provider element.
 
-Hook to get just the authenticated user.
+#### `ChatProvider(props)`
+
+Provider for AI chat.
 
 ```typescript
-function useUser(): T | null
+function ChatProvider({
+  provider,
+  children,
+}: ChatProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** The authenticated user or null
+- `props` — Component props (see {@link ChatProviderProps}).
 
-#### `useVersion()`
+**Returns:** The rendered chat provider element.
 
-Hook for version state and update actions.
+#### `WorkspaceProvider(props)`
 
-Uses module-level `getProvider()` — version is a singleton, not context-provided.
+Provider for IDE workspace.
 
 ```typescript
-function useVersion(): UseVersionResult
+function WorkspaceProvider({
+  provider,
+  children,
+}: WorkspaceProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** Version state and action methods
+- `props` — Component props (see {@link WorkspaceProviderProps}).
 
-#### `useWatch(form, name)`
+**Returns:** The rendered workspace provider element.
 
-Hook to watch a specific field value.
+#### `EditorProvider(props)`
+
+Provider for code editor.
 
 ```typescript
-function useWatch(form: FormController<T>, name: K): T[K]
+function EditorProvider({
+  provider,
+  children,
+}: EditorProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-- `form` — Form controller
-- `name` — Field name to watch
+- `props` — Component props (see {@link EditorProviderProps}).
 
-**Returns:** Current field value
+**Returns:** The rendered editor provider element.
 
-#### `useWorkspace()`
+#### `PreviewProvider(props)`
 
-Hook for IDE workspace layout management.
+Provider for live preview.
 
 ```typescript
-function useWorkspace(): UseWorkspaceResult
+function PreviewProvider({
+  provider,
+  children,
+}: PreviewProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** The workspace state and management methods.
-
-#### `useWorkspaceProvider()`
-
-Access the workspace provider from context.
+- `props` — Component props (see {@link PreviewProviderProps}).
 
-```typescript
-function useWorkspaceProvider(): WorkspaceProvider
-```
+**Returns:** The rendered preview provider element.
 
-**Returns:** The result.
+#### `MoleculeProvider(props)`
 
-#### `WorkspaceProvider(props)`
+Combined provider for all molecule services.
 
-Provider for IDE workspace.
+Provides a convenient way to wrap your app with all molecule providers at once.
+Only providers that are passed will be included — except `state`, which falls
+back to the state provider bonded under `@molecule/app-state` (set by
+`setupAllDefaultBonds()` or a state bond) so `useStore()` works without a
+`state` prop.
 
 ```typescript
-function WorkspaceProvider({
-  provider,
+function MoleculeProvider({
   children,
-}: WorkspaceProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+  state,
+  auth,
+  theme,
+  router,
+  i18n,
+  http,
+  storage,
+  logger,
+  chat,
+  workspace,
+  editor,
+  preview,
+}: MoleculeProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-- `props` — Component props (see {@link WorkspaceProviderProps}).
+- `props` — Component props (see {@link MoleculeProviderProps}) — each service is optional, and ONLY the services passed are provided to the tree.
 
-**Returns:** The rendered workspace provider element.
+**Returns:** The rendered combined provider element.
 
 ### Constants
 
-#### `AuthContext`
+#### `DEFAULT_AGENT_NAME`
 
-Context for authentication client.
+Neutral, product-agnostic agent name used when the host supplies none.
 
 ```typescript
-const AuthContext: Context<AuthClient<unknown> | null>
+const DEFAULT_AGENT_NAME: 'the assistant'
 ```
 
-#### `ChatContext`
+#### `DEFAULT_PRODUCT_NAME`
 
-Context for AI chat provider.
+Neutral, product-agnostic product/IDE name used when the host supplies none.
 
 ```typescript
-const ChatContext: Context<ChatProvider | null>
+const DEFAULT_PRODUCT_NAME: 'the IDE'
 ```
 
 #### `DEFAULT_AGENT_IDENTITY`
@@ -2516,36 +2855,36 @@ passes its own.
 const DEFAULT_AGENT_IDENTITY: AgentIdentity
 ```
 
-#### `DEFAULT_AGENT_NAME`
+#### `StateContext`
 
-Neutral, product-agnostic agent name used when the host supplies none.
+Context for state management provider.
 
 ```typescript
-const DEFAULT_AGENT_NAME: 'the assistant'
+const StateContext: Context<StateProvider | null>
 ```
 
-#### `DEFAULT_PRODUCT_NAME`
+#### `AuthContext`
 
-Neutral, product-agnostic product/IDE name used when the host supplies none.
+Context for authentication client.
 
 ```typescript
-const DEFAULT_PRODUCT_NAME: 'the IDE'
+const AuthContext: Context<AuthClient<unknown, Record<never, never>> | null>
 ```
 
-#### `EditorContext`
+#### `ThemeContext`
 
-Context for code editor provider.
+Context for theme provider.
 
 ```typescript
-const EditorContext: Context<EditorProvider | null>
+const ThemeContext: Context<ThemeProvider | null>
 ```
 
-#### `HttpContext`
+#### `RouterContext`
 
-Context for HTTP client.
+Context for router.
 
 ```typescript
-const HttpContext: Context<HttpClient | null>
+const RouterContext: Context<Router | null>
 ```
 
 #### `I18nContext`
@@ -2556,52 +2895,60 @@ Context for internationalization provider.
 const I18nContext: Context<I18nProvider | null>
 ```
 
-#### `LoggerContext`
+#### `HttpContext`
 
-Context for logger provider.
+Context for HTTP client.
 
 ```typescript
-const LoggerContext: Context<LoggerProvider | null>
+const HttpContext: Context<HttpClient | null>
 ```
 
-#### `PreviewContext`
+#### `StorageContext`
 
-Context for live preview provider.
+Context for storage provider.
 
 ```typescript
-const PreviewContext: Context<PreviewProvider | null>
+const StorageContext: Context<StorageProvider | null>
 ```
 
-#### `RouterContext`
+#### `LoggerContext`
 
-Context for router.
+Context for logger provider.
 
 ```typescript
-const RouterContext: Context<Router | null>
+const LoggerContext: Context<LoggerProvider | null>
 ```
 
-#### `StateContext`
+#### `ChatContext`
 
-Context for state management provider.
+Context for AI chat provider.
 
 ```typescript
-const StateContext: Context<StateProvider | null>
+const ChatContext: Context<ChatProvider | null>
 ```
 
-#### `StorageContext`
+#### `WorkspaceContext`
 
-Context for storage provider.
+Context for IDE workspace provider.
 
 ```typescript
-const StorageContext: Context<StorageProvider | null>
+const WorkspaceContext: Context<WorkspaceProvider | null>
 ```
 
-#### `ThemeContext`
+#### `EditorContext`
 
-Context for theme provider.
+Context for code editor provider.
 
 ```typescript
-const ThemeContext: Context<ThemeProvider | null>
+const EditorContext: Context<EditorProvider | null>
+```
+
+#### `PreviewContext`
+
+Context for live preview provider.
+
+```typescript
+const PreviewContext: Context<PreviewProvider | null>
 ```
 
 #### `useAsyncState`
@@ -2612,6 +2959,10 @@ Hook like useState but accepts Promises and supports partial state extension.
 const useAsyncState: <T>(initialState: T) => [T, AsyncSetState<T>, AsyncExtendState<T>]
 ```
 
+- `initialState` — Initial state value
+
+**Returns:** Tuple of [state, asyncSetState, asyncExtendState]
+
 #### `usePromise`
 
 Hook that wraps an async function with state tracking.
@@ -2625,13 +2976,9 @@ const usePromise: <T extends (...args: any[]) => Promise<any>>(
 ]
 ```
 
-#### `WorkspaceContext`
-
-Context for IDE workspace provider.
+- `asyncFn` — The async function to wrap
 
-```typescript
-const WorkspaceContext: Context<WorkspaceProvider | null>
-```
+**Returns:** Tuple of [state, wrappedFunction]
 
 ## Injection Notes