@oxyhq/bloom 0.6.13 → 0.6.15

package/lib/typescript/commonjs/theme/color-presets.d.ts

@@ -1,11 +1,26 @@
 export type AppColorName = 'teal' | 'blue' | 'green' | 'amber' | 'yellow' | 'red' | 'purple' | 'pink' | 'sky' | 'orange' | 'mint' | 'oxy' | 'faircoin';
+/**
+ * Palette tokens for a single mode (light or dark) of a color preset.
+ *
+ * Keys carry a leading `--` for historical reasons (shadcn-style CSS variable
+ * names) — keep in mind the values are platform-agnostic **raw HSL triples**
+ * (e.g. `'185 100% 20%'` or `'185 100% 20% / 0.5'`), not CSS-resolved colors.
+ * The same map drives both:
+ *   - the web layer (written verbatim into `document.documentElement.style`
+ *     so Tailwind's `hsl(var(--primary))` plumbing picks them up), and
+ *   - the native layer (`buildTheme` resolves them into `hsl(...)` strings
+ *     consumable by React Native styles).
+ *
+ * The `--` prefix is an implementation detail we will drop in a future major.
+ */
+export type PresetTokens = Record<string, string>;
 export interface AppColorPreset {
     name: AppColorName;
     hex: string;
-    light: Record<string, string>;
-    dark: Record<string, string>;
+    light: PresetTokens;
+    dark: PresetTokens;
 }
-export declare const APP_COLOR_NAMES: AppColorName[];
+export declare const APP_COLOR_NAMES: readonly AppColorName[];
 export declare const HEX_TO_APP_COLOR: Record<string, AppColorName>;
 export declare function hexToAppColorName(hex: string): AppColorName;
 export declare const APP_COLOR_PRESETS: Record<AppColorName, AppColorPreset>;

package/lib/typescript/commonjs/theme/color-presets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"color-presets.d.ts","sourceRoot":"","sources":["../../../../src/theme/color-presets.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;AAEvJ,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,eAAO,MAAM,eAAe,EAAE,YAAY,EAAsH,CAAC;AAEjK,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAczD,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAE3D;AAED,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,YAAY,EAAE,cAAc,CAkmBlE,CAAC"}
+{"version":3,"file":"color-presets.d.ts","sourceRoot":"","sources":["../../../../src/theme/color-presets.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;AAEvJ;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,YAAY,EAAsH,CAAC;AAE1K,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAczD,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAE3D;AAED,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,YAAY,EAAE,cAAc,CAkmBlE,CAAC"}

package/lib/typescript/commonjs/theme/index.d.ts

@@ -1,10 +1,13 @@
-export { BloomThemeProvider, BloomColorScope, buildTheme } from './BloomThemeProvider';
-export type { BloomThemeProviderProps, BloomThemeContextValue, BloomColorScopeProps } from './BloomThemeProvider';
+export { BloomThemeProvider, BloomColorScope } from './BloomThemeProvider';
+export type { BloomThemeProviderProps, BloomThemeContextValue, BloomColorScopeProps, } from './BloomThemeProvider';
+export { buildTheme, STATUS_COLORS } from './build-theme';
 export { useTheme, useThemeColor, useBloomTheme } from './use-theme';
 export type { Theme, ThemeColors, ThemeMode } from './types';
-export type { AppColorName, AppColorPreset } from './color-presets';
-export { APP_COLOR_NAMES, APP_COLOR_PRESETS, HEX_TO_APP_COLOR, hexToAppColorName } from './color-presets';
+export type { AppColorName, AppColorPreset, PresetTokens } from './color-presets';
+export { APP_COLOR_NAMES, APP_COLOR_PRESETS, HEX_TO_APP_COLOR, hexToAppColorName, } from './color-presets';
 export { applyDarkClass } from './apply-dark-class';
 export { setColorSchemeSafe } from './set-color-scheme-safe';
 export { initCssInteropDarkMode } from './init-css-interop';
+export type { BloomThemeStorage, PersistedThemeState } from './persistence';
+export { webLocalStorage } from './persistence';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/commonjs/theme/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/theme/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvF,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1G,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/theme/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC3E,YAAY,EACV,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/lib/typescript/commonjs/theme/persistence.d.ts

@@ -0,0 +1,50 @@
+import { type AppColorName } from './color-presets';
+import type { ThemeMode } from './types';
+/**
+ * Storage adapter for persisting Bloom theme state.
+ *
+ * Methods may be synchronous or asynchronous. The provider awaits both, so
+ * `AsyncStorage`-compatible adapters on native and `localStorage`-backed
+ * adapters on web both work without consumer-side branching.
+ *
+ * On web, a synchronous adapter lets Bloom hydrate before the first paint —
+ * preventing a flash of the default palette. On native, the provider can
+ * gate `children` rendering until hydration completes (see
+ * `awaitHydration` on `BloomThemeProvider`).
+ */
+export interface BloomThemeStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem?(key: string): void | Promise<void>;
+}
+export interface PersistedThemeState {
+    mode?: ThemeMode;
+    colorPreset?: AppColorName;
+}
+export type SyncReadResult = {
+    kind: 'sync';
+    state: PersistedThemeState | null;
+} | {
+    kind: 'async';
+} | {
+    kind: 'none';
+};
+/**
+ * Read persisted state during the first render. Returns a discriminated union
+ * so the provider can tell apart:
+ *   - `none`: persistence not configured.
+ *   - `sync`: adapter returned a value synchronously (web `localStorage`).
+ *     Provider can render immediately with the resolved state.
+ *   - `async`: adapter returned a Promise (native `AsyncStorage`). Provider
+ *     must await `readPersistedTheme` before painting if gating is enabled.
+ */
+export declare function readPersistedThemeSync(persistKey: string | undefined, storage: BloomThemeStorage | undefined): SyncReadResult;
+export declare function readPersistedTheme(persistKey: string | undefined, storage: BloomThemeStorage | undefined): Promise<PersistedThemeState | null>;
+export declare function writePersistedTheme(persistKey: string | undefined, storage: BloomThemeStorage | undefined, state: PersistedThemeState): Promise<void>;
+export declare function removePersistedTheme(persistKey: string | undefined, storage: BloomThemeStorage | undefined): Promise<void>;
+/**
+ * `localStorage`-backed storage adapter. Only defined on web; on native the
+ * export is `undefined` so consumers pass an `AsyncStorage` adapter explicitly.
+ */
+export declare const webLocalStorage: BloomThemeStorage | undefined;
+//# sourceMappingURL=persistence.d.ts.map

