@molecule/app-svelte 1.0.2 → 1.0.3

package/README.md

@@ -3,15 +3,11 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-09-15T19:11:43.926Z
+Generated: 2026-10-21T17:02:43.425Z
 -->
 
 # @molecule/app-svelte
 
-> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
-> It is written to be read by coding agents as much as by people, and is generated from this
-> package's source — edit `src/index.ts` JSDoc, not this file.
-
 Svelte framework bindings for molecule.dev.
 
 Provides Svelte stores and context utilities for all molecule core
@@ -19,6 +15,10 @@ interfaces: call `setMoleculeContext(config)` once in the root layout,
 then consume services anywhere below via store factories
 (`createAuthStores`, `createThemeStores`, `createI18nStores`, …).
 
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
 ## Quick Start
 
 ```svelte
@@ -69,119 +69,38 @@ npm install @molecule/app-svelte @molecule/app-auth @molecule/app-device @molecu
 
 ### Interfaces
 
-#### `AsyncStateStore`
+#### `Readable`
 
-Async state store.
+Readable interface for subscribing.
 
 ```typescript
-interface AsyncStateStore<T> extends Writable<T> {
-  setState: (value: T | ((prev: T) => T) | Promise<T | ((prev: T) => T)>) => void
-  extendState: (
-    partial:
-      Partial<T> | ((prev: T) => Partial<T>) | Promise<Partial<T> | ((prev: T) => Partial<T>)>,
-  ) => void
+interface Readable<T> {
+  /**
+   * Subscribe on value changes.
+   * @param run subscription callback
+   * @param invalidate cleanup callback
+   */
+  subscribe(this: void, run: Subscriber<T>, invalidate?: () => void): Unsubscriber
 }
 ```
 
-#### `AuthClient`
+#### `Writable`
 
-Auth client interface that all auth bond packages must implement.
-Provides login/logout/register flows, token management, profile
-updates, and auth state subscription.
+Writable interface for both updating and subscribing.
 
 ```typescript
-interface AuthClient<T = UserProfile> {
-  /**
-   * Returns the current authentication state snapshot.
-   */
-  getState(): AuthState<T>
-  /**
-   * Returns whether the user is currently authenticated.
-   */
-  isAuthenticated(): boolean
-  /**
-   * Gets the current user.
-   */
-  getUser(): T | null
-  /**
-   * Updates the cached user object (state + persistent storage) without
-   * hitting the network. Intended for local refreshes after a per-app
-   * mutation (e.g., the user just PATCHed their own profile and the
-   * server returned the canonical row). Does NOT change tokens.
-   */
-  setUser(user: T | null): void
-  /**
-   * Gets the current access token.
-   */
-  getAccessToken(): string | null
-  /**
-   * Stores the access token in the configured token storage adapter (in-memory
-   * by default). Use this to seed the token after an out-of-band exchange (e.g.
-   * the OAuth code→token redirect) instead of writing to `localStorage` directly,
-   * which would violate the in-memory-default storage contract and make the bearer
-   * token JS-readable (XSS-exfiltratable). Pass `null` to clear it.
-   */
-  setAccessToken(token: string | null): void
-  /**
-   * Gets the refresh token.
-   */
-  getRefreshToken(): string | null
-  /**
-   * Logs in with credentials.
-   */
-  login(credentials: LoginCredentials): Promise<AuthResult<T>>
-  /**
-   * Logs out the current user.
-   */
-  logout(): Promise<void>
-  /**
-   * Registers a new user.
-   */
-  register(data: RegisterData): Promise<AuthResult<T>>
-  /**
-   * Refreshes the access token.
-   */
-  refresh(): Promise<AuthResult<T>>
-  /**
-   * Requests a password reset.
-   */
-  requestPasswordReset(data: PasswordResetRequest): Promise<void>
-  /**
-   * Confirms a password reset.
-   */
-  confirmPasswordReset(data: PasswordResetConfirm): Promise<void>
-  /**
-   * Updates the current user's profile.
-   */
-  updateProfile(data: Partial<T>): Promise<T>
-  /**
-   * Changes the current user's password.
-   */
-  changePassword(oldPassword: string, newPassword: string): Promise<void>
-  /**
-   * Initializes auth state (e.g., from stored tokens).
-   */
-  initialize(): Promise<void>
-  /**
-   * Subscribes to auth state changes.
-   */
-  subscribe(callback: (state: AuthState<T>) => void): () => void
-  /**
-   * Subscribes to auth state changes (alias for subscribe).
-   */
-  onAuthChange(callback: (state: AuthState<T>) => void): () => void
-  /**
-   * Gets the current access token (alias for getAccessToken).
-   */
-  getToken?(): string | null
+interface Writable<T> extends Readable<T> {
   /**
-   * Adds an auth event listener.
+   * Set value and inform subscribers.
+   * @param value to set
    */
-  addEventListener(listener: AuthEventListener): () => void
+  set(this: void, value: T): void
+
   /**
-   * Destroys the auth client.
+   * Update value using callback and inform subscribers.
+   * @param updater callback
    */
-  destroy(): void
+  update(this: void, updater: Updater<T>): void
 }
 ```
 
@@ -191,6 +110,11 @@ Reactive authentication state snapshot (initialized, authenticated, user, loadin
 
 ```typescript
 interface AuthState<T = UserProfile> {
+  /**
+   * The session's state as one value — render from this instead of combining
+   * `initialized`/`authenticated`/`loading`. See {@link AuthStatus}.
+   */
+  status: AuthStatus
   /**
    * Whether auth state has been initialized.
    */
@@ -214,6 +138,178 @@ interface AuthState<T = UserProfile> {
 }
 ```
 
+#### `AuthClient`
+
+Auth client interface that all auth bond packages must implement.
+Provides login/logout/register flows, token management, profile
+updates, and auth state subscription.
+
+```typescript
+interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegister> = Record<never, never>> {
+    /**
+     * Returns the current authentication state snapshot.
+     *
+     * READING the state starts the client's one session restore when nobody has called
+     * {@link initialize} yet — lazily and exactly once, sharing the promise an explicit
+     * `initialize()` returns. A hook (`useAuth()`), a subscriber, `isAuthenticated()` and
+     * `getUser()` are reads too, so a client whose entry file dropped the template's
+     * `authClient.initialize()` line still restores instead of reporting `'loading'`
+     * forever.
+     */
+    getState(): AuthState<T>;
+    /**
+     * Returns whether the user is currently authenticated.
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Gets the current user.
+     */
+    getUser(): T | null;
+    /**
+     * Updates the cached user object (state + persistent storage) without
+     * hitting the network. Intended for local refreshes after a per-app
+     * mutation (e.g., the user just PATCHed their own profile and the
+     * server returned the canonical row). Does NOT change tokens.
+     *
+     * This does not sign the client in: `authenticated` and `status` are
+     * unchanged, so an anonymous client stays anonymous. Use
+     * {@link login} / {@link register} for a credential exchange, or
+     * {@link setSession} when the token was issued outside the client.
+     */
+    setUser(user: T | null): void;
+    /**
+     * Gets the current access token.
+     */
+    getAccessToken(): string | null;
+    /**
+     * Stores the access token in the configured token storage adapter (in a
+     * browser, Web Storage; `'memory'` where no browser store exists). Use this
+     * to seed the token after an out-of-band exchange (e.g. the OAuth
+     * code→token redirect) instead of writing to `localStorage` directly,
+     * which would violate the storage contract and make a stored bearer token
+     * JS-readable (XSS-exfiltratable). Pass `null` to clear it.
+     *
+     * This changes token storage only; it does not sign the client in
+     * (`authenticated` and `status` are unchanged). Use {@link login} /
+     * {@link register} for a credential exchange, or call {@link setSession}
+     * with the token and the user to establish an already-issued session.
+     */
+    setAccessToken(token: string | null): void;
+    /**
+     * Adopts a session an out-of-band exchange already established: stores the
+     * access token (and the refresh token when given), caches the user, and
+     * sets the COMPLETE state — `initialized`, `authenticated`, `status:
+     * 'authenticated'`, no error — in one update, with one subscriber
+     * notification. Every hook reading the shared client sees the user as
+     * signed in immediately.
+     *
+     * This is the way to seed an OAuth/custom sign-in. Calling
+     * {@link setAccessToken} and {@link setUser} instead does NOT sign the
+     * client in.
+     */
+    setSession(session: AuthSessionSeed<T>): void;
+    /**
+     * Gets the refresh token.
+     */
+    getRefreshToken(): string | null;
+    /**
+     * Logs in with credentials.
+     */
+    login(credentials: LoginCredentials): Promise<AuthResult<T>>;
+    /**
+     * Logs out the current user.
+     */
+    logout(): Promise<void>;
+    /**
+     * Registers a new user. Accepts the base fields plus the app's own fields
+     * (`TRegister`) at the top level — see {@link RegisterData}.
+     */
+    register(data: RegisterData<TRegister>): Promise<AuthResult<T>>;
+    /**
+     * Refreshes the access token.
+     */
+    refresh(): Promise<AuthResult<T>>;
+    /**
+     * Requests a password reset.
+     */
+    requestPasswordReset(data: PasswordResetRequest): Promise<void>;
+    /**
+     * Confirms a password reset.
+     */
+    confirmPasswordReset(data: PasswordResetConfirm): Promise<void>;
+    /**
+     * Updates the current user's profile.
+     */
+    updateProfile(data: Partial<T>): Promise<T>;
+    /**
+     * Changes the current user's password.
+     */
+    changePassword(oldPassword: string, newPassword: string): Promise<void>;
+    /**
+     * Initializes auth state (e.g., from stored tokens).
+     *
+     * LAZY and IDEMPOTENT: the first read of the state ({@link getState},
+     * {@link subscribe}, `useAuth()`) starts this same restore when nobody has called
+     * `initialize()`, and every later call shares the one promise instead of sending a
+     * second request. An app that keeps the template's explicit call behaves exactly as
+     * before; an app that loses that line still restores its session.
+     *
+     * With a stored token AND a stored user it marks the session `'authenticated'`
+     * SYNCHRONOUSLY — before its first `await` — so the first render is the
+     * signed-in UI and no page waits on a verification round trip. Any check
+     * (a refresh, the cookie-restore probe) settles behind that render, and only an
+     * explicit 401/403 ends the session; a network/5xx/404 failure keeps it and
+     * reports `'unavailable'`. With no stored user the client stays `'loading'`
+     * until the cookie restore decides.
+     *
+     * Do not put this call (or a `/me` request of your own) in front of the first
+     * render, and do not render a loading screen over a session it just restored:
+     * `whenRestored()` already resolves as soon as the restore has settled, and the
+     * HTTP gate built on it holds requests for exactly that window.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Re-checks a restored session against the server, in the background — the
+     * boot-time validation an app with a stored token needs when a revoked or
+     * expired token must sign the user out. Call it AFTER the first render
+     * (`initialize()` restores synchronously from storage; this costs one request).
+     *
+     * - The server confirms the user: the session is refreshed and {@link AuthState.status}
+     *   stays `'authenticated'`.
+     * - The server answers 401 or 403: the token is dead — the stored session is
+     *   cleared and the status becomes `'unauthenticated'`.
+     * - The server cannot confirm the session — a network failure, a 5xx, or a 404
+     *   from a misconfigured {@link AuthClientConfig.currentUserEndpoint}: the
+     *   session (token AND user) is KEPT and the status becomes `'unavailable'`, so
+     *   the app can retry instead of signing the user out over a bad connection or a
+     *   route that does not exist. The 404 error names `currentUserEndpoint`.
+     *
+     * Do not hand-write this beside the client: a parallel token/user store for a
+     * "validating"/"unavailable" flag is the race this method removes.
+     *
+     * Optional: a provider with no restorable session has nothing to validate.
+     */
+    validateSession?(): Promise<void>;
+    /**
+     * Resolves when the session restore started by `initialize()` has settled — the point
+     * after which the client knows whether this visitor is signed in.
+     *
+     * Resolves IMMEDIATELY when no restore is in flight: before `initialize()` is ever
+     * called, and after it has finished. A restore that failed resolves too (it settled the
+     * question), so an HTTP client can await this before every request without risking one
+     * held forever. That is what makes the fetch-before-restore race impossible: a page that
+     * fetches viewer-dependent data on mount waits here instead of going out anonymously
+     * (see `setAuthGate` in `@molecule/app-http`).
+     *
+     * Optional: a provider that restores no session has nothing to wait for. Without it, an
+     * HTTP client bonded to that provider sends first-paint requests unauthenticated.
+     *
+     * A provider whose restore sends a request THROUGH the gated HTTP client must send that
+     * request with `skipAuthGate: true` (`RequestConfig` in `@molecule/app-http`): the gate
+     * waits on this promise, so holding the restore's own request makes the gate wait on
+// … truncated — the full declaration is in node_modules/@molecule/app-svelte/dist
+```
+
 #### `FormController`
 
 Form controller interface.
@@ -366,7 +462,8 @@ interface HttpClient {
    */
   defaultHeaders: Record<string, string>
   /**
-   * Makes a generic HTTP request.
+   * Makes a generic HTTP request. `data` is a field of THIS config object — the same body
+   * `post(url, data, config)` takes as its second argument.
    */
   request<T = unknown>(config: FullRequestConfig): Promise<HttpResponse<T>>
   /**
@@ -374,15 +471,19 @@ interface HttpClient {
    */
   get<T = unknown>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>
   /**
-   * Makes a POST request.
+   * Makes a POST request. `data` is the request BODY, not a config object: the wire body is
+   * `data` itself, so `post(url, { data: body })` sends `{"data":body}` — pass `body` directly.
+   * A config (headers, params) is the THIRD argument.
    */
   post<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
   /**
-   * Makes a PUT request.
+   * Makes a PUT request. `data` is the request BODY (second argument) — never `{ data: body }`,
+   * which sends `{"data":body}`; a config is the THIRD argument.
    */
   put<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
   /**
-   * Makes a PATCH request.
+   * Makes a PATCH request. `data` is the request BODY (second argument) — never `{ data: body }`,
+   * which sends `{"data":body}`; a config is the THIRD argument.
    */
   patch<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
   /**
@@ -421,18 +522,6 @@ interface HttpClient {
 }
 ```
 
-#### `HttpState`
-
-State for async HTTP operations.
-
-```typescript
-interface HttpState<T> {
-  data: T | null
-  loading: boolean
-  error: Error | null
-}
-```
-
 #### `I18nProvider`
 
 i18n provider interface.
@@ -691,149 +780,6 @@ interface LoggerProvider {
 }
 ```
 
-#### `MoleculeConfig`
-
-Configuration for molecule Svelte context.
-
-```typescript
-interface MoleculeConfig {
-  state?: StateProvider
-  auth?: AuthClient<unknown>
-  theme?: ThemeProvider
-  router?: Router
-  i18n?: I18nProvider
-  http?: HttpClient
-  storage?: StorageProvider
-  logger?: LoggerProvider
-}
-```
-
-#### `MoleculeStore`
-
-Reactive state container with getState, setState, subscribe, and destroy.
-
-All state management providers must implement this interface.
-
-```typescript
-interface Store<T> {
-  /**
-   * Gets the current state.
-   */
-  getState(): T
-  /**
-   * Sets the state (partial or via updater function).
-   */
-  setState(partial: Partial<T> | ((state: T) => Partial<T>)): void
-  /**
-   * Subscribes to state changes.
-   * Returns an unsubscribe function.
-   */
-  subscribe(listener: StateListener<T>): () => void
-  /**
-   * Destroys the store and cleans up subscriptions.
-   */
-  destroy(): void
-}
-```
-
-#### `OAuthHelpers`
-
-OAuth helpers returned by {@link createOAuthHelpers}.
-
-```typescript
-interface OAuthHelpers {
-  /** Readable store of available OAuth provider names. */
-  providers: Readable<string[]>
-  /** Builds the OAuth initiation URL for a provider. */
-  getOAuthUrl: (provider: string) => string
-  /** Full-page redirect to the provider's OAuth initiation endpoint. */
-  redirect: (provider: string) => void
-  /**
-   * Handles an OAuth callback: when the current URL carries a `code` param and
-   * a provider was stashed by {@link redirect}, exchanges the code for a
-   * session. A guarded no-op otherwise. Runs automatically when
-   * {@link createOAuthHelpers} is called in a browser; exposed for manual
-   * invocation (e.g. tests or custom callback screens).
-   */
-  handleCallback: () => Promise<void>
-}
-```
-
-#### `OAuthOptions`
-
-OAuth configuration options.
-
-```typescript
-interface OAuthOptions {
-  /** Base URL for the API server (e.g. `https://api.example.com`). */
-  baseURL?: string
-  /** List of supported OAuth provider names (e.g. `['google', 'github']`). */
-  oauthProviders?: string[]
-  /** Path prefix for OAuth initiation routes. Defaults to `/oauth`. */
-  oauthEndpoint?: string
-  /** Path for the OAuth login POST endpoint. Defaults to `/users/log-in/oauth`. */
-  loginEndpoint?: string
-  /** Callback fired after a successful OAuth login. */
-  onSuccess?: () => void
-  /** Callback fired with an error message when the OAuth login fails. */
-  onError?: (error: string) => void
-  /**
-   * Explicit auth client used to establish the session after the callback
-   * exchange. Defaults to the client in Svelte context (only resolvable when
-   * called during component initialization) — pass one explicitly for
-   * callers/tests outside a component/context.
-   */
-  authClient?: AuthClient<unknown>
-}
-```
-
-#### `PasswordResetStores`
-
-Password reset stores.
-
-```typescript
-interface PasswordResetStores {
-  request: Readable<PromiseState<void>> & {
-    call: (data: PasswordResetRequest) => Promise<void>
-    cancel: (message?: string) => void
-    reset: () => void
-  }
-  confirm: Readable<PromiseState<void>> & {
-    call: (data: PasswordResetConfirm) => Promise<void>
-    cancel: (message?: string) => void
-    reset: () => void
-  }
-  resetAll: () => void
-}
-```
-
-#### `PromiseStore`
-
-Promise store with action methods.
-
-```typescript
-interface PromiseStore<T> extends Readable<PromiseState<T>> {
-  call: (...args: any[]) => Promise<T>
-  cancel: (message?: string) => void
-  reset: () => void
-}
-```
-
-#### `Readable`
-
-Readable interface for subscribing.
-
-```typescript
-interface Readable<T> {
-  /**
-   * Subscribe on value changes.
-   * @param run subscription callback
-   * @param invalidate cleanup callback
-   */
-  subscribe(this: void, run: Subscriber<T>, invalidate?: () => void): Unsubscriber
-}
-```
-
 #### `RouteLocation`
 
 Current URL decomposed into pathname, search string, hash, navigation state, and unique key.
@@ -968,19 +914,68 @@ interface Router {
 }
 ```
 
-#### `StateProvider`
+#### `StoreConfig`
 
-State provider interface that all state management bond packages
-must implement. Provides the store creation factory.
+Configuration for creating a store (initial state, optional name, and middleware chain).
 
 ```typescript
-interface StateProvider {
+interface StoreConfig<T> {
   /**
-   * Creates a new store.
+   * Initial state value.
    */
-  createStore<T>(config: StoreConfig<T>): Store<T>
-}
-```
+  initialState: T
+  /**
+   * Optional name for debugging.
+   */
+  name?: string
+  /**
+   * Optional middleware functions.
+   */
+  middleware?: StoreMiddleware<T>[]
+}
+```
+
+#### `MoleculeStore`
+
+Reactive state container with getState, setState, subscribe, and destroy.
+
+All state management providers must implement this interface.
+
+```typescript
+interface Store<T> {
+  /**
+   * Gets the current state.
+   */
+  getState(): T
+  /**
+   * Sets the state (partial or via updater function).
+   */
+  setState(partial: Partial<T> | ((state: T) => Partial<T>)): void
+  /**
+   * Subscribes to state changes.
+   * Returns an unsubscribe function.
+   */
+  subscribe(listener: StateListener<T>): () => void
+  /**
+   * Destroys the store and cleans up subscriptions.
+   */
+  destroy(): void
+}
+```
+
+#### `StateProvider`
+
+State provider interface that all state management bond packages
+must implement. Provides the store creation factory.
+
+```typescript
+interface StateProvider {
+  /**
+   * Creates a new store.
+   */
+  createStore<T>(config: StoreConfig<T>): Store<T>
+}
+```
 
 #### `StorageProvider`
 
@@ -1025,58 +1020,6 @@ interface StorageProvider {
 }
 ```
 
-#### `StorageValueState`
-
-State for async storage values.
-
-```typescript
-interface StorageValueState<T> {
-  value: T | undefined
-  loading: boolean
-  error: Error | null
-}
-```
-
-#### `StoreConfig`
-
-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.
-
-```typescript
-interface Theme {
-  name: string
-  mode: 'light' | 'dark'
-  colors: ThemeColors
-  breakpoints: ThemeBreakpoints
-  spacing: ThemeSpacing
-  typography: ThemeTypography
-  borderRadius: ThemeBorderRadius
-  shadows: ThemeShadows
-  transitions: ThemeTransitions
-  zIndex: ThemeZIndex
-}
-```
-
 #### `ThemeProvider`
 
 Manages theme state including the active theme, mode toggling,
@@ -1123,866 +1066,1003 @@ interface ThemeProvider {
 }
 ```
 
-#### `Writable`
+#### `Theme`
 
-Writable interface for both updating and subscribing.
+Complete theme definition.
 
 ```typescript
-interface Writable<T> extends Readable<T> {
-  /**
-   * Set value and inform subscribers.
-   * @param value to set
-   */
-  set(this: void, value: T): void
-
-  /**
-   * Update value using callback and inform subscribers.
-   * @param updater callback
-   */
-  update(this: void, updater: Updater<T>): void
+interface Theme {
+  name: string
+  mode: 'light' | 'dark'
+  colors: ThemeColors
+  breakpoints: ThemeBreakpoints
+  spacing: ThemeSpacing
+  typography: ThemeTypography
+  borderRadius: ThemeBorderRadius
+  shadows: ThemeShadows
+  transitions: ThemeTransitions
+  zIndex: ThemeZIndex
 }
 ```
 
-### Types
-
-#### `CapacitorAppStore`
+#### `AsyncStateStore`
 
-Return type for the Capacitor app store.
+Async state store.
 
 ```typescript
-type CapacitorAppStore = Readable<CapacitorAppState> & {
-  initialize: () => Promise<void>
+interface AsyncStateStore<T> extends Writable<T> {
+  setState: (value: T | ((prev: T) => T) | Promise<T | ((prev: T) => T)>) => void
+  extendState: (
+    partial:
+      Partial<T> | ((prev: T) => Partial<T>) | Promise<Partial<T> | ((prev: T) => Partial<T>)>,
+  ) => void
 }
 ```
 
-#### `ChangePasswordStore`
+#### `OAuthOptions`
 
-Change password store type.
+OAuth configuration options.
 
 ```typescript
-type ChangePasswordStore = PromiseStore<void>
+interface OAuthOptions {
+  /** Base URL for the API server (e.g. `https://api.example.com`). */
+  baseURL?: string
+  /** List of supported OAuth provider names (e.g. `['google', 'github']`). */
+  oauthProviders?: string[]
+  /** Path prefix for OAuth initiation routes. Defaults to `/oauth`. */
+  oauthEndpoint?: string
+  /** Path for the OAuth login POST endpoint. Defaults to `/users/log-in/oauth`. */
+  loginEndpoint?: string
+  /** Callback fired after a successful OAuth login. */
+  onSuccess?: () => void
+  /** Callback fired with an error message when the OAuth login fails. */
+  onError?: (error: string) => void
+  /**
+   * Explicit auth client used to establish the session after the callback
+   * exchange. Defaults to the client in Svelte context (only resolvable when
+   * called during component initialization) — pass one explicitly for
+   * callers/tests outside a component/context.
+   */
+  authClient?: AuthClient<unknown>
+}
 ```
 
-#### `LoginStore`
+#### `OAuthHelpers`
 
-Login store type.
+OAuth helpers returned by {@link createOAuthHelpers}.
 
 ```typescript
-type LoginStore<T = unknown> = PromiseStore<AuthResult<T>>
+interface OAuthHelpers {
+  /** Readable store of available OAuth provider names. */
+  providers: Readable<string[]>
+  /** Builds the OAuth initiation URL for a provider. */
+  getOAuthUrl: (provider: string) => string
+  /** Full-page redirect to the provider's OAuth initiation endpoint. */
+  redirect: (provider: string) => void
+  /**
+   * Handles an OAuth callback: when the current URL carries a `code` param and
+   * a provider was stashed by {@link redirect}, exchanges the code for a
+   * session. A guarded no-op otherwise. Runs automatically when
+   * {@link createOAuthHelpers} is called in a browser; exposed for manual
+   * invocation (e.g. tests or custom callback screens).
+   */
+  handleCallback: () => Promise<void>
+}
 ```
 
-#### `QueryParams`
+#### `PasswordResetStores`
 
-URL query string parameter map (single values or arrays for repeated keys).
+Password reset stores.
 
 ```typescript
-type QueryParams = Record<string, string | string[] | undefined>
+interface PasswordResetStores {
+  request: Readable<PromiseState<void>> & {
+    call: (data: PasswordResetRequest) => Promise<void>
+    cancel: (message?: string) => void
+    reset: () => void
+  }
+  confirm: Readable<PromiseState<void>> & {
+    call: (data: PasswordResetConfirm) => Promise<void>
+    cancel: (message?: string) => void
+    reset: () => void
+  }
+  resetAll: () => void
+}
 ```
 
-#### `RouteParams`
+#### `PromiseStore`
 
-URL path parameter key-value map extracted from dynamic route segments (e.g. `{ id: '123' }`).
+Promise store with action methods.
 
 ```typescript
-type RouteParams = Record<string, string>
+interface PromiseStore<T> extends Readable<PromiseState<T>> {
+  call: (...args: any[]) => Promise<T>
+  cancel: (message?: string) => void
+  reset: () => void
+}
 ```
 
-#### `SignupStore`
+#### `MoleculeConfig`
 
-Signup store type.
+Configuration for molecule Svelte context.
 
 ```typescript
-type SignupStore<T = unknown> = PromiseStore<AuthResult<T>>
+interface MoleculeConfig {
+  state?: StateProvider
+  auth?: AuthClient<unknown>
+  theme?: ThemeProvider
+  router?: Router
+  i18n?: I18nProvider
+  http?: HttpClient
+  storage?: StorageProvider
+  logger?: LoggerProvider
+}
 ```
 
-### Functions
-
-#### `createAsyncState(initialValue)`
+#### `HttpState`
 
-Creates a writable store with async-capable setState and extendState.
+State for async HTTP operations.
 
 ```typescript
-function createAsyncState(initialValue: T): AsyncStateStore<T>
+interface HttpState<T> {
+  data: T | null
+  loading: boolean
+  error: Error | null
+}
 ```
 
-- `initialValue` — The initial state value
-
-**Returns:** The created instance.
-
-#### `createAuthStores()`
+#### `StorageValueState`
 
-Create auth stores from the auth client in context.
+State for async storage values.
 
 ```typescript
-function createAuthStores(): AuthStores<T> & { error: Readable<string | null> }
+interface StorageValueState<T> {
+  value: T | undefined
+  loading: boolean
+  error: Error | null
+}
 ```
 
-**Returns:** Auth stores and actions
-
-#### `createAuthStoresFromClient(client)`
+### Types
 
-Create auth stores from a specific auth client.
+#### `RouteParams`
 
-Use this when you don't want to use context.
+URL path parameter key-value map extracted from dynamic route segments (e.g. `{ id: '123' }`).
 
 ```typescript
-function createAuthStoresFromClient(client: AuthClient<T>): AuthStores<T>
+type RouteParams = Record<string, string>
 ```
 
-- `client` — Auth client
+#### `QueryParams`
 
-**Returns:** Auth stores and actions
+URL query string parameter map (single values or arrays for repeated keys).
 
-#### `createCapacitorAppStore(options)`
+```typescript
+type QueryParams = Record<string, string | string[] | undefined>
+```
 
-Create a Svelte store wrapping the Capacitor app coordinator.
+#### `CapacitorAppStore`
 
-Creates a CapacitorApp instance, subscribes to state changes,
-and auto-initializes. The returned store is readable and also
-exposes an `initialize` method for manual re-initialization.
+Return type for the Capacitor app store.
 
 ```typescript
-function createCapacitorAppStore(options?: CapacitorAppOptions): CapacitorAppStore
+type CapacitorAppStore = Readable<CapacitorAppState> & {
+  initialize: () => Promise<void>
+}
 ```
 
-- `options` — Capacitor app options
+#### `ChangePasswordStore`
 
-**Returns:** A readable store of CapacitorAppState with an initialize method
+Change password store type.
 
-#### `createChangePasswordStore()`
+```typescript
+type ChangePasswordStore = PromiseStore<void>
+```
 
-Creates a change password store with async state tracking.
+#### `LoginStore`
+
+Login store type.
 
 ```typescript
-function createChangePasswordStore(): ChangePasswordStore
+type LoginStore<T = unknown> = PromiseStore<AuthResult<T>>
 ```
 
-**Returns:** Change password promise store
-
-#### `createDeleteStore(url, config)`
+#### `SignupStore`
 
-Creates a DELETE request store.
+Signup store type.
 
 ```typescript
-function createDeleteStore(url: string, config?: RequestConfig): HttpStore<T>
+type SignupStore<T = unknown> = PromiseStore<AuthResult<T>>
 ```
 
-- `url` — The request endpoint URL.
-- `config` — Optional request configuration such as headers or params.
-
-**Returns:** A subscribable HTTP store for the DELETE request with execute and reset methods.
+### Functions
 
-#### `createDeviceStores()`
+#### `setMoleculeContext(config)`
 
-Create device stores from the module-level device provider.
+Set all molecule providers in Svelte context.
 
-Device information is static (no reactive subscription needed),
-so this returns plain values rather than Svelte stores.
+Call this in your root layout/component.
 
 ```typescript
-function createDeviceStores(): {
-  deviceInfo: DeviceInfo
-  screenInfo: ScreenInfo
-  hardwareInfo: HardwareInfo
-  featureSupport: FeatureSupport
-  supports: (feature: keyof FeatureSupport) => boolean
-  isOnline: () => boolean
-  isStandalone: () => boolean
-  language: string
-  languages: string[]
-}
+function setMoleculeContext(config: MoleculeConfig): void
 ```
 
-**Returns:** Device information and utility functions
+- `config` — Provider instances to register (state, auth, theme, router, i18n, http, storage, logger).
 
-#### `createFieldStore(controller, name)`
+#### `setStateContext(provider)`
 
-Create a readable store that tracks a single field's state.
+Sets the state context.
 
 ```typescript
-function createFieldStore(controller: FormController<T>, name: K): Readable<FieldState<T[K]>>
+function setStateContext(provider: StateProvider): void
 ```
 
-- `controller` — Form controller
-- `name` — Field name to track
-
-**Returns:** Readable store of the field state
+- `provider` — The state provider to store in Svelte context.
 
-#### `createFormStores(provider, options)`
+#### `setAuthContext(client)`
 
-Create form stores from a form provider and options.
+Sets the auth context.
 
 ```typescript
-function createFormStores(provider: FormProvider, options: FormOptions<T>): FormStores<T>
+function setAuthContext(client: AuthClient<T, Record<never, never>>): void
 ```
 
-- `provider` — Form provider instance
-- `options` — Form creation options
-
-**Returns:** Form stores and actions
+- `client` — The auth client to store in Svelte context.
 
-#### `createGetStore(url, config)`
+#### `setThemeContext(provider)`
 
-Creates a GET request store.
+Sets the theme context.
 
 ```typescript
-function createGetStore(url: string, config?: RequestConfig): HttpStore<T>
+function setThemeContext(provider: ThemeProvider): void
 ```
 
-- `url` — The request endpoint URL.
-- `config` — Optional request configuration such as headers or params.
-
-**Returns:** A subscribable HTTP store for the GET request with execute and reset methods.
+- `provider` — The theme provider to store in Svelte context.
 
-#### `createHttpStore(method, url, config)`
+#### `setRouterContext(router)`
 
-Create an HTTP request store.
+Sets the router context.
 
 ```typescript
-function createHttpStore(
-  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
-  url: string,
-  config?: RequestConfig,
-): HttpStore<T>
+function setRouterContext(router: Router): void
 ```
 
-- `method` — HTTP method
-- `url` — Request URL
-- `config` — Request configuration
-
-**Returns:** Store with state and actions
+- `router` — The router instance to store in Svelte context.
 
-#### `createHttpStoresFromClient(client)`
+#### `setI18nContext(provider)`
 
-Creates HTTP store factory methods bound to a specific client instance.
+Sets the i18n context.
 
 ```typescript
-function createHttpStoresFromClient(client: HttpClient): HttpStoreFactory
+function setI18nContext(provider: I18nProvider): void
 ```
 
-- `client` — The HTTP client to use for all created stores.
-
-**Returns:** An object with get, post, put, patch, and delete factory methods.
+- `provider` — The i18n provider to store in Svelte context.
 
-#### `createI18nStores()`
+#### `setHttpContext(client)`
 
-Create i18n stores from the i18n provider in context.
+Sets the HTTP context.
 
 ```typescript
-function createI18nStores(): I18nStores
+function setHttpContext(client: HttpClient): void
 ```
 
-**Returns:** I18n stores and actions
+- `client` — The HTTP client to store in Svelte context.
 
-#### `createI18nStoresFromProvider(provider)`
+#### `setStorageContext(provider)`
 
-Create i18n stores from a specific provider.
+Sets the storage context.
 
 ```typescript
-function createI18nStoresFromProvider(provider: I18nProvider): I18nStores
+function setStorageContext(provider: StorageProvider): void
 ```
 
-- `provider` — I18n provider
-
-**Returns:** I18n stores and actions
+- `provider` — The storage provider to store in Svelte context.
 
-#### `createIsActiveStore(location, router, path, exact)`
+#### `setLoggerContext(provider)`
 
-Create a derived store that checks if a path is active.
+Sets the logger context.
 
 ```typescript
-function createIsActiveStore(
-  location: Readable<RouteLocation>,
-  router: Router,
-  path: string,
-  exact?: boolean,
-): Readable<boolean>
+function setLoggerContext(provider: LoggerProvider): void
 ```
 
-- `location` — A readable location store (from createRouterStores or createRouterStoresFromRouter)
-- `router` — Router instance (for isActive check)
-- `path` — Path to check
-- `exact` — Whether to require exact match (default: false)
-
-**Returns:** Readable store of whether the path is active
+- `provider` — The logger provider to store in Svelte context.
 
-#### `createLogger(config)`
+#### `getStateProvider()`
 
-Create a logger with custom configuration.
+Gets the state provider from Svelte context.
 
 ```typescript
-function createLogger(config: LoggerConfig): Logger
+function getStateProvider(): StateProvider
 ```
 
-- `config` — Logger configuration
-
-**Returns:** Logger instance
+**Returns:** The state provider instance.
 
-#### `createLoggerHelpers()`
+#### `getAuthClient()`
 
-Create logger helpers from context.
+Gets the auth client from Svelte context.
 
 ```typescript
-function createLoggerHelpers(): LoggerHelpers
+function getAuthClient(): AuthClient<T, TRegister>
 ```
 
-**Returns:** Logger helper functions
+**Returns:** The auth client instance.
 
-#### `createLoggerHelpersFromProvider(provider)`
+#### `getThemeProvider()`
 
-Create logger helpers from a specific provider.
+Gets the theme provider from Svelte context.
 
 ```typescript
-function createLoggerHelpersFromProvider(provider: LoggerProvider): LoggerHelpers
+function getThemeProvider(): ThemeProvider
 ```
 
-- `provider` — Logger provider
-
-**Returns:** Logger helper functions
+**Returns:** The theme provider instance.
 
-#### `createLoginStore()`
+#### `getRouter()`
 
-Creates a login store with async state tracking.
+Gets the router from Svelte context.
 
 ```typescript
-function createLoginStore(): LoginStore<T>
+function getRouter(): Router
 ```
 
-**Returns:** Login promise store
-
-#### `createOAuthHelpers(options)`
-
-Creates OAuth helpers for provider-based authentication flows.
+**Returns:** The router instance.
 
-When created in a browser, automatically handles OAuth callbacks by
-detecting `code` and `state` URL parameters and exchanging them for a
-session (a guarded no-op when there is no callback code in the URL).
+#### `getI18nProvider()`
 
-Session establishment: the exchange result is applied to the resolved auth
-client (an explicit `options.authClient`, else the Svelte-context client
-when created during component initialization). When NO client is available,
-the server has already established the httpOnly-cookie session via the
-exchange, so a user-carrying response still counts as success —
-`options.onSuccess` fires; a response with no user fires `options.onError`.
+Gets the i18n provider from Svelte context.
 
 ```typescript
-function createOAuthHelpers(options?: OAuthOptions): OAuthHelpers
+function getI18nProvider(): I18nProvider
 ```
 
-- `options` — OAuth configuration (base URL, providers, endpoint paths, callbacks, auth client).
-
-**Returns:** An object containing a readable providers store, URL builder, redirect function, and callback handler.
+**Returns:** The i18n provider instance.
 
-#### `createPasswordResetStores()`
+#### `getHttpClient()`
 
-Creates password reset stores with async state tracking.
+Gets the HTTP client from Svelte context.
 
 ```typescript
-function createPasswordResetStores(): PasswordResetStores
+function getHttpClient(): HttpClient
 ```
 
-**Returns:** Password reset stores for request and confirm steps
+**Returns:** The HTTP client instance.
 
-#### `createPatchStore(url, config)`
+#### `getStorageProvider()`
 
-Creates a PATCH request store.
+Gets the storage provider from Svelte context.
 
 ```typescript
-function createPatchStore(url: string, config?: RequestConfig): HttpStore<T>
+function getStorageProvider(): StorageProvider
 ```
 
-- `url` — The request endpoint URL.
-- `config` — Optional request configuration such as headers or body data.
-
-**Returns:** A subscribable HTTP store for the PATCH request with execute and reset methods.
-
-#### `createPlatformStores()`
+**Returns:** The storage provider instance.
 
-Create platform stores from the module-level platform info.
+#### `getLoggerProvider()`
 
-Platform information is static (no reactive subscription needed),
-so this returns plain values rather than Svelte stores.
+Gets the logger provider from Svelte context.
 
 ```typescript
-function createPlatformStores(): {
-  platform: Platform
-  isNative: boolean
-  isMobile: boolean
-  isDesktop: boolean
-  isWeb: boolean
-  isDevelopment: boolean
-  isProduction: boolean
-  isPlatform: (...platforms: Platform[]) => boolean
-}
+function getLoggerProvider(): LoggerProvider
 ```
 
-**Returns:** Platform information and utility functions
+**Returns:** The logger provider instance.
 
-#### `createPostStore(url, config)`
+#### `createAsyncState(initialValue)`
 
-Creates a POST request store.
+Creates a writable store with async-capable setState and extendState.
 
 ```typescript
-function createPostStore(url: string, config?: RequestConfig): HttpStore<T>
+function createAsyncState(initialValue: T): AsyncStateStore<T>
 ```
 
-- `url` — The request endpoint URL.
-- `config` — Optional request configuration such as headers or body data.
+- `initialValue` — The initial state value
 
-**Returns:** A subscribable HTTP store for the POST request with execute and reset methods.
+**Returns:** The created instance.
 
-#### `createPromiseStore(asyncFn)`
+#### `createAuthStores()`
 
-Creates a store that tracks async function state.
+Create auth stores from the auth client in context.
 
 ```typescript
-function createPromiseStore(asyncFn: T): PromiseStore<Awaited<ReturnType<T>>>
+function createAuthStores(): AuthStores<T, TRegister> & { error: Readable<string | null> }
 ```
 
-- `asyncFn` — The async function to track
+**Returns:** Auth stores and actions
 
-**Returns:** Promise store with subscribe, call, cancel, and reset
+#### `createAuthStoresFromClient(client)`
 
-#### `createPushStores()`
+Create auth stores from a specific auth client.
 
-Create push notification stores from the module-level push provider.
+Use this when you don't want to use context.
 
 ```typescript
-function createPushStores(): {
-  permission: Readable<PermissionStatus | null>
-  token: Readable<PushToken | null>
-  checkPermission: () => Promise<PermissionStatus>
-  requestPermission: () => Promise<PermissionStatus>
-  register: (options?: PushRegisterOptions) => Promise<PushToken>
-  unregister: () => Promise<void>
-  onNotificationReceived: (listener: NotificationReceivedListener) => () => void
-  onNotificationAction: (listener: NotificationActionListener) => () => void
-  onTokenChange: (listener: TokenChangeListener) => () => void
-  setBadge: (count: number) => Promise<void>
-  clearBadge: () => Promise<void>
+function createAuthStoresFromClient(client: AuthClient<T, TRegister>): AuthStores<T, TRegister>
+```
+
+- `client` — Auth client
+
+**Returns:** Auth stores and actions
+
+#### `createCapacitorAppStore(options)`
+
+Create a Svelte store wrapping the Capacitor app coordinator.
+
+Creates a CapacitorApp instance, subscribes to state changes,
+and auto-initializes. The returned store is readable and also
+exposes an `initialize` method for manual re-initialization.
+
+```typescript
+function createCapacitorAppStore(options?: CapacitorAppOptions): CapacitorAppStore
+```
+
+- `options` — Capacitor app options
+
+**Returns:** A readable store of CapacitorAppState with an initialize method
+
+#### `createChangePasswordStore()`
+
+Creates a change password store with async state tracking.
+
+```typescript
+function createChangePasswordStore(): ChangePasswordStore
+```
+
+**Returns:** Change password promise store
+
+#### `createDeviceStores()`
+
+Create device stores from the module-level device provider.
+
+Device information is static (no reactive subscription needed),
+so this returns plain values rather than Svelte stores.
+
+```typescript
+function createDeviceStores(): {
+  deviceInfo: DeviceInfo
+  screenInfo: ScreenInfo
+  hardwareInfo: HardwareInfo
+  featureSupport: FeatureSupport
+  supports: (feature: keyof FeatureSupport) => boolean
+  isOnline: () => boolean
+  isStandalone: () => boolean
+  language: string
+  languages: string[]
 }
 ```
 
-**Returns:** Push notification stores and actions
+**Returns:** Device information and utility functions
 
-#### `createPutStore(url, config)`
+#### `createFormStores(provider, options)`
 
-Creates a PUT request store.
+Create form stores from a form provider and options.
 
 ```typescript
-function createPutStore(url: string, config?: RequestConfig): HttpStore<T>
+function createFormStores(provider: FormProvider, options: FormOptions<T>): FormStores<T>
 ```
 
-- `url` — The request endpoint URL.
-- `config` — Optional request configuration such as headers or body data.
+- `provider` — Form provider instance
+- `options` — Form creation options
 
-**Returns:** A subscribable HTTP store for the PUT request with execute and reset methods.
+**Returns:** Form stores and actions
 
-#### `createRouterStores()`
+#### `createFieldStore(controller, name)`
 
-Create router stores from the router in context.
+Create a readable store that tracks a single field's state.
 
 ```typescript
-function createRouterStores(): RouterStores
+function createFieldStore(controller: FormController<T>, name: K): Readable<FieldState<T[K]>>
 ```
 
-**Returns:** Router stores and actions
+- `controller` — Form controller
+- `name` — Field name to track
 
-#### `createRouterStoresFromRouter(router)`
+**Returns:** Readable store of the field state
 
-Create router stores from a specific router.
+#### `createWatchStore(controller, name)`
+
+Create a readable store that tracks a single field's value.
 
 ```typescript
-function createRouterStoresFromRouter(router: Router): RouterStores
+function createWatchStore(controller: FormController<T>, name: K): Readable<T[K]>
 ```
 
-- `router` — Router instance
+- `controller` — Form controller
+- `name` — Field name to watch
 
-**Returns:** Router stores and actions
+**Returns:** Readable store of the field value
 
-#### `createSignupStore()`
+#### `createHttpStore(method, url, config)`
 
-Creates a signup store with async state tracking.
+Create an HTTP request store.
 
 ```typescript
-function createSignupStore(): SignupStore<T>
+function createHttpStore(
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  url: string,
+  config?: RequestConfig,
+): HttpStore<T>
 ```
 
-**Returns:** Signup promise store
+- `method` — HTTP method
+- `url` — Request URL
+- `config` — Request configuration
 
-#### `createStorageHelpers()`
+**Returns:** Store with state and actions
 
-Create storage helper functions from context.
+#### `createGetStore(url, config)`
+
+Creates a GET request store.
 
 ```typescript
-function createStorageHelpers(): StorageHelpers
+function createGetStore(url: string, config?: RequestConfig): HttpStore<T>
 ```
 
-**Returns:** Storage functions
+- `url` — The request endpoint URL.
+- `config` — Optional request configuration such as headers or params.
 
-#### `createStorageStore(key, defaultValue)`
+**Returns:** A subscribable HTTP store for the GET request with execute and reset methods.
 
-Create a storage value store.
+#### `createPostStore(url, config)`
+
+Creates a POST request store.
 
 ```typescript
-function createStorageStore(key: string, defaultValue?: T): StorageStore<T>
+function createPostStore(url: string, config?: RequestConfig): HttpStore<T>
 ```
 
-- `key` — Storage key
-- `defaultValue` — Default value if not found
+- `url` — The request endpoint URL.
+- `config` — Optional request configuration such as headers or body data.
 
-**Returns:** Store with value and actions
+**Returns:** A subscribable HTTP store for the POST request with execute and reset methods.
 
-#### `createStorageStoreFromProvider(storage, key, defaultValue)`
+#### `createPutStore(url, config)`
 
-Create storage store from a specific provider.
+Creates a PUT request store.
 
 ```typescript
-function createStorageStoreFromProvider(
-  storage: StorageProvider,
-  key: string,
-  defaultValue?: T,
-): StorageStore<T>
+function createPutStore(url: string, config?: RequestConfig): HttpStore<T>
 ```
 
-- `storage` — Storage provider
-- `key` — Storage key
-- `defaultValue` — Default value
+- `url` — The request endpoint URL.
+- `config` — Optional request configuration such as headers or body data.
 
-**Returns:** Store with value and actions
+**Returns:** A subscribable HTTP store for the PUT request with execute and reset methods.
 
-#### `createStoreAction(store, action)`
+#### `createPatchStore(url, config)`
 
-Create a bound action for a store.
+Creates a PATCH request store.
 
 ```typescript
-function createStoreAction(
-  store: MoleculeStore<T>,
-  action: (
-    setState: MoleculeStore<T>['setState'],
-    getState: MoleculeStore<T>['getState'],
-  ) => (...args: Args) => R,
-): (...args: Args) => R
+function createPatchStore(url: string, config?: RequestConfig): HttpStore<T>
 ```
 
-- `store` — The store
-- `action` — Action creator function
+- `url` — The request endpoint URL.
+- `config` — Optional request configuration such as headers or body data.
 
-**Returns:** Bound action
+**Returns:** A subscribable HTTP store for the PATCH request with execute and reset methods.
 
-#### `createStoreReadable(store)`
+#### `createDeleteStore(url, config)`
 
-Create a readable Svelte store from a molecule store.
+Creates a DELETE request store.
 
 ```typescript
-function createStoreReadable(store: MoleculeStore<T>): Readable<T>
+function createDeleteStore(url: string, config?: RequestConfig): HttpStore<T>
 ```
 
-- `store` — The molecule store
+- `url` — The request endpoint URL.
+- `config` — Optional request configuration such as headers or params.
 
-**Returns:** Readable Svelte store
+**Returns:** A subscribable HTTP store for the DELETE request with execute and reset methods.
 
-#### `createStoreSelector(store, selector)`
+#### `createHttpStoresFromClient(client)`
 
-Create a derived Svelte store with a selector.
+Creates HTTP store factory methods bound to a specific client instance.
 
 ```typescript
-function createStoreSelector(store: MoleculeStore<T>, selector: (state: T) => S): Readable<S>
+function createHttpStoresFromClient(client: HttpClient): HttpStoreFactory
 ```
 
-- `store` — The molecule store
-- `selector` — Selector function
+- `client` — The HTTP client to use for all created stores.
 
-**Returns:** Derived Svelte store
+**Returns:** An object with get, post, put, patch, and delete factory methods.
 
-#### `createThemeColorsStore(theme)`
+#### `createI18nStores()`
 
-Create a derived store that returns just the theme colors.
+Create i18n stores from the i18n provider in context.
 
 ```typescript
-function createThemeColorsStore(theme: Readable<Theme>): Readable<ThemeColors>
+function createI18nStores(): I18nStores
 ```
 
-- `theme` — A readable theme store (from createThemeStores or createThemeStoresFromProvider)
+**Returns:** I18n stores and actions
 
-**Returns:** Readable store of theme colors
+#### `createI18nStoresFromProvider(provider)`
 
-#### `createThemeStores()`
+Create i18n stores from a specific provider.
 
-Create theme stores from the theme provider in context.
+```typescript
+function createI18nStoresFromProvider(provider: I18nProvider): I18nStores
+```
+
+- `provider` — I18n provider
+
+**Returns:** I18n stores and actions
+
+#### `getLogger(name)`
+
+Get a logger instance.
 
 ```typescript
-function createThemeStores(): ThemeStores & { colors: Readable<Theme['colors']> }
+function getLogger(name?: string): Logger
 ```
 
-**Returns:** Theme stores and actions
+- `name` — Logger name
 
-#### `createThemeStoresFromProvider(provider)`
+**Returns:** Logger instance
 
-Create theme stores from a specific theme provider.
+#### `createLogger(config)`
+
+Create a logger with custom configuration.
 
 ```typescript
-function createThemeStoresFromProvider(provider: ThemeProvider): ThemeStores
+function createLogger(config: LoggerConfig): Logger
 ```
 
-- `provider` — Theme provider
+- `config` — Logger configuration
 
-**Returns:** Theme stores and actions
+**Returns:** Logger instance
 
-#### `createVersionStores()`
+#### `getRootLogger()`
 
-Create version stores from the module-level version provider.
+Get the root logger.
 
 ```typescript
-function createVersionStores(): {
-  state: Readable<VersionState>
-  isUpdateAvailable: Readable<boolean>
-  isChecking: Readable<boolean>
-  isServiceWorkerWaiting: Readable<boolean>
-  newVersion: Readable<string | undefined>
-  checkForUpdates: () => Promise<boolean>
-  applyUpdate: (options?: { force?: boolean }) => void
-  dismissUpdate: () => void
-  startPeriodicChecks: (options?: UpdateCheckOptions) => void
-  stopPeriodicChecks: () => void
-}
+function getRootLogger(): Logger
 ```
 
-**Returns:** Version stores and actions
+**Returns:** Root logger instance
 
-#### `createWatchStore(controller, name)`
+#### `getChildLogger(name, context)`
 
-Create a readable store that tracks a single field's value.
+Create a child logger with additional context.
 
 ```typescript
-function createWatchStore(controller: FormController<T>, name: K): Readable<T[K]>
+function getChildLogger(name: string, context: Record<string, unknown>): Logger
 ```
 
-- `controller` — Form controller
-- `name` — Field name to watch
+- `name` — Parent logger name
+- `context` — Additional context
 
-**Returns:** Readable store of the field value
+**Returns:** Child logger instance
 
-#### `getAuthClient()`
+#### `createLoggerHelpers()`
 
-Gets the auth client from Svelte context.
+Create logger helpers from context.
 
 ```typescript
-function getAuthClient(): AuthClient<T>
+function createLoggerHelpers(): LoggerHelpers
 ```
 
-**Returns:** The auth client instance.
+**Returns:** Logger helper functions
+
+#### `createLoggerHelpersFromProvider(provider)`
+
+Create logger helpers from a specific provider.
+
+```typescript
+function createLoggerHelpersFromProvider(provider: LoggerProvider): LoggerHelpers
+```
+
+- `provider` — Logger provider
+
+**Returns:** Logger helper functions
+
+#### `createLoginStore()`
+
+Creates a login store with async state tracking.
+
+```typescript
+function createLoginStore(): LoginStore<T>
+```
+
+**Returns:** Login promise store
+
+#### `createOAuthHelpers(options)`
+
+Creates OAuth helpers for provider-based authentication flows.
 
-#### `getChildLogger(name, context)`
+When created in a browser, automatically handles OAuth callbacks by
+detecting `code` and `state` URL parameters and exchanging them for a
+session (a guarded no-op when there is no callback code in the URL).
 
-Create a child logger with additional context.
+Session establishment: the exchange result is applied to the resolved auth
+client (an explicit `options.authClient`, else the Svelte-context client
+when created during component initialization). When NO client is available,
+the server has already established the httpOnly-cookie session via the
+exchange, so a user-carrying response still counts as success —
+`options.onSuccess` fires; a response with no user fires `options.onError`.
 
 ```typescript
-function getChildLogger(name: string, context: Record<string, unknown>): Logger
+function createOAuthHelpers(options?: OAuthOptions): OAuthHelpers
 ```
 
-- `name` — Parent logger name
-- `context` — Additional context
+- `options` — OAuth configuration (base URL, providers, endpoint paths, callbacks, auth client).
 
-**Returns:** Child logger instance
+**Returns:** An object containing a readable providers store, URL builder, redirect function, and callback handler.
 
-#### `getHttpClient()`
+#### `createPasswordResetStores()`
 
-Gets the HTTP client from Svelte context.
+Creates password reset stores with async state tracking.
 
 ```typescript
-function getHttpClient(): HttpClient
+function createPasswordResetStores(): PasswordResetStores
 ```
 
-**Returns:** The HTTP client instance.
+**Returns:** Password reset stores for request and confirm steps
 
-#### `getI18nProvider()`
+#### `createPlatformStores()`
 
-Gets the i18n provider from Svelte context.
+Create platform stores from the module-level platform info.
+
+Platform information is static (no reactive subscription needed),
+so this returns plain values rather than Svelte stores.
 
 ```typescript
-function getI18nProvider(): I18nProvider
+function createPlatformStores(): {
+  platform: Platform
+  isNative: boolean
+  isMobile: boolean
+  isDesktop: boolean
+  isWeb: boolean
+  isDevelopment: boolean
+  isProduction: boolean
+  isPlatform: (...platforms: Platform[]) => boolean
+}
 ```
 
-**Returns:** The i18n provider instance.
+**Returns:** Platform information and utility functions
 
-#### `getLogger(name)`
+#### `createPromiseStore(asyncFn)`
 
-Get a logger instance.
+Creates a store that tracks async function state.
 
 ```typescript
-function getLogger(name?: string): Logger
+function createPromiseStore(asyncFn: T): PromiseStore<Awaited<ReturnType<T>>>
 ```
 
-- `name` — Logger name
+- `asyncFn` — The async function to track
 
-**Returns:** Logger instance
+**Returns:** Promise store with subscribe, call, cancel, and reset
 
-#### `getLoggerProvider()`
+#### `createPushStores()`
 
-Gets the logger provider from Svelte context.
+Create push notification stores from the module-level push provider.
 
 ```typescript
-function getLoggerProvider(): LoggerProvider
+function createPushStores(): {
+  permission: Readable<PermissionStatus | null>
+  token: Readable<PushToken | null>
+  checkPermission: () => Promise<PermissionStatus>
+  requestPermission: () => Promise<PermissionStatus>
+  register: (options?: PushRegisterOptions) => Promise<PushToken>
+  unregister: () => Promise<void>
+  onNotificationReceived: (listener: NotificationReceivedListener) => () => void
+  onNotificationAction: (listener: NotificationActionListener) => () => void
+  onTokenChange: (listener: TokenChangeListener) => () => void
+  setBadge: (count: number) => Promise<void>
+  clearBadge: () => Promise<void>
+}
 ```
 
-**Returns:** The logger provider instance.
+**Returns:** Push notification stores and actions
 
-#### `getRootLogger()`
+#### `createRouterStores()`
 
-Get the root logger.
+Create router stores from the router in context.
 
 ```typescript
-function getRootLogger(): Logger
+function createRouterStores(): RouterStores
 ```
 
-**Returns:** Root logger instance
+**Returns:** Router stores and actions
 
-#### `getRouter()`
+#### `createIsActiveStore(location, router, path, exact)`
 
-Gets the router from Svelte context.
+Create a derived store that checks if a path is active.
 
 ```typescript
-function getRouter(): Router
+function createIsActiveStore(
+  location: Readable<RouteLocation>,
+  router: Router,
+  path: string,
+  exact?: boolean,
+): Readable<boolean>
 ```
 
-**Returns:** The router instance.
+- `location` — A readable location store (from createRouterStores or createRouterStoresFromRouter)
+- `router` — Router instance (for isActive check)
+- `path` — Path to check
+- `exact` — Whether to require exact match (default: false)
 
-#### `getSetStore(store)`
+**Returns:** Readable store of whether the path is active
 
-Get the setState function from a molecule store.
+#### `createRouterStoresFromRouter(router)`
+
+Create router stores from a specific router.
 
 ```typescript
-function getSetStore(
-  store: MoleculeStore<T>,
-): (partial: Partial<T> | ((state: T) => Partial<T>)) => void
+function createRouterStoresFromRouter(router: Router): RouterStores
 ```
 
-- `store` — The molecule store
+- `router` — Router instance
 
-**Returns:** setState function
+**Returns:** Router stores and actions
 
-#### `getStateProvider()`
+#### `createSignupStore()`
 
-Gets the state provider from Svelte context.
+Creates a signup store with async state tracking.
 
 ```typescript
-function getStateProvider(): StateProvider
+function createSignupStore(): SignupStore<T>
 ```
 
-**Returns:** The state provider instance.
+**Returns:** Signup promise store
 
-#### `getStorageProvider()`
+#### `createStoreReadable(store)`
 
-Gets the storage provider from Svelte context.
+Create a readable Svelte store from a molecule store.
 
 ```typescript
-function getStorageProvider(): StorageProvider
+function createStoreReadable(store: MoleculeStore<T>): Readable<T>
 ```
 
-**Returns:** The storage provider instance.
+- `store` — The molecule store
 
-#### `getThemeProvider()`
+**Returns:** Readable Svelte store
 
-Gets the theme provider from Svelte context.
+#### `createStoreSelector(store, selector)`
+
+Create a derived Svelte store with a selector.
 
 ```typescript
-function getThemeProvider(): ThemeProvider
+function createStoreSelector(store: MoleculeStore<T>, selector: (state: T) => S): Readable<S>
 ```
 
-**Returns:** The theme provider instance.
+- `store` — The molecule store
+- `selector` — Selector function
 
-#### `setAuthContext(client)`
+**Returns:** Derived Svelte store
 
-Sets the auth context.
+#### `getSetStore(store)`
+
+Get the setState function from a molecule store.
 
 ```typescript
-function setAuthContext(client: AuthClient<T>): void
+function getSetStore(
+  store: MoleculeStore<T>,
+): (partial: Partial<T> | ((state: T) => Partial<T>)) => void
 ```
 
-- `client` — The auth client to store in Svelte context.
+- `store` — The molecule store
 
-#### `setHttpContext(client)`
+**Returns:** setState function
 
-Sets the HTTP context.
+#### `createStoreAction(store, action)`
+
+Create a bound action for a store.
 
 ```typescript
-function setHttpContext(client: HttpClient): void
+function createStoreAction(
+  store: MoleculeStore<T>,
+  action: (
+    setState: MoleculeStore<T>['setState'],
+    getState: MoleculeStore<T>['getState'],
+  ) => (...args: Args) => R,
+): (...args: Args) => R
 ```
 
-- `client` — The HTTP client to store in Svelte context.
+- `store` — The store
+- `action` — Action creator function
 
-#### `setI18nContext(provider)`
+**Returns:** Bound action
 
-Sets the i18n context.
+#### `createStorageStore(key, defaultValue)`
+
+Create a storage value store.
 
 ```typescript
-function setI18nContext(provider: I18nProvider): void
+function createStorageStore(key: string, defaultValue?: T): StorageStore<T>
 ```
 
-- `provider` — The i18n provider to store in Svelte context.
+- `key` — Storage key
+- `defaultValue` — Default value if not found
 
-#### `setLoggerContext(provider)`
+**Returns:** Store with value and actions
 
-Sets the logger context.
+#### `createStorageHelpers()`
+
+Create storage helper functions from context.
 
 ```typescript
-function setLoggerContext(provider: LoggerProvider): void
+function createStorageHelpers(): StorageHelpers
 ```
 
-- `provider` — The logger provider to store in Svelte context.
-
-#### `setMoleculeContext(config)`
+**Returns:** Storage functions
 
-Set all molecule providers in Svelte context.
+#### `createStorageStoreFromProvider(storage, key, defaultValue)`
 
-Call this in your root layout/component.
+Create storage store from a specific provider.
 
 ```typescript
-function setMoleculeContext(config: MoleculeConfig): void
+function createStorageStoreFromProvider(
+  storage: StorageProvider,
+  key: string,
+  defaultValue?: T,
+): StorageStore<T>
 ```
 
-- `config` — Provider instances to register (state, auth, theme, router, i18n, http, storage, logger).
+- `storage` — Storage provider
+- `key` — Storage key
+- `defaultValue` — Default value
 
-#### `setRouterContext(router)`
+**Returns:** Store with value and actions
 
-Sets the router context.
+#### `createThemeStores()`
+
+Create theme stores from the theme provider in context.
 
 ```typescript
-function setRouterContext(router: Router): void
+function createThemeStores(): ThemeStores & { colors: Readable<Theme['colors']> }
 ```
 
-- `router` — The router instance to store in Svelte context.
+**Returns:** Theme stores and actions
 
-#### `setStateContext(provider)`
+#### `createThemeColorsStore(theme)`
 
-Sets the state context.
+Create a derived store that returns just the theme colors.
 
 ```typescript
-function setStateContext(provider: StateProvider): void
+function createThemeColorsStore(theme: Readable<Theme>): Readable<ThemeColors>
 ```
 
-- `provider` — The state provider to store in Svelte context.
+- `theme` — A readable theme store (from createThemeStores or createThemeStoresFromProvider)
 
-#### `setStorageContext(provider)`
+**Returns:** Readable store of theme colors
 
-Sets the storage context.
+#### `createThemeStoresFromProvider(provider)`
+
+Create theme stores from a specific theme provider.
 
 ```typescript
-function setStorageContext(provider: StorageProvider): void
+function createThemeStoresFromProvider(provider: ThemeProvider): ThemeStores
 ```
 
-- `provider` — The storage provider to store in Svelte context.
+- `provider` — Theme provider
 
-#### `setThemeContext(provider)`
+**Returns:** Theme stores and actions
 
-Sets the theme context.
+#### `createVersionStores()`
+
+Create version stores from the module-level version provider.
 
 ```typescript
-function setThemeContext(provider: ThemeProvider): void
+function createVersionStores(): {
+  state: Readable<VersionState>
+  isUpdateAvailable: Readable<boolean>
+  isChecking: Readable<boolean>
+  isServiceWorkerWaiting: Readable<boolean>
+  newVersion: Readable<string | undefined>
+  checkForUpdates: () => Promise<boolean>
+  applyUpdate: (options?: { force?: boolean }) => void
+  dismissUpdate: () => void
+  startPeriodicChecks: (options?: UpdateCheckOptions) => void
+  stopPeriodicChecks: () => void
+}
 ```
 
-- `provider` — The theme provider to store in Svelte context.
+**Returns:** Version stores and actions
 
 ## Injection Notes