@molecule/app-react 1.6.1 → 1.6.3

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-09-22T18:05:32.274Z
+Generated: 2026-10-16T00:51:41.781Z
 -->
 
 # @molecule/app-react
@@ -80,19 +80,32 @@ npm install -D @types/react
 
 ### Interfaces
 
-#### `AgentIdentity`
+#### `AuthState`
 
-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.
+Reactive authentication state snapshot (initialized, authenticated, user, loading, and error).
 
 ```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
+interface AuthState<T = UserProfile> {
+  /**
+   * Whether auth state has been initialized.
+   */
+  initialized: boolean
+  /**
+   * Whether the user is authenticated.
+   */
+  authenticated: boolean
+  /**
+   * Current user (if authenticated).
+   */
+  user: T | null
+  /**
+   * Whether an auth operation is in progress.
+   */
+  loading: boolean
+  /**
+   * Last auth error (if any).
+   */
+  error: string | null
 }
 ```
 
@@ -198,65 +211,6 @@ interface AuthClient<T = UserProfile> {
 }
 ```
 
-#### `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> {
-  /**
-   * Whether auth state has been initialized.
-   */
-  initialized: boolean
-  /**
-   * Whether the user is authenticated.
-   */
-  authenticated: boolean
-  /**
-   * Current user (if authenticated).
-   */
-  user: T | null
-  /**
-   * Whether an auth operation is in progress.
-   */
-  loading: boolean
-  /**
-   * Last auth error (if any).
-   */
-  error: string | null
-}
-```
-
-#### `ChatProviderProps`
-
-Props for the ChatProvider React component.
-
-```typescript
-interface ChatProviderProps extends ProviderProps {
-  provider: ChatProvider
-}
-```
-
-#### `EditorProviderProps`
-
-Props for editor provider component.
-
-```typescript
-interface EditorProviderProps extends ProviderProps {
-  provider: EditorProvider
-}
-```
-
 #### `FormController`
 
 Form controller interface.
@@ -464,77 +418,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.
@@ -661,84 +544,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
-  /**
-   * 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
+interface StoreConfig<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.
+   * Initial state value.
    */
-  askUserAnswer?: boolean
+  initialState: T
   /**
-   * 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 name for debugging.
    */
-  userInitiated?: boolean
+  name?: string
   /**
-   * 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.
+   * Optional middleware functions.
    */
-  sideChannel?: 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>[]
 }
 ```
 
@@ -770,30 +593,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 {
@@ -810,14 +612,19 @@ interface Theme {
 }
 ```
 
-#### `ThemeProviderProps`
+#### `AgentIdentity`
 
-Props for theme provider component.
+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 ThemeProviderProps extends ProviderProps {
-  provider: ThemeProvider
-  initialTheme?: string
+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
 }
 ```
 
@@ -843,37 +650,6 @@ interface UseAIModelsResult {
 }
 ```
 
-#### `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> {
-  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
-}
-```
-
 #### `UseChangePasswordReturn`
 
 Return type for useChangePassword hook.
@@ -887,182 +663,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
-  /**
-   * 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
-}
-```
-
-#### `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>
-}
-```
-
 #### `UseDeviceResult`
 
 Hook return type.
@@ -1081,30 +681,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.
@@ -1145,24 +721,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
 }
 ```
 
@@ -1177,15 +744,24 @@ interface UseHttpResult<T> extends UseHttpState<T> {
 }
 ```
 
-#### `UseHttpState`
+#### `UseHttpOptions`
 
-State for async HTTP operations.
+Options for useHttp hook.
 
 ```typescript
-interface UseHttpState<T> {
-  data: T | null
-  loading: boolean
-  error: Error | null
+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
 }
 ```
 
@@ -1256,32 +832,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.
@@ -1296,19 +846,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.
@@ -1329,20 +866,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
 }
 ```
 