package/lib/typescript/commonjs/theme/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../../src/theme/persistence.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAKzC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7D,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,UAAU,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AA4BD,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAKrB;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,iBAAiB,GAAG,SAAS,GACrC,cAAc,CAYhB;AAED,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,iBAAiB,GAAG,SAAS,GACrC,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CASrC;AAED,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,iBAAiB,GAAG,SAAS,EACtC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,iBAAiB,GAAG,SAAS,GACrC,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,iBAAiB,GAAG,SA8B9C,CAAC"}

package/lib/typescript/commonjs/theme/use-isomorphic-layout-effect.d.ts

@@ -0,0 +1,8 @@
+import { useEffect } from 'react';
+/**
+ * `useLayoutEffect` on web (and native — react-native polyfills it) but falls
+ * back to `useEffect` during SSR to avoid the React warning. Bloom apps are
+ * primarily Expo (no SSR), but Next.js consumers of the web bundle need this.
+ */
+export declare const useIsomorphicLayoutEffect: typeof useEffect;
+//# sourceMappingURL=use-isomorphic-layout-effect.d.ts.map

package/lib/typescript/commonjs/theme/use-isomorphic-layout-effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-isomorphic-layout-effect.d.ts","sourceRoot":"","sources":["../../../../src/theme/use-isomorphic-layout-effect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAmB,MAAM,OAAO,CAAC;AAGnD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,kBACkD,CAAC"}

package/lib/typescript/module/hooks/useControllableState.d.ts

@@ -0,0 +1,19 @@
+export interface UseControllableStateOptions<T> {
+    /** Controlled value. When defined, the hook does not own internal state. */
+    value?: T;
+    /** Initial value used when uncontrolled. */
+    defaultValue: T;
+    /** Notified whenever the value changes, controlled or not. */
+    onChange?: (next: T) => void;
+}
+/**
+ * Canonical Radix/shadcn-style controllable state hook. Returns a tuple of the
+ * current value and a setter that:
+ *   - updates internal state when uncontrolled, and
+ *   - always calls `onChange` (so controlled parents stay in sync).
+ *
+ * Switching between controlled and uncontrolled at runtime is supported but
+ * discouraged; the hook keeps the latest `value` for reads either way.
+ */
+export declare function useControllableState<T>({ value, defaultValue, onChange, }: UseControllableStateOptions<T>): [T, (next: T) => void];
+//# sourceMappingURL=useControllableState.d.ts.map

