@molecule/app-solid 1.0.0

package/README.md

@@ -0,0 +1,2543 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-08-04T00:41:07.786Z
+-->
+
+# @molecule/app-solid
+
+> **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.
+
+Solid.js framework bindings for molecule.dev.
+
+Provides Solid-specific implementations of molecule.dev core interfaces
+using Solid's reactive primitives (signals, effects, resources): wrap the
+app in `MoleculeProvider` with a `config` of providers, then consume them
+through `createAuth`, `createTheme`, `createRouter`, `createI18n`, and the
+other primitives.
+
+## Quick Start
+
+```tsx
+import { MoleculeProvider, createAuth, createTheme } from '@molecule/app-solid'
+import { Show } from 'solid-js'
+import { provider as stateProvider } from '@molecule/app-state-zustand'
+import { provider as themeProvider } from '@molecule/app-theme-css-variables'
+import { createJWTAuthClient } from '@molecule/app-auth'
+
+const authClient = createJWTAuthClient({ baseURL: '/api' })
+
+function UserProfile() {
+  const { user, isAuthenticated, logout } = createAuth<{ name?: string }>()
+  const { theme, toggleTheme } = createTheme()
+
+  return (
+    <Show when={isAuthenticated()} fallback={<a href="/login">Log in</a>}>
+      <div style={{ background: theme().colors.background }}>
+        <h1>Welcome, {user()?.name}</h1>
+        <button onClick={toggleTheme}>Toggle Theme</button>
+        <button onClick={() => logout()}>Logout</button>
+      </div>
+    </Show>
+  )
+}
+
+function App() {
+  return (
+    <MoleculeProvider config={{ state: stateProvider, auth: authClient, theme: themeProvider }}>
+      <UserProfile />
+    </MoleculeProvider>
+  )
+}
+```
+
+## Type
+
+`framework`
+
+## Installation
+
+```bash
+npm install @molecule/app-solid @molecule/app-auth @molecule/app-device @molecule/app-forms @molecule/app-http @molecule/app-i18n @molecule/app-logger @molecule/app-platform @molecule/app-push @molecule/app-routing @molecule/app-state @molecule/app-storage @molecule/app-theme @molecule/app-ui @molecule/app-utilities @molecule/app-version solid-js
+```
+
+## API
+
+### Interfaces
+
+#### `AuthClient`
+
+Auth client interface that all auth bond packages must implement.
+Provides login/logout/register flows, token management, profile
+updates, and auth state subscription.
+
+```typescript
+interface AuthClient<T = UserProfile> {
+  /**
+   * Returns the current authentication state snapshot.
+   */
+  getState(): AuthState<T>
+  /**
+   * Returns whether the user is currently authenticated.
+   */
+  isAuthenticated(): boolean
+  /**
+   * Gets the current user.
+   */
+  getUser(): T | null
+  /**
+   * Updates the cached user object (state + persistent storage) without
+   * hitting the network. Intended for local refreshes after a per-app
+   * mutation (e.g., the user just PATCHed their own profile and the
+   * server returned the canonical row). Does NOT change tokens.
+   */
+  setUser(user: T | null): void
+  /**
+   * Gets the current access token.
+   */
+  getAccessToken(): string | null
+  /**
+   * Stores the access token in the configured token storage adapter (in-memory
+   * by default). Use this to seed the token after an out-of-band exchange (e.g.
+   * the OAuth code→token redirect) instead of writing to `localStorage` directly,
+   * which would violate the in-memory-default storage contract and make the bearer
+   * token JS-readable (XSS-exfiltratable). Pass `null` to clear it.
+   */
+  setAccessToken(token: string | null): void
+  /**
+   * Gets the refresh token.
+   */
+  getRefreshToken(): string | null
+  /**
+   * Logs in with credentials.
+   */
+  login(credentials: LoginCredentials): Promise<AuthResult<T>>
+  /**
+   * Logs out the current user.
+   */
+  logout(): Promise<void>
+  /**
+   * Registers a new user.
+   */
+  register(data: RegisterData): Promise<AuthResult<T>>
+  /**
+   * Refreshes the access token.
+   */
+  refresh(): Promise<AuthResult<T>>
+  /**
+   * Requests a password reset.
+   */
+  requestPasswordReset(data: PasswordResetRequest): Promise<void>
+  /**
+   * Confirms a password reset.
+   */
+  confirmPasswordReset(data: PasswordResetConfirm): Promise<void>
+  /**
+   * Updates the current user's profile.
+   */
+  updateProfile(data: Partial<T>): Promise<T>
+  /**
+   * Changes the current user's password.
+   */
+  changePassword(oldPassword: string, newPassword: string): Promise<void>
+  /**
+   * Initializes auth state (e.g., from stored tokens).
+   */
+  initialize(): Promise<void>
+  /**
+   * Subscribes to auth state changes.
+   */
+  subscribe(callback: (state: AuthState<T>) => void): () => void
+  /**
+   * Subscribes to auth state changes (alias for subscribe).
+   */
+  onAuthChange(callback: (state: AuthState<T>) => void): () => void
+  /**
+   * Gets the current access token (alias for getAccessToken).
+   */
+  getToken?(): string | null
+  /**
+   * Adds an auth event listener.
+   */
+  addEventListener(listener: AuthEventListener): () => void
+  /**
+   * Destroys the auth client.
+   */
+  destroy(): void
+}
+```
+
+#### `AuthPrimitives`
+
+Auth primitives return type.
+
+```typescript
+interface AuthPrimitives<T = unknown> {
+  state: Accessor<AuthState<T>>
+  user: Accessor<T | null>
+  isAuthenticated: Accessor<boolean>
+  isLoading: Accessor<boolean>
+  login: AuthClient<T>['login']
+  logout: AuthClient<T>['logout']
+  register: AuthClient<T>['register']
+  refresh: AuthClient<T>['refresh']
+}
+```
+
+#### `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
+}
+```
+
+#### `CapacitorAppPrimitives`
+
+Capacitor app primitives return type.
+
+```typescript
+interface CapacitorAppPrimitives {
+  state: Accessor<CapacitorAppState>
+  ready: Accessor<boolean>
+  initialize: () => Promise<void>
+}
+```
+
+#### `CreateAsyncStateReturn`
+
+Return type for createAsyncState.
+
+```typescript
+interface CreateAsyncStateReturn<T> {
+  state: () => 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
+}
+```
+
+#### `CreateChangePasswordReturn`
+
+Return type for createChangePassword primitive.
+
+```typescript
+interface CreateChangePasswordReturn {
+  state: Accessor<PromiseState<void>>
+  changePassword: (oldPassword: string, newPassword: string) => Promise<void>
+  reset: () => void
+}
+```
+
+#### `CreateFormResult`
+
+Result of createForm primitive.
+
+```typescript
+interface CreateFormResult<T extends Record<string, unknown>> {
+  /** Reactive form state accessor. */
+  formState: Accessor<FormState<T>>
+
+  /** Whether the form is currently valid. */
+  isValid: Accessor<boolean>
+
+  /** Whether any field has been modified. */
+  isDirty: Accessor<boolean>
+
+  /** Whether the form is currently submitting. */
+  isSubmitting: Accessor<boolean>
+
+  /** Current field errors. */
+  errors: Accessor<Partial<Record<keyof T, string>>>
+
+  /** Register a field for form management. */
+  register: (name: keyof T, options?: RegisterOptions) => FieldRegistration
+
+  /** Get the current value of a field. */
+  getValue: <K extends keyof T>(name: K) => T[K]
+
+  /** Set the value of a field. */
+  setValue: <K extends keyof T>(name: K, value: T[K]) => void
+
+  /** Get the error message for a field. */
+  getError: (name: keyof T) => string | undefined
+
+  /** Set an error message for a field. */
+  setError: (name: keyof T, error: string | undefined) => void
+
+  /** Clear all field errors. */
+  clearErrors: () => void
+
+  /** Create a submit handler function. */
+  handleSubmit: (
+    onSubmit: (values: T) => void | Promise<void>,
+  ) => (event?: { preventDefault?: () => void }) => Promise<void>
+
+  /** Reset the form to initial or provided values. */
+  reset: (values?: Partial<T>) => void
+
+  /** Validate all fields. */
+  validate: () => Promise<boolean>
+
+  /** The raw FormController instance for advanced use. */
+  controller: FormController<T>
+}
+```
+
+#### `CreateLoginReturn`
+
+Return type for createLogin primitive.
+
+```typescript
+interface CreateLoginReturn<T = unknown> {
+  state: Accessor<PromiseState<AuthResult<T>>>
+  login: (credentials: LoginCredentials) => Promise<AuthResult<T>>
+  reset: () => void
+}
+```
+
+#### `CreateOAuthOptions`
+
+OAuth configuration options.
+
+```typescript
+interface CreateOAuthOptions {
+  /** Base URL for the API server (e.g. `https://api.example.com`). */
+  baseURL?: string
+  /** List of supported OAuth provider names (e.g. `['github', 'google']`). */
+  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
+  /** Called after a successful OAuth login (session established). */
+  onSuccess?: () => void
+  /** Called with a failure message when the OAuth login fails. */
+  onError?: (error: string) => void
+  /**
+   * Auth client used to establish the session after the code exchange.
+   * Overrides context resolution — when omitted, the client is resolved from
+   * the surrounding `MoleculeProvider` (tolerated when absent; see the
+   * cookie-session fallback documented on
+   * {@link CreateOAuthReturn.handleCallback}).
+   */
+  authClient?: AuthClient<unknown>
+}
+```
+
+#### `CreateOAuthReturn`
+
+Return type for createOAuth primitive.
+
+```typescript
+interface CreateOAuthReturn {
+  /** Accessor for the configured OAuth provider names. */
+  providers: Accessor<string[]>
+  /** Builds the OAuth initiation URL for a provider. */
+  getOAuthUrl: (provider: string) => string
+  /** Starts the full-page redirect flow for a provider. */
+  redirect: (provider: string) => void
+  /**
+   * Handles the OAuth callback: exchanges the `code` URL parameter for a
+   * session. Invoked automatically at creation (see {@link createOAuth});
+   * exposed for callers that need to re-run it manually. No-ops unless
+   * running in a browser with a `code` URL parameter and a stashed provider.
+   *
+   * When an auth client is available (explicit option or context), the
+   * session is established locally (`setAccessToken` + `setUser` +
+   * `initialize`). When no client is available, the server has already
+   * established the httpOnly-cookie session during the exchange, so a
+   * user-carrying response still counts as success.
+   */
+  handleCallback: () => Promise<void>
+}
+```
+
+#### `CreatePasswordResetReturn`
+
+Return type for createPasswordReset primitive.
+
+```typescript
+interface CreatePasswordResetReturn {
+  requestState: Accessor<PromiseState<void>>
+  confirmState: Accessor<PromiseState<void>>
+  requestReset: (data: PasswordResetRequest) => Promise<void>
+  confirmReset: (data: PasswordResetConfirm) => Promise<void>
+  reset: () => void
+}
+```
+
+#### `CreatePromiseReturn`
+
+Promise state accessor with actions.
+
+```typescript
+interface CreatePromiseReturn<T> {
+  state: () => PromiseState<T>
+  call: (...args: any[]) => Promise<T>
+  cancel: (message?: string) => void
+  reset: () => void
+}
+```
+
+#### `CreateSignupReturn`
+
+Return type for createSignup primitive.
+
+```typescript
+interface CreateSignupReturn<T = unknown> {
+  state: Accessor<PromiseState<AuthResult<T>>>
+  signup: (data: RegisterData) => Promise<AuthResult<T>>
+  reset: () => void
+}
+```
+
+#### `DevicePrimitives`
+
+Device primitives return type.
+
+```typescript
+interface DevicePrimitives {
+  deviceInfo: DeviceInfo
+  screenInfo: ScreenInfo
+  hardwareInfo: HardwareInfo
+  featureSupport: FeatureSupport
+  supports: (feature: keyof FeatureSupport) => boolean
+  isOnline: () => boolean
+  isStandalone: () => boolean
+  language: string
+  languages: string[]
+}
+```
+
+#### `FormController`
+
+Form controller interface.
+
+All form providers must implement this interface.
+
+```typescript
+interface FormController<T extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * Gets the current form state.
+   */
+  getState(): FormState<T>
+  /**
+   * Gets the value of a specific field.
+   */
+  getValue(name: string): unknown
+  getValue<K extends keyof T>(name: K): T[K]
+  /**
+   * Gets all form values.
+   */
+  getValues(): T
+  /**
+   * Sets the value of a specific field.
+   */
+  setValue(
+    name: string,
+    value: unknown,
+    options?: {
+      shouldValidate?: boolean
+      shouldDirty?: boolean
+      shouldTouch?: boolean
+    },
+  ): void
+  /**
+   * Sets multiple values at once.
+   */
+  setValues(
+    values: Partial<T>,
+    options?: {
+      shouldValidate?: boolean
+    },
+  ): void
+  /**
+   * Gets the error for a specific field.
+   */
+  getError(name: string): string | undefined
+  /**
+   * Sets the error for a specific field.
+   */
+  setError(name: string, error: string | undefined): void
+  /**
+   * Clears the error for a specific field.
+   */
+  clearError<K extends keyof T>(name: K): void
+  /**
+   * Clears all errors.
+   */
+  clearErrors(): void
+  /**
+   * Gets the field state for a specific field.
+   */
+  getFieldState<K extends keyof T>(name: K): FieldState<T[K]>
+  /**
+   * Registers a field for form management.
+   */
+  register(nameOrOptions: string | RegisterOptions, options?: RegisterOptions): FieldRegistration
+  /**
+   * Unregisters a field.
+   */
+  unregister(name: string): void
+  /**
+   * Validates a specific field.
+   */
+  validateField<K extends keyof T>(name: K): Promise<boolean>
+  /**
+   * Validates all fields.
+   */
+  validate(): Promise<boolean>
+  /**
+   * Resets the form to initial values.
+   */
+  reset(values?: Partial<T>): void
+  /**
+   * Handles form submission.
+   */
+  handleSubmit(
+    onSubmit: (values: T) => void | Promise<void>,
+    onError?: (errors: Partial<Record<keyof T, string>>) => void,
+  ): (event?: { preventDefault?: () => void }) => Promise<void>
+  /**
+   * Sets focus to a field.
+   */
+  setFocus(name: keyof T): void
+  /**
+   * Subscribes to form state changes.
+   */
+  subscribe(callback: (state: FormState<T>) => void): () => void
+  /**
+   * Destroys the form controller.
+   */
+  destroy(): void
+}
+```
+
+#### `FormOptions`
+
+Form creation options.
+
+```typescript
+interface FormOptions<T extends Record<string, unknown>> {
+  /**
+   * Default values.
+   */
+  defaultValues?: Partial<T>
+  /**
+   * Validation mode.
+   */
+  mode?: 'onSubmit' | 'onChange' | 'onBlur' | 'all'
+  /**
+   * Revalidation mode.
+   */
+  reValidateMode?: 'onChange' | 'onBlur' | 'onSubmit'
+  /**
+   * Whether to focus the first error field on submit.
+   */
+  shouldFocusError?: boolean
+  /**
+   * Form-level validation function.
+   */
+  validate?: (
+    values: T,
+  ) => Partial<Record<keyof T, string>> | Promise<Partial<Record<keyof T, string>>>
+}
+```
+
+#### `HttpClient`
+
+HTTP client interface.
+
+All HTTP providers must implement this interface.
+
+```typescript
+interface HttpClient {
+  /**
+   * Base URL for all requests.
+   */
+  baseURL: string
+  /**
+   * Default headers for all requests.
+   */
+  defaultHeaders: Record<string, string>
+  /**
+   * Makes a generic HTTP request.
+   */
+  request<T = unknown>(config: FullRequestConfig): Promise<HttpResponse<T>>
+  /**
+   * Makes a GET request.
+   */
+  get<T = unknown>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>
+  /**
+   * Makes a POST request.
+   */
+  post<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
+  /**
+   * Makes a PUT request.
+   */
+  put<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
+  /**
+   * Makes a PATCH request.
+   */
+  patch<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
+  /**
+   * Makes a DELETE request.
+   */
+  delete<T = unknown>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>
+  /**
+   * Adds a request interceptor.
+   * Returns a function to remove the interceptor.
+   */
+  addRequestInterceptor(interceptor: RequestInterceptor): () => void
+  /**
+   * Adds a response interceptor.
+   * Returns a function to remove the interceptor.
+   */
+  addResponseInterceptor(interceptor: ResponseInterceptor): () => void
+  /**
+   * Adds an error interceptor.
+   * Returns a function to remove the interceptor.
+   */
+  addErrorInterceptor(interceptor: ErrorInterceptor): () => void
+  /**
+   * Sets the authorization token.
+   */
+  setAuthToken(token: string | null): void
+  /**
+   * Returns the current authorization token, or `null` if not set.
+   */
+  getAuthToken(): string | null
+  /**
+   * Registers a handler for authentication errors (401).
+   *
+   * @returns An unsubscribe function.
+   */
+  onAuthError(handler: () => void): () => void
+}
+```
+
+#### `HttpState`
+
+State for async HTTP operations.
+
+```typescript
+interface HttpState<T> {
+  data: T | null
+  loading: boolean
+  error: Error | null
+}
+```
+
+#### `I18nProvider`
+
+i18n provider interface.
+
+All i18n providers must implement this interface.
+
+```typescript
+interface I18nProvider {
+  /**
+   * Gets the current locale.
+   */
+  getLocale(): string
+  /**
+   * Sets the current locale.
+   *
+   * **Fleet contract:** every conformant provider (the core simple provider,
+   * `@molecule/api-i18n-simple`, `@molecule/app-i18n-i18next`, and
+   * `@molecule/app-i18n-react-i18next`) MUST throw `Error('Locale "<code>"
+   * not found')` when `locale` is not registered — via the constructor's
+   * `initialLocales`/`locales` config, `addLocale()`, or `addTranslations()`
+   * (all three register a locale). It must NOT silently degrade to
+   * fallback-locale text while `getLocale()` reports the unregistered code —
+   * that divergence makes a misconfigured locale switch indistinguishable
+   * from a working one until a user notices the wrong language on screen.
+   */
+  setLocale(locale: string): Promise<void>
+  /**
+   * Gets all available locales.
+   */
+  getLocales(): LocaleConfig[]
+  /**
+   * Adds a locale.
+   */
+  addLocale(config: LocaleConfig): void
+  /**
+   * Removes a locale by code, notifying subscribers so language pickers
+   * built on `onLocaleChange` re-render their list. If the removed locale
+   * is currently active, the caller is responsible for switching to a
+   * fallback (e.g. `'en'`) BEFORE calling this — the provider will not
+   * auto-fall-back on its own.
+   *
+   * Returns `true` if the locale was registered and removed, `false`
+   * otherwise.
+   */
+  removeLocale(code: string): boolean
+  /**
+   * Adds translations to a locale. Auto-creates the locale if it doesn't exist.
+   *
+   * **Fleet contract:** merges are DEEP, not a shallow spread — registering
+   * two calls (e.g. two modules) that share a top-level namespace key merges
+   * their subtrees instead of the second call clobbering the first's nested
+   * translations wholesale. `@molecule/api-i18n-simple` implements the same
+   * contract on the API side.
+   */
+  addTranslations(locale: string, translations: Translations, namespace?: string): void
+  /**
+   * Translates a key with optional interpolation values and pluralization.
+   *
+   * **Fleet plural contract (matches i18next's own key resolution order):**
+   * when `options.count` is provided, the plural-suffixed key
+   * (`` `${key}_${pluralForm}` ``, e.g. `item_one`/`item_few`/…, falling back
+   * to `` `${key}_other` ``) is looked up FIRST and wins over the base `key`
+   * if BOTH are registered. Only when no plural-suffixed key exists at all
+   * does resolution fall back to the base key. A catalog that ships both
+   * `item` and `item_one`/`item_other` therefore pluralizes identically
+   * whichever provider is bonded.
+   *
+   * @returns The translated string, or the default value / key if not found.
+   */
+  t(
+    key: string,
+    values?: InterpolationValues,
+    options?: {
+      defaultValue?: string
+      count?: number
+    },
+  ): string
+  /**
+   * Checks if a translation key exists.
+   *
+   * **Fleet contract:** follows the SAME locale-resolution chain as `t()` —
+   * the active locale, then the English fallback — so `exists(key) === true`
+   * whenever `t(key)` would render real translated text (not the raw key or
+   * an inline `defaultValue`). Do not narrow this to "only the active
+   * locale's own catalog"; that made `exists()` return `false` for keys `t()`
+   * happily rendered via the English fallback, and the answer differed by
+   * provider.
+   *
+   * @returns `true` if the key has a translation.
+   */
+  exists(key: string): boolean
+  /**
+   * Formats a number according to the current locale.
+   *
+   * @returns The locale-formatted number string.
+   */
+  formatNumber(value: number, options?: NumberFormatOptions): string
+  /**
+   * Formats a date according to the current locale.
+   *
+   * @returns The locale-formatted date string.
+   */
+  formatDate(value: Date | number | string, options?: DateFormatOptions): string
+  /**
+   * Formats a relative time (e.g. "2 hours ago").
+   *
+   * @returns The locale-formatted relative time string.
+   */
+  formatRelativeTime(
+    value: Date | number,
+    options?: {
+      unit?: Intl.RelativeTimeFormatUnit
+    },
+  ): string
+  /**
+   * Formats a list (e.g. "A, B, and C").
+   *
+   * @returns The locale-formatted list string.
+   */
+  formatList(
+    values: string[],
+    options?: {
+      type?: 'conjunction' | 'disjunction' | 'unit'
+    },
+  ): string
+  /**
+   * Subscribes to locale changes.
+   *
+   * @returns An unsubscribe function.
+   */
+  onLocaleChange(listener: (locale: string) => void): () => void
+  /**
+   * Gets the text direction for the current locale.
+   *
+   * @returns `'ltr'` or `'rtl'`.
+   */
+  getDirection(): 'ltr' | 'rtl'
+  /**
+   * Checks if a translation key exists (alias for exists).
+   */
+  hasKey?(key: string): boolean
+  /**
+   * Checks if the provider is ready.
+   */
+  isReady?(): boolean
+  /**
+   * Registers a callback for when the provider is ready.
+   */
+  onReady?(callback: () => void): () => void
+  /**
+   * Registers a lazily-loaded content module for automatic reload on locale changes.
+   * All registered content is reloaded during `setLocale()` before listeners fire,
+   * ensuring content is available on the first re-render with no flash.
+   *
+   * Idempotent: registering the same module name twice is a no-op.
+   */
+  registerContent?(module: string, loader: (locale: string) => Promise<void>): void
+}
+```
+
+#### `Logger`
+
+Logger instance with leveled logging methods, child logger creation,
+and transport management.
+
+```typescript
+interface Logger {
+  /**
+   * Logs a trace message.
+   */
+  trace(message: string, ...args: unknown[]): void
+  /**
+   * Logs a debug message.
+   */
+  debug(message: string, ...args: unknown[]): void
+  /**
+   * Logs an info message.
+   */
+  info(message: string, ...args: unknown[]): void
+  /**
+   * Logs a warning message.
+   */
+  warn(message: string, ...args: unknown[]): void
+  /**
+   * Logs an error message.
+   */
+  error(message: string | Error, ...args: unknown[]): void
+  /**
+   * Sets the log level.
+   */
+  setLevel(level: LogLevel): void
+  /**
+   * Gets the current log level.
+   */
+  getLevel(): LogLevel
+  /**
+   * Creates a child logger with a namespace.
+   */
+  child(name: string, context?: Record<string, unknown>): Logger
+  /**
+   * Adds additional context to the logger.
+   */
+  withContext(context: Record<string, unknown>): Logger
+  /**
+   * Adds a transport.
+   */
+  addTransport(transport: LogTransport): () => void
+  /**
+   * Removes a transport.
+   */
+  removeTransport(transport: LogTransport): void
+}
+```
+
+#### `LoggerProvider`
+
+Logger provider interface that all logger bond packages must implement.
+Creates and manages logger instances and global log configuration.
+
+```typescript
+interface LoggerProvider {
+  /**
+   * Gets a logger by name, or the root logger if no name given.
+   */
+  getLogger(name?: string): Logger
+  /**
+   * Creates a named logger.
+   */
+  createLogger(nameOrConfig: string | LoggerConfig, config?: LoggerConfig): Logger
+  /**
+   * Sets the global log level.
+   */
+  setLevel(level: LogLevel): void
+  /**
+   * Gets the global log level.
+   */
+  getLevel(): LogLevel
+  /**
+   * Adds a global transport.
+   */
+  addTransport(transport: LogTransport): () => void
+  /**
+   * Enables logging.
+   */
+  enable(): void
+  /**
+   * Disables logging.
+   */
+  disable(): void
+  /**
+   * Checks if logging is enabled.
+   *
+   * @returns `true` if logging is currently enabled.
+   */
+  isEnabled(): boolean
+}
+```
+
+#### `MoleculeConfig`
+
+Configuration for molecule Solid 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
+}
+```
+
+#### `PlatformPrimitives`
+
+Platform primitives return type.
+
+```typescript
+interface PlatformPrimitives {
+  platform: Platform
+  isNative: boolean
+  isMobile: boolean
+  isDesktop: boolean
+  isWeb: boolean
+  isDevelopment: boolean
+  isProduction: boolean
+  isPlatform: (...platforms: Platform[]) => boolean
+}
+```
+
+#### `PushPrimitives`
+
+Push primitives return type.
+
+```typescript
+interface PushPrimitives {
+  permission: Accessor<PermissionStatus | null>
+  token: Accessor<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>
+}
+```
+
+#### `RouteLocation`
+
+Current URL decomposed into pathname, search string, hash, navigation state, and unique key.
+
+```typescript
+interface RouteLocation {
+  /**
+   * Current pathname.
+   */
+  pathname: string
+  /**
+   * Query string (including leading ?).
+   */
+  search: string
+  /**
+   * Hash (including leading #).
+   */
+  hash: string
+  /**
+   * State data passed with navigation.
+   */
+  state?: unknown
+  /**
+   * Unique key for this location.
+   */
+  key?: string
+}
+```
+
+#### `Router`
+
+Client-side router providing navigation, guards, route matching, and history control.
+
+All routing providers must implement this interface.
+
+```typescript
+interface Router {
+  /**
+   * Returns the current route location (pathname, search, hash, state).
+   */
+  getLocation(): RouteLocation
+  /**
+   * Gets the current route params.
+   */
+  getParams<T extends RouteParams = RouteParams>(): T
+  /**
+   * Gets the current query params.
+   */
+  getQuery(): QueryParams
+  /**
+   * Gets a specific query parameter.
+   */
+  getQueryParam(key: string): string | undefined
+  /**
+   * Gets the current hash.
+   */
+  getHash(): string
+  /**
+   * Navigates to a path.
+   */
+  navigate(path: string, options?: NavigateOptions): void
+  /**
+   * Navigates to a named route.
+   */
+  navigateTo(
+    name: string,
+    params?: RouteParams,
+    query?: QueryParams,
+    options?: NavigateOptions,
+  ): void
+  /**
+   * Goes back in history.
+   */
+  back(): void
+  /**
+   * Goes forward in history.
+   */
+  forward(): void
+  /**
+   * Goes to a specific point in history.
+   */
+  go(delta: number): void
+  /**
+   * Updates the current query params.
+   */
+  setQuery(params: QueryParams, options?: NavigateOptions): void
+  /**
+   * Updates a specific query parameter.
+   */
+  setQueryParam(key: string, value: string | undefined, options?: NavigateOptions): void
+  /**
+   * Updates the current hash.
+   */
+  setHash(hash: string, options?: NavigateOptions): void
+  /**
+   * Checks if a path matches the current location.
+   *
+   * @returns `true` if the path matches the current route.
+   */
+  isActive(path: string, exact?: boolean): boolean
+  /**
+   * Matches a path pattern against a pathname.
+   */
+  matchPath<Params extends RouteParams = RouteParams>(
+    pattern: string,
+    pathname: string,
+  ): RouteMatch<Params> | null
+  /**
+   * Generates a URL from a named route.
+   */
+  generatePath(name: string, params?: RouteParams, query?: QueryParams): string
+  /**
+   * Subscribes to route changes.
+   */
+  subscribe(listener: RouteChangeListener): () => void
+  /**
+   * Adds a navigation guard.
+   */
+  addGuard(guard: NavigationGuard): () => void
+  /**
+   * Registers route definitions.
+   */
+  registerRoutes(routes: RouteDefinition[]): void
+  /**
+   * Gets all registered routes.
+   */
+  getRoutes(): RouteDefinition[]
+  /**
+   * Destroys the router.
+   */
+  destroy(): void
+}
+```
+
+#### `RouterPrimitives`
+
+Router primitives return type.
+
+```typescript
+interface RouterPrimitives {
+  location: Accessor<RouteLocation>
+  params: Accessor<RouteParams>
+  query: Accessor<QueryParams>
+  navigate: Router['navigate']
+  navigateTo: Router['navigateTo']
+  back: Router['back']
+  forward: Router['forward']
+  isActive: Router['isActive']
+}
+```
+
+#### `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`
+
+Storage provider interface.
+
+All storage providers must implement this interface.
+
+```typescript
+interface StorageProvider {
+  /**
+   * Gets a value from storage.
+   */
+  get<T = unknown>(key: string): Promise<T | null>
+  /**
+   * Sets a value in storage.
+   */
+  set<T = unknown>(key: string, value: T): Promise<void>
+  /**
+   * Removes a value from storage.
+   */
+  remove(key: string): Promise<void>
+  /**
+   * Clears all values from storage.
+   */
+  clear(): Promise<void>
+  /**
+   * Gets all keys in storage.
+   */
+  keys(): Promise<string[]>
+  /**
+   * Gets multiple values from storage.
+   */
+  getMany?<T = unknown>(keys: string[]): Promise<Map<string, T | null>>
+  /**
+   * Sets multiple values in storage.
+   */
+  setMany?<T = unknown>(entries: Array<[string, T]>): Promise<void>
+  /**
+   * Removes multiple values from storage.
+   */
+  removeMany?(keys: string[]): Promise<void>
+}
+```
+
+#### `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
+}
+```
+
+#### `ThemePrimitives`
+
+Theme primitives return type.
+
+```typescript
+interface ThemePrimitives {
+  theme: Accessor<Theme>
+  themeName: Accessor<string>
+  mode: Accessor<'light' | 'dark'>
+  setTheme: (name: string) => void
+  toggleTheme: () => void
+}
+```
+
+#### `ThemeProvider`
+
+Manages theme state including the active theme, mode toggling,
+and change subscriptions.
+
+```typescript
+interface ThemeProvider {
+  /**
+   * Returns the currently active theme.
+   */
+  getTheme(): Theme
+  /**
+   * Sets the active theme by reference or by name.
+   *
+   * @param theme - A `Theme` object or a theme name string to activate.
+   */
+  setTheme(theme: Theme | string): void
+  /**
+   * Toggles between light and dark mode for the active theme.
+   */
+  toggleMode(): void
+  /**
+   * Subscribes to theme changes. The callback fires whenever
+   * `setTheme()` or `toggleMode()` is called.
+   *
+   * @param callback - Invoked with the new theme after each change.
+   * @returns An unsubscribe function.
+   */
+  subscribe(callback: (theme: Theme) => void): () => void
+  /**
+   * Returns all registered themes. Optional — not all providers
+   * support multiple themes.
+   */
+  getThemes?(): Theme[]
+}
+```
+
+#### `VersionPrimitives`
+
+Version primitives return type.
+
+```typescript
+interface VersionPrimitives {
+  state: Accessor<VersionState>
+  isUpdateAvailable: Accessor<boolean>
+  isChecking: Accessor<boolean>
+  isServiceWorkerWaiting: Accessor<boolean>
+  newVersion: Accessor<string | undefined>
+  checkForUpdates: () => Promise<boolean>
+  applyUpdate: (options?: { force?: boolean }) => void
+  dismissUpdate: () => void
+  startPeriodicChecks: (options?: UpdateCheckOptions) => void
+  stopPeriodicChecks: () => void
+}
+```
+
+### Types
+
+#### `Accessor`
+
+```typescript
+type Accessor<T> = () => T
+```
+
+#### `QueryParams`
+
+URL query string parameter map (single values or arrays for repeated keys).
+
+```typescript
+type QueryParams = Record<string, string | string[] | undefined>
+```
+
+#### `RouteParams`
+
+URL path parameter key-value map extracted from dynamic route segments (e.g. `{ id: '123' }`).
+
+```typescript
+type RouteParams = Record<string, string>
+```
+
+#### `Setter`
+
+```typescript
+type Setter<in out T> = {
+  <U extends T>(
+    ...args: undefined extends T ? [] : [value: Exclude<U, Function> | ((prev: T) => U)]
+  ): undefined extends T ? undefined : U
+  <U extends T>(value: (prev: T) => U): U
+  <U extends T>(value: Exclude<U, Function>): U
+  <U extends T>(value: Exclude<U, Function> | ((prev: T) => U)): U
+}
+```
+
+### Functions
+
+#### `applyThemeToDocument()`
+
+Apply theme CSS variables to document.
+
+```typescript
+function applyThemeToDocument(): void
+```
+
+#### `createAsyncState(initialState)`
+
+Primitive like createSignal but accepts Promises and supports partial state extension.
+
+```typescript
+function createAsyncState(initialState: T): CreateAsyncStateReturn<T>
+```
+
+- `initialState` — Initial state value
+
+**Returns:** The created instance.
+
+#### `createAuth()`
+
+Create auth primitives for authentication state and actions.
+
+```typescript
+function createAuth(): AuthPrimitives<T>
+```
+
+**Returns:** Auth primitives object
+
+#### `createAuthFromClient(client)`
+
+Create auth primitives from a specific client.
+
+```typescript
+function createAuthFromClient(client: AuthClient<T>): AuthPrimitives<T>
+```
+
+- `client` — Auth client
+
+**Returns:** Auth primitives
+
+#### `createAuthGuard(redirectTo)`
+
+Create a guard primitive that redirects unauthenticated users.
+
+```typescript
+function createAuthGuard(redirectTo: string): Accessor<boolean>
+```
+
+- `redirectTo` — Path to redirect to
+
+**Returns:** Accessor indicating if user is allowed
+
+#### `createAuthHelpers()`
+
+Creates a auth helpers.
+
+```typescript
+function createAuthHelpers(): {
+  login: (credentials: LoginCredentials) => Promise<AuthResult<T>>
+  logout: () => Promise<void>
+  register: (data: RegisterData) => Promise<AuthResult<T>>
+  refresh: () => Promise<AuthResult<T>>
+  getUser: () => T | null
+  getToken: () => string | null
+  isAuthenticated: () => boolean
+}
+```
+
+**Returns:** The created result.
+
+#### `createCapacitorApp(options)`
+
+Create Capacitor app primitives for native app initialization.
+
+Wraps the core `createCapacitorApp` coordinator with Solid signals,
+automatically initializing and cleaning up on disposal.
+
+```typescript
+function createCapacitorApp(options?: CapacitorAppOptions): CapacitorAppPrimitives
+```
+
+- `options` — Capacitor app configuration options.
+
+**Returns:** Capacitor app primitives object
+
+#### `createChangePassword()`
+
+Creates a change password primitive with async state tracking.
+
+```typescript
+function createChangePassword(): CreateChangePasswordReturn
+```
+
+**Returns:** Change password state and action
+
+#### `createDevice()`
+
+Create device primitives for accessing device information.
+
+This is a static primitive (no reactive signals) since device info
+does not change during the lifecycle of the app.
+
+```typescript
+function createDevice(): DevicePrimitives
+```
+
+**Returns:** Device primitives object
+
+#### `createFieldSignal(controller, name)`
+
+Create a reactive accessor for a single field's state.
+
+```typescript
+function createFieldSignal(
+  controller: FormController<T>,
+  name: keyof T,
+): Accessor<FieldState<T[keyof T]>>
+```
+
+- `controller` — Form controller
+- `name` — Field name to track
+
+**Returns:** Accessor for the field state
+
+#### `createForm(provider, options)`
+
+Create form primitives for form state management and validation.
+
+```typescript
+function createForm(provider: FormProvider, options: FormOptions<T>): CreateFormResult<T>
+```
+
+- `provider` — Form provider that creates controllers
+- `options` — Form configuration options
+
+**Returns:** Form primitives object
+
+#### `createFormFromController(controller)`
+
+Create form primitives from an existing controller.
+
+Useful when you have a controller created externally and want to
+wrap it with Solid reactivity.
+
+```typescript
+function createFormFromController(controller: FormController<T>): CreateFormResult<T>
+```
+
+- `controller` — An existing FormController
+
+**Returns:** Form primitives object
+
+#### `createFormHelpers(provider)`
+
+Creates a form helpers.
+
+```typescript
+function createFormHelpers(provider: FormProvider): {
+  createForm: <T extends Record<string, unknown>>(options: FormOptions<T>) => CreateFormResult<T>
+}
+```
+
+- `provider` — The provider implementation.
+
+**Returns:** The created result.
+
+#### `createHttp()`
+
+Creates a http.
+
+```typescript
+function createHttp(): {
+  get: <T>(url: string, config?: RequestConfig) => Promise<HttpResponse<T>>
+  post: <T>(url: string, data?: unknown, config?: RequestConfig) => Promise<HttpResponse<T>>
+  put: <T>(url: string, data?: unknown, config?: RequestConfig) => Promise<HttpResponse<T>>
+  patch: <T>(url: string, data?: unknown, config?: RequestConfig) => Promise<HttpResponse<T>>
+  delete: <T>(url: string, config?: RequestConfig) => Promise<HttpResponse<T>>
+  request: <T>(config: FullRequestConfig) => Promise<HttpResponse<T>>
+}
+```
+
+**Returns:** The created result.
+
+#### `createHttpFromClient(client)`
+
+Creates a http from client.
+
+```typescript
+function createHttpFromClient(client: HttpClient): {
+  get: <T>(url: string, config?: RequestConfig) => Promise<HttpResponse<T>>
+  post: <T>(url: string, data?: unknown, config?: RequestConfig) => Promise<HttpResponse<T>>
+  put: <T>(url: string, data?: unknown, config?: RequestConfig) => Promise<HttpResponse<T>>
+  patch: <T>(url: string, data?: unknown, config?: RequestConfig) => Promise<HttpResponse<T>>
+  delete: <T>(url: string, config?: RequestConfig) => Promise<HttpResponse<T>>
+  request: <T>(config: FullRequestConfig) => Promise<HttpResponse<T>>
+}
+```
+
+- `client` — The client instance.
+
+**Returns:** The created result.
+
+#### `createHttpHelpers()`
+
+Creates a http helpers.
+
+```typescript
+function createHttpHelpers(): {
+  get: <T>(url: string, config?: RequestConfig) => Promise<HttpResponse<T>>
+  post: <T>(url: string, data?: unknown, config?: RequestConfig) => Promise<HttpResponse<T>>
+  put: <T>(url: string, data?: unknown, config?: RequestConfig) => Promise<HttpResponse<T>>
+  patch: <T>(url: string, data?: unknown, config?: RequestConfig) => Promise<HttpResponse<T>>
+  delete: <T>(url: string, config?: RequestConfig) => Promise<HttpResponse<T>>
+  setAuthToken: (token: string | null) => void
+  getAuthToken: () => string | null
+}
+```
+
+**Returns:** The created result.
+
+#### `createI18n()`
+
+Creates a i18n.
+
+```typescript
+function createI18n(): {
+  t: TranslateFunction
+  locale: Accessor<string>
+  setLocale: (newLocale: string) => Promise<void>
+  isReady: Accessor<boolean>
+  getLocales: () => LocaleConfig[]
+  hasKey: (key: string) => boolean
+}
+```
+
+**Returns:** The created result.
+
+#### `createI18nFromProvider(provider)`
+
+Creates a i18n from provider.
+
+```typescript
+function createI18nFromProvider(provider: I18nProvider): {
+  t: TranslateFunction
+  locale: Accessor<string>
+  setLocale: (newLocale: string) => Promise<void>
+  isReady: Accessor<boolean>
+  getLocales: () => LocaleConfig[]
+  hasKey: (key: string) => boolean
+}
+```
+
+- `provider` — The provider implementation.
+
+**Returns:** The created result.
+
+#### `createI18nHelpers()`
+
+Creates a i18n helpers.
+
+```typescript
+function createI18nHelpers(): {
+  t: TranslateFunction
+  getLocale: () => string
+  setLocale: (locale: string) => Promise<void>
+  getLocales: () => LocaleConfig[]
+  hasKey: (key: string) => boolean
+  isReady: () => boolean
+}
+```
+
+**Returns:** The created result.
+
+#### `createIsActive(path, exact)`
+
+Create a reactive boolean accessor that tracks whether a given path is active.
+
+Unlike `useMatch` which only accepts a static pattern, this factory returns
+a signal that re-evaluates on every route change and supports the `exact`
+parameter from the router's `isActive` method.
+
+```typescript
+function createIsActive(path: string, exact?: boolean): Accessor<boolean>
+```
+
+- `path` — Path to check against the current location
+- `exact` — Whether to require an exact match (default: false)
+
+**Returns:** Accessor<boolean> that is true when the path is active
+
+#### `createLogger(config)`
+
+Create a logger with custom configuration.
+
+```typescript
+function createLogger(config: LoggerConfig): Logger
+```
+
+- `config` — Logger configuration
+
+**Returns:** Logger instance
+
+#### `createLoggerFromProvider(provider, name)`
+
+Create logger from a specific provider.
+
+```typescript
+function createLoggerFromProvider(provider: LoggerProvider, name?: string): Logger
+```
+
+- `provider` — Logger provider
+- `name` — Logger name
+
+**Returns:** Logger instance
+
+#### `createLoggerHelpers()`
+
+Creates a logger helpers.
+
+```typescript
+function createLoggerHelpers(): {
+  getLogger: (name?: string) => Logger
+  createLogger: (config: LoggerConfig) => Logger
+  setLevel: (level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent') => void
+  getLevel: () => string
+  enable: () => void
+  disable: () => void
+  isEnabled: () => boolean
+}
+```
+
+**Returns:** The created result.
+
+#### `createLoggerHelpersFromProvider(provider)`
+
+Creates a logger helpers from provider.
+
+```typescript
+function createLoggerHelpersFromProvider(provider: LoggerProvider): {
+  getLogger: (name?: string) => Logger
+  createLogger: (config: LoggerConfig) => Logger
+  setLevel: (level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent') => void
+  getLevel: () => string
+  enable: () => void
+  disable: () => void
+  isEnabled: () => boolean
+}
+```
+
+- `provider` — The provider implementation.
+
+**Returns:** The created result.
+
+#### `createLogin()`
+
+Creates a login primitive with async state tracking.
+
+```typescript
+function createLogin(): CreateLoginReturn<T>
+```
+
+**Returns:** Login state and action
+
+#### `createOAuth(options)`
+
+Creates OAuth helpers.
+
+Automatically handles OAuth callbacks by detecting `code` and `state` URL
+parameters and exchanging them for a session:
+
+- Inside a Solid owner (component setup / `createRoot`), the callback
+  handling is deferred to `onMount` so it runs client-side after mount.
+- Outside an owner (a plain function call, e.g. bootstrap code), it runs
+  immediately at creation, browser-guarded.
+
+```typescript
+function createOAuth(options?: CreateOAuthOptions): CreateOAuthReturn
+```
+
+- `options` — OAuth configuration
+
+**Returns:** The created instance.
+
+#### `createPasswordReset()`
+
+Creates a password reset primitive with async state tracking.
+
+```typescript
+function createPasswordReset(): CreatePasswordResetReturn
+```
+
+**Returns:** Password reset state and actions
+
+#### `createPersistedStore(key, initial, storage)`
+
+Create a persisted signal store.
+
+```typescript
+function createPersistedStore(
+  key: string,
+  initial: T,
+  storage: StorageAdapter,
+): [Accessor<T>, (value: T | ((prev: T) => T)) => void]
+```
+
+- `key` — Storage key
+- `initial` — Initial value
+- `storage` — Storage adapter (required - use localStorage, sessionStorage, or `@molecule/app-storage`)
+
+**Returns:** Tuple of accessor and setter
+
+#### `createPlatform()`
+
+Create platform primitives for detecting the current platform.
+
+This is a static primitive (no reactive signals) since the platform
+does not change during the lifecycle of the app.
+
+```typescript
+function createPlatform(): PlatformPrimitives
+```
+
+**Returns:** Platform primitives object
+
+#### `createPromise(asyncFn)`
+
+Primitive that wraps an async function with reactive state tracking.
+
+```typescript
+function createPromise(asyncFn: T): CreatePromiseReturn<Awaited<ReturnType<T>>>
+```
+
+- `asyncFn` — The async function to wrap
+
+**Returns:** Object with state accessor, call, cancel, and reset functions
+
+#### `createPush()`
+
+Create push notification primitives.
+
+```typescript
+function createPush(): PushPrimitives
+```
+
+**Returns:** Push primitives object
+
+#### `createRouter()`
+
+Create router primitives for navigation state and actions.
+
+```typescript
+function createRouter(): RouterPrimitives
+```
+
+**Returns:** Router primitives object
+
+#### `createRouterFromInstance(router)`
+
+Create router primitives from a specific router.
+
+```typescript
+function createRouterFromInstance(router: Router): RouterPrimitives
+```
+
+- `router` — Router instance
+
+**Returns:** Router primitives
+
+#### `createRouterHelpers()`
+
+Creates a router helpers.
+
+```typescript
+function createRouterHelpers(): {
+  navigate: (path: string, options?: NavigateOptions) => void
+  navigateTo: (
+    name: string,
+    params?: RouteParams,
+    query?: QueryParams,
+    options?: NavigateOptions,
+  ) => void
+  back: () => void
+  forward: () => void
+  getLocation: () => RouteLocation
+  getParams: () => RouteParams
+  getQuery: () => QueryParams
+  isActive: (path: string) => boolean
+}
+```
+
+**Returns:** The created result.
+
+#### `createSignalStore(initial)`
+
+Create a simple signal-based store without provider.
+
+```typescript
+function createSignalStore(initial: T): [Accessor<T>, (value: T | ((prev: T) => T)) => void]
+```
+
+- `initial` — Initial state
+
+**Returns:** The created instance.
+
+#### `createSignup()`
+
+Creates a signup primitive with async state tracking.
+
+```typescript
+function createSignup(): CreateSignupReturn<T>
+```
+
+**Returns:** Signup state and action
+
+#### `createStateHelpers()`
+
+Creates a state helpers.
+
+```typescript
+function createStateHelpers(): {
+  createStore: <T extends object>(config: StoreConfig<T>) => Store<T>
+}
+```
+
+**Returns:** The created result.
+
+#### `createStateHelpersFromProvider(provider)`
+
+Creates a state helpers from provider.
+
+```typescript
+function createStateHelpersFromProvider(provider: StateProvider): {
+  createStore: <T extends object>(config: StoreConfig<T>) => Store<T>
+}
+```
+
+- `provider` — The provider implementation.
+
+**Returns:** The created result.
+
+#### `createStorage()`
+
+Create storage primitives.
+
+```typescript
+function createStorage(): {
+  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 methods
+
+#### `createStorageFromProvider(storage)`
+
+Create storage primitives from a specific provider.
+
+```typescript
+function createStorageFromProvider(storage: StorageProvider): {
+  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[]>
+}
+```
+
+- `storage` — Storage provider
+
+**Returns:** Storage methods
+
+#### `createStorageHelpers()`
+
+Create storage helpers from context.
+
+```typescript
+function createStorageHelpers(): {
+  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 helper functions
+
+#### `createStorageValue(key, defaultValue)`
+
+Create a storage value primitive.
+
+```typescript
+function createStorageValue(
+  key: string,
+  defaultValue?: T,
+): {
+  value: () => T | undefined
+  loading: () => boolean
+  error: () => Error | null
+  set: (value: T) => Promise<void>
+  remove: () => Promise<void>
+  refresh: () => Promise<T | undefined>
+}
+```
+
+- `key` — Storage key
+- `defaultValue` — Default value if not found
+
+**Returns:** Storage value accessor and actions
+
+#### `createStorageValueFromProvider(storage, key, defaultValue)`
+
+Create storage value primitive from a specific provider.
+
+```typescript
+function createStorageValueFromProvider(
+  storage: StorageProvider,
+  key: string,
+  defaultValue?: T,
+): {
+  value: () => T | undefined
+  loading: () => boolean
+  error: () => Error | null
+  set: (value: T) => Promise<void>
+  remove: () => Promise<void>
+}
+```
+
+- `storage` — Storage provider
+- `key` — Storage key
+- `defaultValue` — Default value
+
+**Returns:** Storage value accessor and actions
+
+#### `createStore(config)`
+
+Create a reactive store using Solid signals.
+
+```typescript
+function createStore(config: StoreConfig<T>): Store<T>
+```
+
+- `config` — Store configuration
+
+**Returns:** Store instance
+
+#### `createTheme()`
+
+Create theme primitives for theme state and actions.
+
+```typescript
+function createTheme(): ThemePrimitives
+```
+
+**Returns:** The created instance.
+
+#### `createThemeColors(theme)`
+
+Create a colors accessor derived from a theme accessor.
+
+```typescript
+function createThemeColors(theme: Accessor<Theme>): Accessor<ThemeColors>
+```
+
+- `theme` — Theme accessor (e.g. from createTheme().theme)
+
+**Returns:** Accessor for the current theme colors
+
+#### `createThemeFromProvider(provider)`
+
+Create theme primitives from a specific provider.
+
+```typescript
+function createThemeFromProvider(provider: ThemeProvider): ThemePrimitives
+```
+
+- `provider` — Theme provider
+
+**Returns:** Theme primitives
+
+#### `createThemeHelpers()`
+
+Creates a theme helpers.
+
+```typescript
+function createThemeHelpers(): {
+  getTheme: () => Theme
+  setTheme: (name: string) => void
+  getMode: () => 'light' | 'dark'
+  toggleMode: () => void
+  getAvailableThemes: () => Theme[]
+}
+```
+
+**Returns:** The created result.
+
+#### `createVersion()`
+
+Create version primitives for tracking app updates.
+
+```typescript
+function createVersion(): VersionPrimitives
+```
+
+**Returns:** Version primitives object
+
+#### `createWatchSignal(controller, name)`
+
+Create a reactive accessor that tracks a single field's value.
+
+```typescript
+function createWatchSignal(controller: FormController<T>, name: K): Accessor<T[K]>
+```
+
+- `controller` — Form controller
+- `name` — Field name to watch
+
+**Returns:** Accessor for the field value
+
+#### `getAuthClient()`
+
+Get the auth client from context.
+
+```typescript
+function getAuthClient(): AuthClient<T>
+```
+
+**Returns:** The auth client instance.
+
+#### `getChildLogger(name, context)`
+
+Create a child logger with additional context.
+
+```typescript
+function getChildLogger(name: string, context: Record<string, unknown>): Logger
+```
+
+- `name` — Parent logger name
+- `context` — Additional context
+
+**Returns:** Child logger instance
+
+#### `getHttpClient()`
+
+Get the HTTP client from context.
+
+```typescript
+function getHttpClient(): HttpClient
+```
+
+**Returns:** The HTTP client instance.
+
+#### `getI18nProvider()`
+
+Get the i18n provider from context.
+
+```typescript
+function getI18nProvider(): I18nProvider
+```
+
+**Returns:** The i18n provider instance.
+
+#### `getLogger(name)`
+
+Get a logger instance.
+
+```typescript
+function getLogger(name?: string): Logger
+```
+
+- `name` — Logger name
+
+**Returns:** Logger instance
+
+#### `getLoggerProvider()`
+
+Get the logger provider from context.
+
+```typescript
+function getLoggerProvider(): LoggerProvider
+```
+
+**Returns:** The logger provider instance.
+
+#### `getRootLogger()`
+
+Get the root logger.
+
+```typescript
+function getRootLogger(): Logger
+```
+
+**Returns:** Root logger instance
+
+#### `getRouter()`
+
+Get the router from context.
+
+```typescript
+function getRouter(): Router
+```
+
+**Returns:** The router instance.
+
+#### `getStateProvider()`
+
+Get the state provider from context.
+
+```typescript
+function getStateProvider(): StateProvider
+```
+
+**Returns:** The state provider instance.
+
+#### `getStorageProvider()`
+
+Get the storage provider from context.
+
+```typescript
+function getStorageProvider(): StorageProvider
+```
+
+**Returns:** The storage provider instance.
+
+#### `getThemeProvider()`
+
+Get the theme provider from context.
+
+```typescript
+function getThemeProvider(): ThemeProvider
+```
+
+**Returns:** The theme provider instance.
+
+#### `MoleculeProvider(props)`
+
+MoleculeProvider component that provides all molecule services to the component tree.
+
+```typescript
+function MoleculeProvider(props: ParentProps<{ config: MoleculeConfig }>): JSX.Element
+```
+
+- `props` — Component props containing the molecule config.
+
+**Returns:** The nested provider tree wrapping children.
+
+#### `useComponentLogger(componentName)`
+
+Create a component logger that includes component name in context.
+
+```typescript
+function useComponentLogger(componentName: string): Logger
+```
+
+- `componentName` — Name of the component
+
+**Returns:** Logger configured for the component
+
+#### `useFetch(url, config)`
+
+Create a resource for fetching data.
+
+```typescript
+function useFetch(url: string | Accessor<string>, config?: RequestConfig): Resource<T | undefined>
+```
+
+- `url` — URL string or accessor returning a URL string.
+- `config` — Optional request configuration.
+
+**Returns:** Solid resource
+
+#### `useLazyQuery()`
+
+Hook for lazy query.
+
+```typescript
+function useLazyQuery(): {
+  execute: (url: string, config?: RequestConfig) => Promise<T>
+  data: () => T | null
+  isLoading: () => boolean
+  error: () => Error | null
+  reset: () => void
+}
+```
+
+**Returns:** The result.
+
+#### `useLocale()`
+
+Get current locale as accessor.
+
+```typescript
+function useLocale(): Accessor<string>
+```
+
+**Returns:** Accessor for current locale
+
+#### `useLocation()`
+
+Get current route location as accessor.
+
+```typescript
+function useLocation(): Accessor<RouteLocation>
+```
+
+**Returns:** Accessor for current location
+
+#### `useMatch(pattern)`
+
+Create a match accessor for a path pattern.
+
+```typescript
+function useMatch(pattern: string): Accessor<boolean>
+```
+
+- `pattern` — Path pattern to match
+
+**Returns:** Accessor indicating if current path matches
+
+#### `useMode()`
+
+Create a mode accessor.
+
+```typescript
+function useMode(): Accessor<'light' | 'dark'>
+```
+
+**Returns:** Accessor for current mode
+
+#### `useMutation()`
+
+Hook for mutation.
+
+```typescript
+function useMutation(): {
+  mutate: (
+    url: string,
+    payload?: unknown,
+    method?: 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  ) => Promise<T>
+  isLoading: Accessor<boolean>
+  error: Accessor<Error | null>
+  data: Accessor<T | null>
+  reset: () => void
+}
+```
+
+**Returns:** The result.
+
+#### `useNavigate()`
+
+Get navigate function.
+
+```typescript
+function useNavigate(): (path: string, options?: NavigateOptions) => void
+```
+
+**Returns:** Navigate function
+
+#### `useParams()`
+
+Get current route params as accessor.
+
+```typescript
+function useParams(): Accessor<RouteParams>
+```
+
+**Returns:** Accessor for route params
+
+#### `usePersistedSignal(key, defaultValue)`
+
+Create a persisted signal that syncs with storage.
+
+```typescript
+function usePersistedSignal(
+  key: string,
+  defaultValue: T,
+): [Accessor<T | undefined>, (value: T | ((prev: T | undefined) => T)) => void]
+```
+
+- `key` — Storage key
+- `defaultValue` — Default value
+
+**Returns:** Tuple of accessor and setter
+
+#### `usePlural(key, count, values)`
+
+Create a reactive plural translation.
+
+```typescript
+function usePlural(
+  key: string,
+  count: Accessor<number>,
+  values?: InterpolationValues,
+): Accessor<string>
+```
+
+- `key` — Translation key
+- `count` — Count accessor for pluralization
+- `values` — Interpolation values for the translation.
+
+**Returns:** Accessor for translated string
+
+#### `useQuery()`
+
+Get current query params as accessor.
+
+```typescript
+function useQuery(): Accessor<QueryParams>
+```
+
+**Returns:** Accessor for query params
+
+#### `useStore(store, selector)`
+
+Use a store with optional selector, returning an accessor.
+
+```typescript
+function useStore(store: Store<T>, selector?: (state: T) => S): Accessor<S>
+```
+
+- `store` — Store to subscribe to
+- `selector` — Optional selector function
+
+**Returns:** Accessor for selected state
+
+#### `useThemeName()`
+
+Create a theme name accessor.
+
+```typescript
+function useThemeName(): Accessor<string>
+```
+
+**Returns:** Accessor for current theme name
+
+#### `useTranslate()`
+
+Get translate function.
+
+```typescript
+function useTranslate(): TranslateFunction
+```
+
+**Returns:** Translate function
+
+#### `useTranslation(key, values, options)`
+
+Create a reactive translation.
+
+```typescript
+function useTranslation(
+  key: string,
+  values?: InterpolationValues,
+  options?: TranslateOptions,
+): Accessor<string>
+```
+
+- `key` — Translation key
+- `values` — Interpolation values for the translation.
+- `options` — Translation options
+
+**Returns:** Accessor for translated string
+
+### Constants
+
+#### `AuthContext`
+
+```typescript
+const AuthContext: Context<AuthClient<unknown> | undefined>
+```
+
+#### `HttpContext`
+
+```typescript
+const HttpContext: Context<HttpClient | undefined>
+```
+
+#### `I18nContext`
+
+```typescript
+const I18nContext: Context<I18nProvider | undefined>
+```
+
+#### `LoggerContext`
+
+```typescript
+const LoggerContext: Context<LoggerProvider | undefined>
+```
+
+#### `RouterContext`
+
+```typescript
+const RouterContext: Context<Router | undefined>
+```
+
+#### `StateContext`
+
+Internal contexts for molecule providers.
+
+```typescript
+const StateContext: Context<StateProvider | undefined>
+```
+
+#### `StorageContext`
+
+```typescript
+const StorageContext: Context<StorageProvider | undefined>
+```
+
+#### `ThemeContext`
+
+```typescript
+const ThemeContext: Context<ThemeProvider | undefined>
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/app-auth` ^1.0.0
+- `@molecule/app-device` ^1.0.0
+- `@molecule/app-forms` ^1.0.0
+- `@molecule/app-http` ^1.0.0
+- `@molecule/app-i18n` ^1.0.0
+- `@molecule/app-logger` ^1.0.0
+- `@molecule/app-platform` ^1.0.0
+- `@molecule/app-push` ^1.0.0
+- `@molecule/app-routing` ^1.0.0
+- `@molecule/app-state` ^1.0.0
+- `@molecule/app-storage` ^1.0.0
+- `@molecule/app-theme` ^1.0.0
+- `@molecule/app-ui` ^1.0.0
+- `@molecule/app-utilities` ^1.0.0
+- `@molecule/app-version` ^1.0.0
+- `solid-js` ^1.8.0
+
+### Runtime Dependencies
+
+- `@molecule/app-auth`
+- `@molecule/app-device`
+- `@molecule/app-forms`
+- `@molecule/app-http`
+- `@molecule/app-i18n`
+- `@molecule/app-logger`
+- `@molecule/app-platform`
+- `@molecule/app-push`
+- `@molecule/app-routing`
+- `@molecule/app-state`
+- `@molecule/app-storage`
+- `@molecule/app-theme`
+- `@molecule/app-ui`
+- `@molecule/app-utilities`
+- `@molecule/app-version`
+- `solid-js`
+
+- **Primitives throw outside `MoleculeProvider` — and per missing service.** `config` wires
+  ONLY the services you pass; calling `createAuth()` in a tree whose config lacks `auth`
+  throws "getAuthClient must be used within a MoleculeProvider with auth configured". Fix the
+  config, don't catch the error.
+- Primitive results are Solid accessors — call them (`isAuthenticated()`, `theme()`,
+  `user()`), never read them bare; a bare `theme.colors` is a type error, and a bare
+  `isAuthenticated` is always truthy.
+- Call primitives at component setup (top level of the component function), not inside JSX
+  callbacks, so subscriptions are established once.
+
+## Translations
+
+Translation strings are provided by `@molecule/app-locales-solid`.