@@ -1391,47 +924,6 @@ interface UseStorageValueResult<T> {
 }
 ```
 
-#### `UseStoreOptions`
-
-Hook options for useStore.
-
-```typescript
-interface UseStoreOptions<T, S> {
-  selector?: (state: T) => S
-  equalityFn?: (a: S, b: S) => boolean
-}
-```
-
-#### `UseThemeResult`
-
-Hook result for useTheme.
-
-```typescript
-interface UseThemeResult {
-  theme: Theme
-  themeName: string
-  setTheme: (name: string) => void
-  toggleTheme: () => void
-  mode: 'light' | 'dark'
-}
-```
-
-#### `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'
-}
-```
-
 #### `UseVerifyPaymentReturnOptions`
 
 Options for {@link useVerifyPaymentReturn}.
@@ -1469,45 +961,520 @@ State of the post-checkout verification.
 ```typescript
 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`.
+   * `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
+}
+```
+
+#### `UseVersionResult`
+
+Hook return type.
+
+```typescript
+interface UseVersionResult {
+  state: VersionState
+  isUpdateAvailable: boolean
+  isChecking: boolean
+  isServiceWorkerWaiting: boolean
+  newVersion: string | undefined
+  checkForUpdates: () => Promise<boolean>
+  applyUpdate: (options?: { force?: boolean }) => void
+  dismissUpdate: () => void
+  startPeriodicChecks: (options?: UpdateCheckOptions) => void
+  stopPeriodicChecks: () => void
+}
+```
+
+#### `ProviderProps`
+
+Props for provider components.
+
+```typescript
+interface ProviderProps {
+  children: ReactNode
+}
+```
+
+#### `StateProviderProps`
+
+Props for state provider component.
+
+```typescript
+interface StateProviderProps extends ProviderProps {
+  provider: StateProvider
+}
+```
+
+#### `AuthProviderProps`
+
+Props for auth provider component.
+
+```typescript
+interface AuthProviderProps<T = unknown> extends ProviderProps {
+  client: AuthClient<T>
+}
+```
+
+#### `ThemeProviderProps`
+
+Props for theme provider component.
+
+```typescript
+interface ThemeProviderProps extends ProviderProps {
+  provider: ThemeProvider
+  initialTheme?: string
+}
+```
+
+#### `RouterProviderProps`
+
+Props for router provider component.
+
+```typescript
+interface RouterProviderProps extends ProviderProps {
+  router: Router
+}
+```
+
+#### `I18nProviderProps`
+
+Props for i18n provider component.
+
+```typescript
+interface I18nProviderProps extends ProviderProps {
+  provider: I18nProvider
+}
+```
+
+#### `HttpProviderProps`
+
+Props for http provider component.
+
+```typescript
+interface HttpProviderProps extends ProviderProps {
+  client: HttpClient
+}
+```
+
+#### `StorageProviderProps`
+
+Props for storage provider component.
+
+```typescript
+interface StorageProviderProps extends ProviderProps {
+  provider: StorageProvider
+}
+```
+
+#### `LoggerProviderProps`
+
+Props for logger provider component.
+
+```typescript
+interface LoggerProviderProps extends ProviderProps {
+  provider: LoggerProvider
+}
+```
+
+#### `ChatProviderProps`
+
+Props for the ChatProvider React component.
+
+```typescript
+interface ChatProviderProps extends ProviderProps {
+  provider: ChatProvider
+}
+```
+
+#### `WorkspaceProviderProps`
+
+Props for workspace provider component.
+
+```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> {
+  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
+}
+```
+
+#### `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.
    */
-  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
-}
-```
-
-#### `UseVersionResult`
-
-Hook return type.
-
-```typescript
-interface UseVersionResult {
-  state: VersionState
-  isUpdateAvailable: boolean
-  isChecking: boolean
-  isServiceWorkerWaiting: boolean
-  newVersion: string | undefined
-  checkForUpdates: () => Promise<boolean>
-  applyUpdate: (options?: { force?: boolean }) => void
-  dismissUpdate: () => void
-  startPeriodicChecks: (options?: UpdateCheckOptions) => void
-  stopPeriodicChecks: () => void
+  reconcileHistory: () => Promise<void>
 }
 ```
 
@@ -1527,28 +1494,58 @@ interface UseWorkspaceResult {
 }
 ```
 
-#### `WorkspaceProviderProps`
+#### `UseEditorResult`
 
-Props for workspace provider component.
+Hook result for useEditor.
 
 ```typescript
-interface WorkspaceProviderProps extends ProviderProps {
-  provider: WorkspaceProvider
+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
 }
 ```
 
-### Types
-
-#### `AsyncExtendState`
+#### `UsePreviewResult`
 
-Async-capable extendState function for partial updates.
+Hook result for usePreview.
 
 ```typescript
-type AsyncExtendState<T> = (
-  partial: Partial<T> | ((prev: T) => Partial<T>) | Promise<Partial<T> | ((prev: T) => Partial<T>)>,
-) => void
+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.
@@ -1557,6 +1554,18 @@ Async-capable setState function.
 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.
@@ -1577,194 +1586,153 @@ type VerifyPaymentReturnStatus = 'idle' | 'verifying' | 'verified' | 'failed'
 
 ### Functions
 
-#### `AuthProvider(props)`
+#### `resetAIModelsCache()`
 
-Provider for authentication.
+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 AuthProvider({
-  client,
-  children,
-}: AuthProviderProps<T>): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function resetAIModelsCache(): void
 ```
 
-- `props` — Component props (see {@link AuthProviderProps}).
-
-**Returns:** The rendered auth provider element.
-
-#### `ChatProvider(props)`
+#### `useAIModels(projectId)`
 