package/lib/typescript/module/hooks/useControllableState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useControllableState.d.ts","sourceRoot":"","sources":["../../../../src/hooks/useControllableState.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,2BAA2B,CAAC,CAAC;IAC5C,4EAA4E;IAC5E,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,4CAA4C;IAC5C,YAAY,EAAE,CAAC,CAAC;IAChB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,EACtC,KAAK,EACL,YAAY,EACZ,QAAQ,GACT,EAAE,2BAA2B,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,CAmBzD"}

package/lib/typescript/module/theme/BloomThemeProvider.d.ts

@@ -1,40 +1,63 @@
 import './init-css-interop';
 import React from 'react';
 import { type AppColorName } from './color-presets';
+import { type BloomThemeStorage } from './persistence';
 import type { Theme, ThemeMode } from './types';
-/** Build a Theme object from a color preset name and resolved light/dark mode. */
-export declare function buildTheme(appColor: AppColorName, resolved: 'light' | 'dark', isAdaptive?: boolean): Theme;
 export interface BloomThemeContextValue {
     theme: Theme;
     mode: ThemeMode;
     colorPreset: AppColorName;
     setMode: (mode: ThemeMode) => void;
     setColorPreset: (preset: AppColorName) => void;
+    /**
+     * Restore mode and color preset to the provider defaults
+     * (`defaultMode` / `defaultColorPreset`) and clear the persisted entry.
+     * Use this when signing out or otherwise resetting per-user state.
+     */
+    resetTheme: () => void;
 }
 export declare const BloomThemeContext: React.Context<BloomThemeContextValue | null>;
 export interface BloomThemeProviderProps {
+    /** Controlled mode. Omit to use Bloom's internal state (with optional persistence). */
     mode?: ThemeMode;
+    /** Controlled color preset. Omit to use Bloom's internal state. */
     colorPreset?: AppColorName;
+    /** Initial mode when uncontrolled and nothing is persisted yet. */
+    defaultMode?: ThemeMode;
+    /** Initial color preset when uncontrolled and nothing is persisted yet. */
+    defaultColorPreset?: AppColorName;
     onModeChange?: (mode: ThemeMode) => void;
     onColorPresetChange?: (preset: AppColorName) => void;
     /**
-     * Load and inject the Bloom font system (BlomusModernus + Inter Variable
-     * + Geist Mono Variable). Default true. Set to false to opt out — e.g.
-     * apps that already ship their own font loader.
+     * Persist mode + preset under this storage key. Bloom becomes the single
+     * source of truth — apps don't need their own theme store. Has no effect
+     * without `storage`.
      */
-    fonts?: boolean;
+    persistKey?: string;
     /**
-     * Rendered while native fonts load. Ignored on web. Useful for matching
-     * an app-level splash screen so consumers don't see a system-font flash
-     * before the bundled fonts resolve.
+     * Storage adapter paired with `persistKey`. Use `webLocalStorage` on web,
+     * or pass an `AsyncStorage`-compatible adapter on native.
      */
+    storage?: BloomThemeStorage;
+    /**
+     * Block rendering until persisted state has been read. Default `true` when
+     * both `persistKey` and `storage` are provided, ensuring native apps don't
+     * flash the default palette. Web hydrates synchronously so this is a no-op
+     * there.
+     */
+    awaitHydration?: boolean;
+    /** Rendered while async hydration is pending. */
+    onHydrating?: React.ReactNode;
+    /** Load and inject Bloom's font system. Default `true`. */
+    fonts?: boolean;
+    /** Rendered while native fonts load. Ignored on web. */
     onFontsLoading?: React.ReactNode;
     children: React.ReactNode;
 }
-export declare function BloomThemeProvider({ mode: controlledMode, colorPreset: controlledPreset, onModeChange, onColorPresetChange, fonts, onFontsLoading, children, }: BloomThemeProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function BloomThemeProvider({ mode: controlledMode, colorPreset: controlledPreset, defaultMode, defaultColorPreset, onModeChange, onColorPresetChange, persistKey, storage, awaitHydration, onHydrating, fonts, onFontsLoading, children, }: BloomThemeProviderProps): import("react/jsx-runtime").JSX.Element;
 /**
- * Scoped color override for a subtree.
- * Inherits mode/dark from the parent BloomThemeProvider but overrides the color preset.
+ * Scoped color override for a subtree. Inherits the resolved mode from the
+ * parent `BloomThemeProvider` but renders descendants with a different preset.
  */
 export interface BloomColorScopeProps {
     colorPreset: AppColorName;

package/lib/typescript/module/theme/BloomThemeProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BloomThemeProvider.d.ts","sourceRoot":"","sources":["../../../../src/theme/BloomThemeProvider.tsx"],"names":[],"mappings":"AAIA,OAAO,oBAAoB,CAAC;AAC5B,OAAO,KAA4E,MAAM,OAAO,CAAC;AAEjG,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAKvE,OAAO,KAAK,EAAE,KAAK,EAAe,SAAS,EAAE,MAAM,SAAS,CAAC;AAmB7D,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,EAAE,UAAU,GAAE,OAAe,GAAG,KAAK,CAyEjH;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,YAAY,CAAC;IAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACnC,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;CAChD;AAED,eAAO,MAAM,iBAAiB,8CAAqD,CAAC;AAEpF,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACzC,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IACrD;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACjC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,wBAAgB,kBAAkB,CAAC,EACjC,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,gBAAgB,EAC7B,YAAY,EACZ,mBAAmB,EACnB,KAAY,EACZ,cAAc,EACd,QAAQ,GACT,EAAE,uBAAuB,2CA2DzB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,YAAY,CAAC;IAC1B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,wBAAgB,eAAe,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,oBAAoB,2CAoB9E"}
+{"version":3,"file":"BloomThemeProvider.d.ts","sourceRoot":"","sources":["../../../../src/theme/BloomThemeProvider.tsx"],"names":[],"mappings":"AAIA,OAAO,oBAAoB,CAAC;AAE5B,OAAO,KAQN,MAAM,OAAO,CAAC;AAQf,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAKL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAKhD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,YAAY,CAAC;IAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACnC,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAC/C;;;;OAIG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,eAAO,MAAM,iBAAiB,8CAAqD,CAAC;AAEpF,MAAM,WAAW,uBAAuB;IACtC,uFAAuF;IACvF,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,mEAAmE;IACnE,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,mEAAmE;IACnE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,YAAY,CAAC;IAElC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACzC,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAErD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iDAAiD;IACjD,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAE9B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wDAAwD;IACxD,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAEjC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAkJD,wBAAgB,kBAAkB,CAAC,EACjC,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,gBAAgB,EAC7B,WAA0B,EAC1B,kBAAmC,EACnC,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,OAAO,EACP,cAAc,EACd,WAAW,EACX,KAAY,EACZ,cAAc,EACd,QAAQ,GACT,EAAE,uBAAuB,2CAkDzB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,YAAY,CAAC;IAC1B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,wBAAgB,eAAe,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,oBAAoB,2CAc9E"}

package/lib/typescript/module/theme/build-theme.d.ts

@@ -0,0 +1,20 @@
+import { type AppColorName } from './color-presets';
+import type { Theme } from './types';
+/**
+ * Status colors used across the design system. Independent of the accent
+ * preset so semantic intent stays stable across themes.
+ */
+export declare const STATUS_COLORS: {
+    readonly success: "#10B981";
+    readonly error: "#EF4444";
+    readonly warning: "#F59E0B";
+    readonly info: "#3B82F6";
+};
+/**
+ * Build a `Theme` from a color preset and a resolved light/dark mode.
+ *
+ * When `isAdaptive` is true and the platform exposes adaptive (Material You /
+ * iOS dynamic) colors, those override the preset-derived palette.
+ */
+export declare function buildTheme(preset: AppColorName, resolved: 'light' | 'dark', isAdaptive?: boolean): Theme;
+//# sourceMappingURL=build-theme.d.ts.map

package/lib/typescript/module/theme/build-theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-theme.d.ts","sourceRoot":"","sources":["../../../../src/theme/build-theme.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,YAAY,EAAqB,MAAM,iBAAiB,CAAC;AAE1F,OAAO,KAAK,EAAE,KAAK,EAAe,MAAM,SAAS,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AA6FX;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,OAAO,GAAG,MAAM,EAC1B,UAAU,GAAE,OAAe,GAC1B,KAAK,CAUP"}

package/lib/typescript/module/theme/color-presets.d.ts

@@ -1,11 +1,26 @@
 export type AppColorName = 'teal' | 'blue' | 'green' | 'amber' | 'yellow' | 'red' | 'purple' | 'pink' | 'sky' | 'orange' | 'mint' | 'oxy' | 'faircoin';
+/**
+ * Palette tokens for a single mode (light or dark) of a color preset.
+ *
+ * Keys carry a leading `--` for historical reasons (shadcn-style CSS variable
+ * names) — keep in mind the values are platform-agnostic **raw HSL triples**
+ * (e.g. `'185 100% 20%'` or `'185 100% 20% / 0.5'`), not CSS-resolved colors.
+ * The same map drives both:
+ *   - the web layer (written verbatim into `document.documentElement.style`
+ *     so Tailwind's `hsl(var(--primary))` plumbing picks them up), and
+ *   - the native layer (`buildTheme` resolves them into `hsl(...)` strings
+ *     consumable by React Native styles).
+ *
+ * The `--` prefix is an implementation detail we will drop in a future major.
+ */
+export type PresetTokens = Record<string, string>;
 export interface AppColorPreset {
     name: AppColorName;
     hex: string;
-    light: Record<string, string>;
-    dark: Record<string, string>;
+    light: PresetTokens;
+    dark: PresetTokens;
 }
-export declare const APP_COLOR_NAMES: AppColorName[];
+export declare const APP_COLOR_NAMES: readonly AppColorName[];
 export declare const HEX_TO_APP_COLOR: Record<string, AppColorName>;
 export declare function hexToAppColorName(hex: string): AppColorName;
 export declare const APP_COLOR_PRESETS: Record<AppColorName, AppColorPreset>;

package/lib/typescript/module/theme/color-presets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"color-presets.d.ts","sourceRoot":"","sources":["../../../../src/theme/color-presets.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;AAEvJ,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,eAAO,MAAM,eAAe,EAAE,YAAY,EAAsH,CAAC;AAEjK,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAczD,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAE3D;AAED,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,YAAY,EAAE,cAAc,CAkmBlE,CAAC"}
+{"version":3,"file":"color-presets.d.ts","sourceRoot":"","sources":["../../../../src/theme/color-presets.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;AAEvJ;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,YAAY,EAAsH,CAAC;AAE1K,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAczD,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAE3D;AAED,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,YAAY,EAAE,cAAc,CAkmBlE,CAAC"}

package/lib/typescript/module/theme/index.d.ts

@@ -1,10 +1,13 @@
-export { BloomThemeProvider, BloomColorScope, buildTheme } from './BloomThemeProvider';
-export type { BloomThemeProviderProps, BloomThemeContextValue, BloomColorScopeProps } from './BloomThemeProvider';
+export { BloomThemeProvider, BloomColorScope } from './BloomThemeProvider';
+export type { BloomThemeProviderProps, BloomThemeContextValue, BloomColorScopeProps, } from './BloomThemeProvider';
+export { buildTheme, STATUS_COLORS } from './build-theme';
 export { useTheme, useThemeColor, useBloomTheme } from './use-theme';
 export type { Theme, ThemeColors, ThemeMode } from './types';
-export type { AppColorName, AppColorPreset } from './color-presets';
-export { APP_COLOR_NAMES, APP_COLOR_PRESETS, HEX_TO_APP_COLOR, hexToAppColorName } from './color-presets';
+export type { AppColorName, AppColorPreset, PresetTokens } from './color-presets';
+export { APP_COLOR_NAMES, APP_COLOR_PRESETS, HEX_TO_APP_COLOR, hexToAppColorName, } from './color-presets';
 export { applyDarkClass } from './apply-dark-class';
 export { setColorSchemeSafe } from './set-color-scheme-safe';
 export { initCssInteropDarkMode } from './init-css-interop';
+export type { BloomThemeStorage, PersistedThemeState } from './persistence';
+export { webLocalStorage } from './persistence';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/theme/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/theme/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvF,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1G,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/theme/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC3E,YAAY,EACV,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/lib/typescript/module/theme/persistence.d.ts

@@ -0,0 +1,50 @@
+import { type AppColorName } from './color-presets';
+import type { ThemeMode } from './types';
+/**
+ * Storage adapter for persisting Bloom theme state.
+ *
+ * Methods may be synchronous or asynchronous. The provider awaits both, so
+ * `AsyncStorage`-compatible adapters on native and `localStorage`-backed
+ * adapters on web both work without consumer-side branching.
+ *
+ * On web, a synchronous adapter lets Bloom hydrate before the first paint —
+ * preventing a flash of the default palette. On native, the provider can
+ * gate `children` rendering until hydration completes (see
+ * `awaitHydration` on `BloomThemeProvider`).
+ */
+export interface BloomThemeStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem?(key: string): void | Promise<void>;
+}
+export interface PersistedThemeState {
+    mode?: ThemeMode;
+    colorPreset?: AppColorName;
+}
+export type SyncReadResult = {
+    kind: 'sync';
+    state: PersistedThemeState | null;
+} | {
+    kind: 'async';
+} | {
+    kind: 'none';
+};
+/**
+ * Read persisted state during the first render. Returns a discriminated union
+ * so the provider can tell apart:
+ *   - `none`: persistence not configured.
+ *   - `sync`: adapter returned a value synchronously (web `localStorage`).
+ *     Provider can render immediately with the resolved state.
+ *   - `async`: adapter returned a Promise (native `AsyncStorage`). Provider
+ *     must await `readPersistedTheme` before painting if gating is enabled.
+ */
+export declare function readPersistedThemeSync(persistKey: string | undefined, storage: BloomThemeStorage | undefined): SyncReadResult;
+export declare function readPersistedTheme(persistKey: string | undefined, storage: BloomThemeStorage | undefined): Promise<PersistedThemeState | null>;
+export declare function writePersistedTheme(persistKey: string | undefined, storage: BloomThemeStorage | undefined, state: PersistedThemeState): Promise<void>;
+export declare function removePersistedTheme(persistKey: string | undefined, storage: BloomThemeStorage | undefined): Promise<void>;
+/**
+ * `localStorage`-backed storage adapter. Only defined on web; on native the
+ * export is `undefined` so consumers pass an `AsyncStorage` adapter explicitly.
+ */
+export declare const webLocalStorage: BloomThemeStorage | undefined;
+//# sourceMappingURL=persistence.d.ts.map

package/lib/typescript/module/theme/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../../src/theme/persistence.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAKzC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7D,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,UAAU,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AA4BD,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAKrB;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,iBAAiB,GAAG,SAAS,GACrC,cAAc,CAYhB;AAED,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,iBAAiB,GAAG,SAAS,GACrC,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CASrC;AAED,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,iBAAiB,GAAG,SAAS,EACtC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,iBAAiB,GAAG,SAAS,GACrC,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,iBAAiB,GAAG,SA8B9C,CAAC"}

package/lib/typescript/module/theme/use-isomorphic-layout-effect.d.ts

@@ -0,0 +1,8 @@
+import { useEffect } from 'react';
+/**
+ * `useLayoutEffect` on web (and native — react-native polyfills it) but falls
+ * back to `useEffect` during SSR to avoid the React warning. Bloom apps are
+ * primarily Expo (no SSR), but Next.js consumers of the web bundle need this.
+ */
+export declare const useIsomorphicLayoutEffect: typeof useEffect;
+//# sourceMappingURL=use-isomorphic-layout-effect.d.ts.map

package/lib/typescript/module/theme/use-isomorphic-layout-effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-isomorphic-layout-effect.d.ts","sourceRoot":"","sources":["../../../../src/theme/use-isomorphic-layout-effect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAmB,MAAM,OAAO,CAAC;AAGnD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,kBACkD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",

package/src/__tests__/BloomThemeProvider.modes.test.tsx

@@ -0,0 +1,159 @@
+import React from 'react';
+import { Text } from 'react-native';
+import { render } from '@testing-library/react-native';
+
+let mockColorScheme: 'light' | 'dark' | null = 'light';
+
+jest.mock('react-native', () => {
+  const actual = jest.requireActual('react-native');
+  return {
+    ...actual,
+    useColorScheme: () => mockColorScheme,
+    Appearance: {
+      ...actual.Appearance,
+      setColorScheme: jest.fn(),
+      getColorScheme: () => mockColorScheme,
+    },
+  };
+});
+
+import { BloomThemeProvider } from '../theme/BloomThemeProvider';
+import { useTheme } from '../theme/use-theme';
+import { Appearance } from 'react-native';
+
+function Display() {
+  const t = useTheme();
+  return (
+    <>
+      <Text testID="resolved">{t.mode}</Text>
+      <Text testID="isDark">{String(t.isDark)}</Text>
+    </>
+  );
+}
+
+beforeEach(() => {
+  mockColorScheme = 'light';
+  (Appearance.setColorScheme as jest.Mock).mockClear();
+});
+
+describe('BloomThemeProvider — light/dark/system/adaptive flow', () => {
+  it('resolves system to light when OS is light', () => {
+    mockColorScheme = 'light';
+    const { getByTestId } = render(
+      <BloomThemeProvider mode="system">
+        <Display />
+      </BloomThemeProvider>,
+    );
+    expect(getByTestId('resolved').props.children).toBe('light');
+    expect(getByTestId('isDark').props.children).toBe('false');
+  });
+
+  it('resolves system to dark when OS is dark', () => {
+    mockColorScheme = 'dark';
+    const { getByTestId } = render(
+      <BloomThemeProvider mode="system">
+        <Display />
+      </BloomThemeProvider>,
+    );
+    expect(getByTestId('resolved').props.children).toBe('dark');
+    expect(getByTestId('isDark').props.children).toBe('true');
+  });
+
+  it('falls back to light when OS exposes no scheme', () => {
+    mockColorScheme = null;
+    const { getByTestId } = render(
+      <BloomThemeProvider mode="system">
+        <Display />
+      </BloomThemeProvider>,
+    );
+    expect(getByTestId('resolved').props.children).toBe('light');
+  });
+
+  it('treats adaptive mode like system for resolution', () => {
+    mockColorScheme = 'dark';
+    const { getByTestId } = render(
+      <BloomThemeProvider mode="adaptive">
+        <Display />
+      </BloomThemeProvider>,
+    );
+    expect(getByTestId('resolved').props.children).toBe('dark');
+  });
+
+  it('explicit light overrides OS dark', () => {
+    mockColorScheme = 'dark';
+    const { getByTestId } = render(
+      <BloomThemeProvider mode="light">
+        <Display />
+      </BloomThemeProvider>,
+    );
+    expect(getByTestId('resolved').props.children).toBe('light');
+    expect(getByTestId('isDark').props.children).toBe('false');
+  });
+
+  it('explicit dark overrides OS light', () => {
+    mockColorScheme = 'light';
+    const { getByTestId } = render(
+      <BloomThemeProvider mode="dark">
+        <Display />
+      </BloomThemeProvider>,
+    );
+    expect(getByTestId('resolved').props.children).toBe('dark');
+    expect(getByTestId('isDark').props.children).toBe('true');
+  });
+
+  it('installs explicit override via Appearance.setColorScheme for dark', () => {
+    render(
+      <BloomThemeProvider mode="dark">
+        <Display />
+      </BloomThemeProvider>,
+    );
+    expect(Appearance.setColorScheme).toHaveBeenCalledWith('dark');
+  });
+
+  it('installs explicit override via Appearance.setColorScheme for light', () => {
+    render(
+      <BloomThemeProvider mode="light">
+        <Display />
+      </BloomThemeProvider>,
+    );
+    expect(Appearance.setColorScheme).toHaveBeenCalledWith('light');
+  });
+
+  it('does NOT install an override in system mode (preserves OS link)', () => {
+    render(
+      <BloomThemeProvider mode="system">
+        <Display />
+      </BloomThemeProvider>,
+    );
+    // On non-iOS the call is skipped entirely; we also assert it was NEVER
+    // called with 'system' (which would install a bogus override).
+    const calls = (Appearance.setColorScheme as jest.Mock).mock.calls;
+    for (const call of calls) {
+      expect(call[0]).not.toBe('system');
+      expect(call[0]).not.toBe('dark');
+      expect(call[0]).not.toBe('light');
+    }
+  });
+
+  it('produces different colors for light vs dark resolution', () => {
+    mockColorScheme = 'light';
+    const { getByTestId: getLight, unmount } = render(
+      <BloomThemeProvider mode="system" colorPreset="blue">
+        <Display />
+      </BloomThemeProvider>,
+    );
+    const lightResolved = getLight('resolved').props.children;
+    unmount();
+
+    mockColorScheme = 'dark';
+    const { getByTestId: getDark } = render(
+      <BloomThemeProvider mode="system" colorPreset="blue">
+        <Display />
+      </BloomThemeProvider>,
+    );
+    const darkResolved = getDark('resolved').props.children;
+
+    expect(lightResolved).toBe('light');
+    expect(darkResolved).toBe('dark');
+  });
+});