-Provider for AI chat.
+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 ChatProvider({
-  provider,
-  children,
-}: ChatProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function useAIModels(projectId?: string): UseAIModelsResult
 ```
 
-- `props` — Component props (see {@link ChatProviderProps}).
-
-**Returns:** The rendered chat provider element.
+- `projectId` — Optional project scope: includes that project's custom ("bring your own AI") models on servers that support them.
 
-#### `convergeHistory(prev, history)`
+**Returns:** Models, free-tier model, loading flag, and error.
 
-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).
+#### `useAsyncState(initialState)`
 
-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.
+Hook like useState but accepts Promises and supports partial state extension.
 
 ```typescript
-function convergeHistory(prev: ChatMessage[], history: ChatMessage[]): ChatMessage[]
+function useAsyncState(initialState: T): [T, AsyncSetState<T>, AsyncExtendState<T>]
 ```
 
-- `prev` — The store's current messages.
-- `history` — The messages from the server's history endpoint.
+- `initialState` — Initial state value
 
-**Returns:** The converged message list.
+**Returns:** Tuple of [state, asyncSetState, asyncExtendState]
 
-#### `EditorProvider(props)`
+#### `useAuthClient()`
 
-Provider for code editor.
+Hook to access the auth client from context.
 
 ```typescript
-function EditorProvider({
-  provider,
-  children,
-}: EditorProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function useAuthClient(): AuthClient<T>
 ```
 
-- `props` — Component props (see {@link EditorProviderProps}).
-
-**Returns:** The rendered editor provider element.
+**Returns:** The auth client from context
 
-#### `HttpProvider(props)`
+#### `useAuth(options)`
 
-Provider for HTTP client.
+Hook for authentication state and actions.
 
 ```typescript
-function HttpProvider({
-  client,
-  children,
-}: HttpProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function useAuth(options?: UseAuthOptions): UseAuthResult<T>
 ```
 
-- `props` — Component props (see {@link HttpProviderProps}).
+- `options` — Hook options
 
-**Returns:** The rendered HTTP provider element.
+**Returns:** Auth state and action methods
 
-#### `I18nProvider(props)`
+#### `useUser()`
 
-Provider for internationalization.
+Hook to get just the authenticated user.
 
 ```typescript
-function I18nProvider({
-  provider,
-  children,
-}: I18nProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function useUser(): T | null
 ```
 
-- `props` — Component props (see {@link I18nProviderProps}).
-
-**Returns:** The rendered i18n provider element.
+**Returns:** The authenticated user or null
 
-#### `localOnlyMessages(prev, history)`
+#### `useIsAuthenticated()`
 
-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).
+Hook to check if user is authenticated.
 
 ```typescript
-function localOnlyMessages(prev: ChatMessage[], history: ChatMessage[]): ChatMessage[]
+function useIsAuthenticated(): boolean
 ```
 
-- `prev` — The store's current messages.
-- `history` — The server's history.
+**Returns:** Whether the user is authenticated
 
-**Returns:** The local-only messages to keep after the merged history.
+#### `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
@@ -1775,186 +1743,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}).
+- `options` — Chat configuration including endpoint URL, project ID, and whether to load history on mount.
 
-**Returns:** The rendered state provider element.
+**Returns:** Chat state and controls: messages, isLoading, error, sendMessage, abort, and clearHistory.
 
-#### `StorageProvider(props)`
+#### `useDevice()`
 
-Provider for storage.
+Hook for device information.
+
+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 StorageProvider({
-  provider,
-  children,
-}: StorageProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function useDevice(): UseDeviceResult
 ```
 
-- `props` — Component props (see {@link StorageProviderProps}).
-
-**Returns:** The rendered storage provider element.
+**Returns:** Device information and utility methods
 
-#### `ThemeProvider(props)`
+#### `useEditorProvider()`
 
-Provider for theming.
+Access the editor provider from context.
 
 ```typescript
-function ThemeProvider({
-  provider,
-  children,
-}: ThemeProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function useEditorProvider(): EditorProvider
 ```
 
-- `props` — Component props (see {@link ThemeProviderProps}).
-
-**Returns:** The rendered theme provider element.
+**Returns:** The EditorProvider instance from the nearest EditorContext.
 
-#### `useAIModels(projectId)`
+#### `useEditor()`
 
-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.
+Hook for code editor management.
 
 ```typescript
-function useAIModels(projectId?: string): UseAIModelsResult
+function useEditor(): UseEditorResult
 ```
 
-- `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.
+**Returns:** Editor state and controls: tabs, activeFile, openFile, closeFile, getContent, setContent, setActiveTab, mount, dispose, and focus.
 
-#### `useAsyncState(initialState)`
+#### `useForm(options)`
 
-Hook like useState but accepts Promises and supports partial state extension.
+Hook for form state management.
 
 ```typescript
-function useAsyncState(initialState: T): [T, AsyncSetState<T>, AsyncExtendState<T>]
+function useForm(options: UseFormOptions<T>): UseFormResult<T>
 ```
 
-- `initialState` — Initial state value
+- `options` — Form options including createForm from a forms provider
 
-**Returns:** Tuple of [state, asyncSetState, asyncExtendState]
+**Returns:** Form state and methods
 
-#### `useAuth(options)`
+#### `useWatch(form, name)`
 
-Hook for authentication state and actions.
+Hook to watch a specific field value.
 
 ```typescript
-function useAuth(options?: UseAuthOptions): UseAuthResult<T>
+function useWatch(form: FormController<T>, name: K): T[K]
 ```
 
-- `options` — Hook options
+- `form` — Form controller
+- `name` — Field name to watch
 
-**Returns:** Auth state and action methods
+**Returns:** Current field value
 
-#### `useAuthClient()`
+#### `useFieldState(form, name)`
 
-Hook to access the auth client from context.
+Hook to get field-level state.
 
 ```typescript
-function useAuthClient(): AuthClient<T>
+function useFieldState(form: FormController<T>, name: keyof T): FieldState<T[keyof T]>
 ```
 
-**Returns:** The auth client from context
+- `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)`
 
@@ -1969,219 +1932,218 @@ 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.
 
 ```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.
+- `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:** Request state (data, loading, error) and controls (execute, reset).
+**Returns:** OAuth helpers: providers, getOAuthUrl, redirect, and loginViaPopup.
 
-#### `useHttp(method, url, options)`
+#### `usePasswordReset()`
 
-Hook for making HTTP requests with state management.
+Hook for password reset flow with async state tracking.
+
+Provides separate tracking for the request and confirm steps.
 
 ```typescript
-function useHttp(
-  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
-  url: string,
-  options?: UseHttpOptions<T>,
-): UseHttpResult<T>
+function usePasswordReset(): UsePasswordResetReturn
 ```
 
-- `method` — HTTP method
-- `url` — Request URL
-- `options` — Request options
+**Returns:** Password reset state and actions
 
-**Returns:** Request state and execute function
+#### `usePlatform()`
 
-#### `useHttpClient()`
+Hook for platform detection.
 
-Hook to access the HTTP client from context.
+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 useHttpClient(): HttpClient
+function usePlatform(): UsePlatformResult
 ```
 
-**Returns:** The HTTP client from context
-
-#### `useI18nError(error)`
+**Returns:** Platform information and utility methods
 
-Translates an error at render time so the displayed message updates automatically
-when the locale changes.
+#### `usePreviewProvider()`
 
-**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.
+Access the preview provider from context.
 
 ```typescript
-function useI18nError(error: Error | null | undefined): string | null
+function usePreviewProvider(): PreviewProvider
 ```
 
-- `error` — The error to translate, or `null`/`undefined`.
-
-**Returns:** The translated error string, or `null` if no error.
+**Returns:** The PreviewProvider instance from the nearest PreviewContext.
 
-#### `useI18nProvider()`
+#### `usePreview()`
 
-Hook to access the i18n provider from context.
+Hook for live preview management.
 
 ```typescript
-function useI18nProvider(): I18nProvider
+function usePreview(): UsePreviewResult
 ```
 
-**Returns:** The i18n provider from context
+**Returns:** Preview state and controls: state (url, isLoading, device, error, isConnected), setUrl, refresh, setDevice, and openExternal.
 
-#### `useIsActive(path, exact)`
+#### `usePromise(asyncFn)`
 
-Hook to check if a path is active.
+Hook that wraps an async function with state tracking.
 
 ```typescript
-function useIsActive(path: string, exact?: boolean): boolean
+function usePromise(
+  asyncFn: T,
+): [
+  UsePromiseState<Awaited<ReturnType<T>>>,
+  (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>,
+]
 ```
 
-- `path` — The path to check
-- `exact` — Whether to match exactly (default: false)
+- `asyncFn` — The async function to wrap
 
-**Returns:** Whether the path is active
+**Returns:** Tuple of [state, wrappedFunction]
 
-#### `useIsAuthenticated()`
+#### `usePush(options)`
 
-Hook to check if user is authenticated.
+Hook for push notification state and actions.
+
+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
 
-#### `useLocale()`
+**Returns:** Push notification state and action methods
 
-Hook to get the current locale.
+#### `useRouterInstance()`
+
+Hook to access the router from context.
 
 ```typescript
-function useLocale(): string
+function useRouterInstance(): Router
 ```
 
-**Returns:** The current locale code
+**Returns:** The router from context
 
-#### `useLocation()`
+#### `useRouter()`
 
-Hook to get the current location.
+Hook for routing state and actions.
 
 ```typescript
-function useLocation(): RouteLocation
+function useRouter(): UseRouterResult
 ```
 
-**Returns:** The current route location
+**Returns:** Router state and navigation methods
 
-#### `useLogger(name, config)`
+#### `useLocation()`
 
-Hook to get a logger instance.
+Hook to get the current location.
 
 ```typescript
-function useLogger(name: string, config?: Partial<LoggerConfig>): Logger
+function useLocation(): RouteLocation
 ```
 
-- `name` — Logger name (usually component or module name)
-- `config` — Optional logger configuration
-
-**Returns:** Logger instance
+**Returns:** The current route location
 
-#### `useLoggerProvider()`
+#### `useParams()`
 
-Hook to access the logger provider from context.
+Hook to get route parameters.
 
 ```typescript
-function useLoggerProvider(): LoggerProvider
+function useParams(): T
 ```
 
-**Returns:** The logger provider from context
+**Returns:** The current route parameters
 
-#### `useLogin()`
+#### `useQuery()`
 
-Hook for login with async state tracking.
+Hook to get query parameters.
 
 ```typescript
-function useLogin(): UseLoginReturn<T>
+function useQuery(): T
 ```
 
-**Returns:** Login state and action
+**Returns:** The current query parameters
 
 #### `useNavigate()`
 
@@ -2193,481 +2155,528 @@ function useNavigate(): (path: string, options?: NavigateOptions) => void
 
 **Returns:** The navigate function
 
-#### `useOAuth(config)`
-
-Hook for OAuth authentication.
+#### `useIsActive(path, exact)`
 
-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 to check if a path is active.
 
 ```typescript
-function useOAuth(config?: {
-  baseURL?: string
-  oauthProviders?: string[]
-  oauthEndpoint?: string
-  loginEndpoint?: string
-  onSuccess?: () => void
-  onError?: (error: string) => void
-}): UseOAuthReturn
+function useIsActive(path: string, exact?: boolean): boolean
 ```
 
-- `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.
+- `path` — The path to check
+- `exact` — Whether to match exactly (default: false)
 
-**Returns:** OAuth helpers: providers, getOAuthUrl, redirect, and loginViaPopup.
+**Returns:** Whether the path is active
 
-#### `useParams()`
+#### `useSignup()`
 
-Hook to get route parameters.
+Hook for user registration with async state tracking.
 
 ```typescript
-function useParams(): T
+function useSignup(): UseSignupReturn<T>
 ```
 
-**Returns:** The current route parameters
-
-#### `usePasswordReset()`
+**Returns:** Signup state and action
 
-Hook for password reset flow with async state tracking.
+#### `useStorageProvider()`
 
-Provides separate tracking for the request and confirm steps.
+Hook to access the storage provider from context.
 
 ```typescript
-function usePasswordReset(): UsePasswordResetReturn
+function useStorageProvider(): StorageProvider
 ```
 
-**Returns:** Password reset state and actions
+**Returns:** The storage provider from context
 
-#### `usePatch(url, options)`
+#### `useStorageValue(key, options)`
 
-Hook for PATCH requests.
+Hook to manage a single storage value with React state sync.
 
 ```typescript
-function usePatch(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
+function useStorageValue(key: string, options?: UseStorageValueOptions<T>): UseStorageValueResult<T>
 ```
 
-- `url` — Request URL to send the PATCH request to.
-- `options` — HTTP request options including partial body data and callbacks.
+- `key` — Storage key
+- `options` — Hook options
 
-**Returns:** Request state (data, loading, error) and controls (execute, reset).
+**Returns:** Storage value state (value, loading, error) and mutators (setValue, removeValue).
 
-#### `usePlatform()`
+#### `useStorage()`
 
-Hook for platform detection.
+Hook for simple storage operations without React state sync.
 
-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 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:** Storage operation methods
+
+#### `useStateProvider()`
+
+Hook to access the state provider from context.
 
 ```typescript
-function usePlatform(): UsePlatformResult
+function useStateProvider(): StateProvider
 ```
 
-**Returns:** Platform information and utility methods
+**Returns:** The state provider from context
 
-#### `usePost(url, options)`
+#### `useStore(store, options)`
 
-Hook for POST requests.
+Hook to subscribe to a store with optional selector and equality function.
 
 ```typescript
-function usePost(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
+function useStore(store: Store<T>, options?: UseStoreOptions<T, S>): S
 ```
 
-- `url` — Request URL to post to.
-- `options` — HTTP request options including body data and callbacks.
+- `store` — The store to subscribe to
+- `options` — Hook options (selector, equalityFn)
 
-**Returns:** Request state (data, loading, error) and controls (execute, reset).
+**Returns:** The selected state
 
-#### `usePreview()`
+#### `useSetStore(store)`
 
-Hook for live preview management.
+Hook to get the store's setState function.
 
 ```typescript
-function usePreview(): UsePreviewResult
+function useSetStore(store: Store<T>): (partial: Partial<T> | ((state: T) => Partial<T>)) => void
 ```
 
-**Returns:** Preview state and controls: state (url, isLoading, device, error, isConnected), setUrl, refresh, setDevice, and openExternal.
+- `store` — The store to get setState from
 
-#### `usePreviewProvider()`
+**Returns:** The setState function
 
-Access the preview provider from context.
+#### `useStoreAction(store, action)`
+
+Hook to create a bound action for a store.
 
 ```typescript
-function usePreviewProvider(): PreviewProvider
+function useStoreAction(
+  store: Store<T>,
+  action: (setState: Store<T>['setState'], getState: Store<T>['getState']) => (...args: Args) => R,
+): (...args: Args) => R
 ```
 
-**Returns:** The PreviewProvider instance from the nearest PreviewContext.
+- `store` — The store to bind to
+- `action` — The action function that receives setState and getState
 
-#### `usePromise(asyncFn)`
+**Returns:** A bound action function
 
-Hook that wraps an async function with state tracking.
+#### `useThemeProvider()`
+
+Hook to access the theme provider from context.
 
 ```typescript
-function usePromise(
-  asyncFn: T,
-): [
-  UsePromiseState<Awaited<ReturnType<T>>>,
-  (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>,
-]
+function useThemeProvider(): ThemeProvider
 ```
 
-- `asyncFn` — The async function to wrap
-
-**Returns:** Tuple of [state, wrappedFunction]
-
-#### `usePush(options)`
+**Returns:** The theme provider from context
 
-Hook for push notification state and actions.
+#### `useTheme()`
 
-Uses module-level `getProvider()` — push is a singleton, not context-provided.
+Hook for theme state and actions.
 
 ```typescript
-function usePush(options?: UsePushOptions): UsePushResult
+function useTheme(): UseThemeResult
 ```
 
-- `options` — Hook options
-
-**Returns:** Push notification state and action methods
+**Returns:** Theme state and actions
 
-#### `usePut(url, options)`
+#### `useCurrentTheme()`
 
-Hook for PUT requests.
+Hook to get just the current theme object.
 
 ```typescript
-function usePut(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
+function useCurrentTheme(): Theme
 ```
 
-- `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
 
-#### `useQuery()`
+#### `useThemeMode()`
 
-Hook to get query parameters.
+Hook to get just the theme mode (light/dark).
 
 ```typescript
-function useQuery(): T
+function useThemeMode(): 'light' | 'dark'
 ```
 
-**Returns:** The current query parameters
+**Returns:** The current theme mode
 
-#### `useRootLogger()`
+#### `useThemeColors()`
 
-Hook to get the root logger.
+Hook to get theme colors.
 
 ```typescript
-function useRootLogger(): Logger
+function useThemeColors(): ThemeColors
 ```
 
-**Returns:** Root logger instance
+**Returns:** The current theme colors
 
-#### `useRouter()`
+#### `useI18nProvider()`
 
-Hook for routing state and actions.
+Hook to access the i18n provider from context.
 
 ```typescript
-function useRouter(): UseRouterResult
+function useI18nProvider(): I18nProvider
 ```
 
-**Returns:** Router state and navigation methods
+**Returns:** The i18n provider from context
 
-#### `useRouterInstance()`
+#### `useTranslation()`
 
-Hook to access the router from context.
+Hook for internationalization.
 
 ```typescript
-function useRouterInstance(): Router
+function useTranslation(): UseTranslationResult
 ```
 
-**Returns:** The router from context
+**Returns:** Translation function and locale management
 
-#### `useSetStore(store)`
+#### `useT()`
 
-Hook to get the store's setState function.
+Hook to get just the translation function.
 
 ```typescript
-function useSetStore(store: Store<T>): (partial: Partial<T> | ((state: T) => Partial<T>)) => void
+function useT(): (
+  key: string,
+  values?: InterpolationValues,
+  options?: { defaultValue?: string; count?: number },
+) => string
 ```
 
-- `store` — The store to get setState from
-
-**Returns:** The setState function
+**Returns:** The translation function
 
-#### `useSignup()`
+#### `useLocale()`
 
-Hook for user registration with async state tracking.
+Hook to get the current locale.
 
 ```typescript
-function useSignup(): UseSignupReturn<T>
+function useLocale(): string
 ```
 
-**Returns:** Signup state and action
+**Returns:** The current locale code
 
-#### `useStateProvider()`
+#### `useDirection()`
 
-Hook to access the state provider from context.
+Hook to get the text direction.
 
 ```typescript
-function useStateProvider(): StateProvider
+function useDirection(): 'ltr' | 'rtl'
 ```
 
-**Returns:** The state provider from context
+**Returns:** The text direction ('ltr' or 'rtl')
 
-#### `useStorage()`
+#### `useI18nError(error)`
 
-Hook for simple storage operations without React state sync.
+Translates an error at render time so the displayed message updates automatically
+when the locale changes.
+
+**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 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 useI18nError(error: Error | null | undefined): string | null
 ```
 
-**Returns:** Storage operation methods
+- `error` — The error to translate, or `null`/`undefined`.
 
-#### `useStorageProvider()`
+**Returns:** The translated error string, or `null` if no error.
 
-Hook to access the storage 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 useStorageProvider(): StorageProvider
+function useVerifyPaymentReturn(
+  options?: UseVerifyPaymentReturnOptions,
+): UseVerifyPaymentReturnResult
 ```
 
-**Returns:** The storage provider from context
+- `options` — Provider fallback + lifecycle callbacks (see {@link UseVerifyPaymentReturnOptions}).
 
-#### `useStorageValue(key, options)`
+**Returns:** The verification state (see {@link UseVerifyPaymentReturnResult}).
 
-Hook to manage a single storage value with React state sync.
+#### `useVersion()`
+
+Hook for version state and update actions.
+
+Uses module-level `getProvider()` — version is a singleton, not context-provided.
 
 ```typescript
-function useStorageValue(key: string, options?: UseStorageValueOptions<T>): UseStorageValueResult<T>
+function useVersion(): UseVersionResult
 ```
 
-- `key` — Storage key
-- `options` — Hook options
-
-**Returns:** Storage value state (value, loading, error) and mutators (setValue, removeValue).
+**Returns:** Version state and action methods
 
-#### `useStore(store, options)`
+#### `useWorkspaceProvider()`
 
-Hook to subscribe to a store with optional selector and equality function.
+Access the workspace provider from context.
 
 ```typescript
-function useStore(store: Store<T>, options?: UseStoreOptions<T, S>): S
+function useWorkspaceProvider(): WorkspaceProvider
 ```
 
-- `store` — The store to subscribe to
-- `options` — Hook options (selector, equalityFn)
-
-**Returns:** The selected state
+**Returns:** The result.
 
-#### `useStoreAction(store, action)`
+#### `useWorkspace()`
 
-Hook to create a bound action for a store.
+Hook for IDE workspace layout management.
 
 ```typescript
-function useStoreAction(
-  store: Store<T>,
-  action: (setState: Store<T>['setState'], getState: Store<T>['getState']) => (...args: Args) => R,
-): (...args: Args) => R
+function useWorkspace(): UseWorkspaceResult
 ```
 
-- `store` — The store to bind to
-- `action` — The action function that receives setState and getState
-
-**Returns:** A bound action function
+**Returns:** The workspace state and management methods.
 
-#### `useT()`
+#### `StateProvider(props)`
 
-Hook to get just the translation function.
+Provider for state management.
 
 ```typescript
-function useT(): (
-  key: string,
-  values?: InterpolationValues,
-  options?: { defaultValue?: string; count?: number },
-) => string
+function StateProvider({
+  provider,
+  children,
+}: StateProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** The translation function
+- `props` — Component props (see {@link StateProviderProps}).
 
-#### `useTheme()`
+**Returns:** The rendered state provider element.
 
-Hook for theme state and actions.
+#### `AuthProvider(props)`
+
+Provider for authentication.
 
 ```typescript
-function useTheme(): UseThemeResult
+function AuthProvider({
+  client,
+  children,
+}: AuthProviderProps<T>): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** Theme state and actions
+- `props` — Component props (see {@link AuthProviderProps}).
+
+**Returns:** The rendered auth provider element.
 
-#### `useThemeColors()`
+#### `ThemeProvider(props)`
 
-Hook to get theme colors.
+Provider for theming.
 
 ```typescript
-function useThemeColors(): ThemeColors
+function ThemeProvider({
+  provider,
+  children,
+}: ThemeProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** The current theme colors
+- `props` — Component props (see {@link ThemeProviderProps}).
 
-#### `useThemeMode()`
+**Returns:** The rendered theme provider element.
 
-Hook to get just the theme mode (light/dark).
+#### `RouterProvider(props)`
+
+Provider for routing.
 
 ```typescript
-function useThemeMode(): 'light' | 'dark'
+function RouterProvider({
+  router,
+  children,
+}: RouterProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** The current theme mode
+- `props` — Component props (see {@link RouterProviderProps}).
 
-#### `useThemeProvider()`
+**Returns:** The rendered router provider element.
 
-Hook to access the theme provider from context.
+#### `I18nProvider(props)`
+
+Provider for internationalization.
 
 ```typescript
-function useThemeProvider(): ThemeProvider
+function I18nProvider({
+  provider,
+  children,
+}: I18nProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** The theme provider from context
+- `props` — Component props (see {@link I18nProviderProps}).
 
-#### `useTranslation()`
+**Returns:** The rendered i18n provider element.
 
-Hook for internationalization.
+#### `HttpProvider(props)`
+
+Provider for HTTP client.
 
 ```typescript
-function useTranslation(): UseTranslationResult
+function HttpProvider({
+  client,
+  children,
+}: HttpProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** Translation function and locale management
+- `props` — Component props (see {@link HttpProviderProps}).
 
-#### `useUser()`
+**Returns:** The rendered HTTP provider element.
 
-Hook to get just the authenticated user.
+#### `StorageProvider(props)`
+
+Provider for storage.
 
 ```typescript
-function useUser(): T | null
+function StorageProvider({
+  provider,
+  children,
+}: StorageProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** The authenticated user or null
-
-#### `useVerifyPaymentReturn(options)`
+- `props` — Component props (see {@link StorageProviderProps}).
 
-Reads the payment id a provider put in the return URL and confirms the
-purchase server-side with `POST /users/:id/verify-payment/:provider`.
+**Returns:** The rendered storage provider element.
 
-**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`.
+#### `LoggerProvider(props)`
 
-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.
+Provider for logging.
 
 ```typescript
-function useVerifyPaymentReturn(
-  options?: UseVerifyPaymentReturnOptions,
-): UseVerifyPaymentReturnResult
+function LoggerProvider({
+  provider,
+  children,
+}: LoggerProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-- `options` — Provider fallback + lifecycle callbacks (see {@link UseVerifyPaymentReturnOptions}).
-
-**Returns:** The verification state (see {@link UseVerifyPaymentReturnResult}).
+- `props` — Component props (see {@link LoggerProviderProps}).
 
-#### `useVersion()`
+**Returns:** The rendered logger provider element.
 
-Hook for version state and update actions.
+#### `ChatProvider(props)`
 
-Uses module-level `getProvider()` — version is a singleton, not context-provided.
+Provider for AI chat.
 
 ```typescript
-function useVersion(): UseVersionResult
+function ChatProvider({
+  provider,
+  children,
+}: ChatProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** Version state and action methods
+- `props` — Component props (see {@link ChatProviderProps}).
 
-#### `useWatch(form, name)`
+**Returns:** The rendered chat provider element.
 
-Hook to watch a specific field value.
+#### `WorkspaceProvider(props)`
+
+Provider for IDE workspace.
 
 ```typescript
-function useWatch(form: FormController<T>, name: K): T[K]
+function WorkspaceProvider({
+  provider,
+  children,
+}: WorkspaceProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-- `form` — Form controller
-- `name` — Field name to watch
+- `props` — Component props (see {@link WorkspaceProviderProps}).
 
-**Returns:** Current field value
+**Returns:** The rendered workspace provider element.
 
-#### `useWorkspace()`
+#### `EditorProvider(props)`
 
-Hook for IDE workspace layout management.
+Provider for code editor.
 
 ```typescript
-function useWorkspace(): UseWorkspaceResult
+function EditorProvider({
+  provider,
+  children,
+}: EditorProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** The workspace state and management methods.
+- `props` — Component props (see {@link EditorProviderProps}).
 
-#### `useWorkspaceProvider()`
+**Returns:** The rendered editor provider element.
 
-Access the workspace provider from context.
+#### `PreviewProvider(props)`
+
+Provider for live preview.
 
 ```typescript
-function useWorkspaceProvider(): WorkspaceProvider
+function PreviewProvider({
+  provider,
+  children,
+}: PreviewProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
 ```
 
-**Returns:** The result.
+- `props` — Component props (see {@link PreviewProviderProps}).
 
-#### `WorkspaceProvider(props)`
+**Returns:** The rendered preview provider element.
 
-Provider for IDE workspace.
+#### `MoleculeProvider(props)`
+
+Combined provider for all molecule services.
+
+Provides a convenient way to wrap your app with all molecule providers at once.
+Only providers that are passed will be included.
 
 ```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`
@@ -2680,36 +2689,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> | 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`
@@ -2720,60 +2729,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>
 ```
 
-#### `WorkspaceContext`
+#### `PreviewContext`
 
-Context for IDE workspace provider.
+Context for live preview provider.
 
 ```typescript
-const WorkspaceContext: Context<WorkspaceProvider | null>
+const PreviewContext: Context<PreviewProvider | null>
 ```
 
 ## Injection Notes