@thewhileloop/whileui 4.1.0 → 4.1.1

package/README.md

@@ -11,6 +11,18 @@ production targets — iOS and Android set the interaction baseline. See
 [ROADMAP.md](./ROADMAP.md) for the product boundary and extraction rules, and
 [PLAN.md](./PLAN.md) for the supported stack and production contracts.
 
+## See it in action
+
+One React Native component contract across native and web, with semantic typography,
+token-driven light and dark themes, accessible controls, and application-owned chat
+composition. The same component tree can feel airy and atmospheric or compact and
+editorial by changing tokens alone.
+
+<p align="center">
+  <img src="./docs/assets/whileui-showcase.gif" width="300" alt="WhileUI Cosmic Aura mobile theme demonstrating light and dark modes, controls, Select, and composable chat" />
+  <img src="./docs/assets/whileui-showcase-atelier.gif" width="300" alt="WhileUI Atelier mobile theme demonstrating compact controls, authentication forms, Select, and composable chat" />
+</p>
+
 ## Installation
 
 ```bash
@@ -425,9 +437,9 @@ Copy from `apps/showcase/templates/profile/`:
 
 ### Media
 
-| Block          | Description                         |
-| -------------- | ----------------------------------- |
-| **SmartImage** | Image with aspect ratio and loading |
+| Block          | Description                                                        |
+| -------------- | ------------------------------------------------------------------ |
+| **SmartImage** | Image with explicit loading, loaded, fallback, and error lifecycle |
 
 ### Date Picker
 
@@ -926,6 +938,9 @@ const adapter: ThemeBridgeAdapter = {
 const { mode, resolvedTheme, setMode, cycleMode } = useThemeBridge({ adapter });
 ```
 
+The bridge loads a new adapter before saving into it. If a user changes the mode while
+storage is still loading, that explicit choice wins over the late persisted value.
+
 When another store already owns the mode, mount the controlled bridge once near the
 application root. Change `mode` in the owning event handler; the bridge applies and
 persists it without mirroring state back through a callback effect.
@@ -1446,6 +1461,8 @@ import {
 Focused and pressed options use the subtle interaction-state tokens; the primary token
 marks the selected indicator without replacing the option's foreground colour. Long
 selected values stay on one line and truncate without displacing the trigger chevron.
+For popover presentation on web, the options panel matches the trigger width, caps
+itself to the collision-available viewport, and wraps long option labels inside it.
 
 `SelectContent` supports optional frosted props:
 
@@ -1507,7 +1524,7 @@ import {
 import { Avatar, AvatarImage, AvatarFallback } from '@thewhileloop/whileui';
 
 <Avatar size="default">
-  <AvatarImage src="https://..." />
+  <AvatarImage source={{ uri: 'https://...' }} />
   <AvatarFallback>JD</AvatarFallback>
 </Avatar>;
 ```
@@ -1516,6 +1533,10 @@ import { Avatar, AvatarImage, AvatarFallback } from '@thewhileloop/whileui';
 | ---- | --------------------------- | ----------- |
 | size | `'sm' \| 'default' \| 'lg'` | `'default'` |
 
+`AvatarImage` keeps `AvatarFallback` visible while loading or after an error. Its
+`onLoadingStatusChange` callback reports `'loading'`, `'loaded'`, and `'error'`, including
+when a changed source begins loading, while the standard image event callbacks still run.
+
 ## Progress
 
 ```tsx
@@ -1552,6 +1573,9 @@ toast({ title: 'Success', description: 'Saved!', variant: 'success' });
 | variant       | `'default' \| 'success' \| 'destructive'` |
 | duration      | `number` (ms)                             |
 
+Each toast owns its duration from the moment it appears; adding or dismissing another
+toast does not restart timers already in progress.
+
 ## Popover
 
 ```tsx
@@ -1889,6 +1913,36 @@ code, and fenced code. It never opens links or writes to the clipboard itself:
 `onLinkPress` and `codeActions` keep those capabilities in the application. `CodeBlock`
 is dependency-free and accepts an application-owned `actions` slot.
 
+## SmartImage
+
+```tsx
+import { SmartImage } from '@thewhileloop/whileui';
+
+<SmartImage
+  source={{ uri: imageUrl }}
+  fallbackSource={{ uri: fallbackUrl }}
+  alt="Product preview"
+  className="h-48 w-full"
+/>;
+```
+
+| Prop                | Type                                               | Default   |
+| ------------------- | -------------------------------------------------- | --------- |
+| `source`            | `ImageProps['source']`                             | required  |
+| `alt`               | `string`                                           | required  |
+| `fallbackSource`    | `ImageProps['source']`                             | —         |
+| `skeleton`          | `boolean`                                          | `true`    |
+| `skeletonClassName` | `string`                                           | —         |
+| `transition`        | `number`                                           | `200`     |
+| `radius`            | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'`    |
+| `objectFit`         | `'cover' \| 'contain' \| 'fill' \| 'scale-down'`   | `'cover'` |
+| `onLoad`            | `() => void`                                       | —         |
+| `onError`           | `() => void`                                       | —         |
+
+The skeleton returns whenever the primary image starts loading again. A failed primary
+source switches to `fallbackSource` when supplied without re-entering a primary/fallback
+loop.
+
 ## DatePickerModal / DatePickerInline / DateRangePickerModal / TimePickerModal
 
 Date selection blocks using react-native-calendars. Theme-aware via `useCalendarTheme` (Uniwind light/dark). Optional `theme` prop for custom RN color strings (hex/rgb/hsl/named). `CalendarTheme` maps to react-native-calendars Theme and supports `arrowColor`, `disabledArrowColor`, and optional font keys.
@@ -2410,7 +2464,7 @@ Tracked work items for future releases.
 ### Documentation Gaps
 
 - [ ] Add `## API` sections for: Textarea, Toggle, ToggleGroup, Label, Separator, Skeleton, AspectRatio, Collapsible, Text, View
-- [ ] Add `## API` sections for blocks: FloatingBottomNav, TabBar, FormModalScreen, ErrorState, LoadingScreen, ListItem, NotificationItem, MetricCard, SmartImage, TimelineFeed
+- [ ] Add `## API` sections for blocks: FloatingBottomNav, TabBar, FormModalScreen, ErrorState, LoadingScreen, ListItem, NotificationItem, MetricCard, TimelineFeed
 
 ### Infrastructure
 

package/dist/blocks/media/smart-image.js

@@ -44,21 +44,19 @@ function resolveRadius(visual, radius) {
     return visual.radiusMd;
 }
 const SmartImage = React.forwardRef(({ className, source, alt, skeleton = true, skeletonClassName, transition = 200, radius, objectFit, onLoad, onError, fallbackSource, style, ...props }, ref) => {
-    const [loading, setLoading] = useState(true);
-    const [error, setError] = useState(false);
+    const [phase, setPhase] = useState('loading');
     const visual = useVisualTokens();
     const borderRadius = resolveRadius(visual, radius ?? 'md');
     const handleLoad = () => {
-        setLoading(false);
+        setPhase((current) => (current === 'fallback' ? 'fallback' : 'loaded'));
         onLoad?.();
     };
     const handleError = () => {
-        setLoading(false);
-        setError(true);
+        setPhase((current) => current === 'fallback' ? 'fallback' : fallbackSource ? 'fallback' : 'error');
         onError?.();
     };
-    const imageSource = error && fallbackSource ? fallbackSource : source;
-    return (_jsxs(View, { ref: ref, className: cn(smartImageVariants({ radius, objectFit }), className), style: [{ borderRadius }, style], ...props, children: [skeleton && loading && (_jsx(Skeleton, { className: cn('absolute inset-0', skeletonClassName) })), _jsx(Image, { source: imageSource, alt: alt, transition: transition, onLoad: handleLoad, onError: handleError, className: cn('w-full h-full', objectFit === 'cover' && 'object-cover', objectFit === 'contain' && 'object-contain', objectFit === 'fill' && 'object-fill', objectFit === 'scale-down' && 'object-scale-down'), style: { opacity: loading && !error ? 0 : 1 } })] }));
+    const imageSource = phase === 'fallback' ? fallbackSource : source;
+    return (_jsxs(View, { ref: ref, className: cn(smartImageVariants({ radius, objectFit }), className), style: [{ borderRadius }, style], ...props, children: [skeleton && phase === 'loading' && (_jsx(Skeleton, { className: cn('absolute inset-0', skeletonClassName) })), _jsx(Image, { source: imageSource, alt: alt, transition: transition, onLoadStart: () => setPhase((current) => (current === 'fallback' ? current : 'loading')), onLoad: handleLoad, onError: handleError, className: cn('w-full h-full', objectFit === 'cover' && 'object-cover', objectFit === 'contain' && 'object-contain', objectFit === 'fill' && 'object-fill', objectFit === 'scale-down' && 'object-scale-down'), style: { opacity: phase === 'loading' ? 0 : 1 } })] }));
 });
 SmartImage.displayName = 'SmartImage';
 export { SmartImage, smartImageVariants };

package/dist/components/avatar/avatar.d.ts

@@ -27,15 +27,16 @@ declare const avatarVariants: import("tailwind-variants").TVReturnType<{
 export interface AvatarProps extends ViewProps, VariantProps<typeof avatarVariants> {
     className?: string;
 }
+export type AvatarImageStatus = 'loading' | 'loaded' | 'error';
 export interface AvatarImageProps extends Omit<ImageProps, 'style'> {
     className?: string;
-    onLoadingStatusChange?: (status: 'loading' | 'loaded' | 'error') => void;
+    onLoadingStatusChange?: (status: AvatarImageStatus) => void;
 }
 export interface AvatarFallbackProps extends ViewProps {
     className?: string;
 }
 declare const Avatar: ForwardRefComponent<ViewInstance, AvatarProps>;
-declare function AvatarImage({ className, onLoadingStatusChange, ...props }: AvatarImageProps): React.JSX.Element;
+declare function AvatarImage({ className, onLoadingStatusChange, onLoadStart, onLoad, onError, ...props }: AvatarImageProps): React.JSX.Element;
 declare namespace AvatarImage {
     var displayName: string;
 }

package/dist/components/avatar/avatar.js

@@ -20,30 +20,36 @@ const avatarVariants = tv({
     },
 });
 const AvatarContext = React.createContext({
-    imageLoaded: false,
-    setImageLoaded: () => { },
+    imageStatus: 'loading',
+    setImageStatus: () => { },
 });
 const Avatar = React.forwardRef(({ className, size, ...props }, ref) => {
-    const [imageLoaded, setImageLoaded] = useState(false);
-    const contextValue = useMemo(() => ({ imageLoaded, setImageLoaded }), [imageLoaded]);
+    const [imageStatus, setImageStatus] = useState('loading');
+    const contextValue = useMemo(() => ({ imageStatus, setImageStatus }), [imageStatus]);
     return (_jsx(AvatarContext.Provider, { value: contextValue, children: _jsx(View, { ref: ref, className: cn(avatarVariants({ size }), className), ...props }) }));
 });
 Avatar.displayName = 'Avatar';
-function AvatarImage({ className, onLoadingStatusChange, ...props }) {
-    const { setImageLoaded } = React.useContext(AvatarContext);
-    return (_jsx(Image, { className: cn('aspect-square h-full w-full rounded-full', className), onLoad: () => {
-            setImageLoaded(true);
+function AvatarImage({ className, onLoadingStatusChange, onLoadStart, onLoad, onError, ...props }) {
+    const { setImageStatus } = React.useContext(AvatarContext);
+    return (_jsx(Image, { ...props, className: cn('aspect-square h-full w-full rounded-full', className), onLoadStart: () => {
+            setImageStatus('loading');
+            onLoadingStatusChange?.('loading');
+            onLoadStart?.();
+        }, onLoad: (event) => {
+            setImageStatus('loaded');
             onLoadingStatusChange?.('loaded');
-        }, onError: () => {
-            setImageLoaded(false);
+            onLoad?.(event);
+        }, onError: (event) => {
+            setImageStatus('error');
             onLoadingStatusChange?.('error');
-        }, ...props }));
+            onError?.(event);
+        } }));
 }
 AvatarImage.displayName = 'AvatarImage';
 function AvatarFallback({ className, children, ...props }) {
-    const { imageLoaded } = React.useContext(AvatarContext);
+    const { imageStatus } = React.useContext(AvatarContext);
     const visual = useVisualTokens();
-    if (imageLoaded)
+    if (imageStatus === 'loaded')
         return null;
     return (_jsx(View, { className: cn('flex h-full w-full items-center justify-center rounded-full bg-muted', className), ...props, children: typeof children === 'string' ? (_jsx(Text, { className: "font-medium text-muted-foreground", style: typographyStyle(visual, 'label'), children: children })) : (children) }));
 }

package/dist/components/avatar/index.d.ts

@@ -1 +1 @@
-export { Avatar, AvatarImage, AvatarFallback, avatarVariants, type AvatarProps, type AvatarImageProps, type AvatarFallbackProps, } from './avatar';
+export { Avatar, AvatarImage, AvatarFallback, avatarVariants, type AvatarProps, type AvatarImageProps, type AvatarImageStatus, type AvatarFallbackProps, } from './avatar';

package/dist/components/select/select.js

@@ -59,21 +59,33 @@ const SelectContent = React.forwardRef(({ className, children, portalHost, posit
     });
     const visual = useVisualTokens();
     const colors = useThemeColors();
-    return (_jsx(SelectPrimitive.Portal, { hostName: portalHost, children: _jsx(FullWindowOverlay, { children: _jsx(SelectPrimitive.Overlay, { style: Platform.select({ native: StyleSheet.absoluteFill }), children: _jsxs(SelectPrimitive.Content, { ref: ref, position: position, insets: insets, style: StyleSheet.flatten([
-                        {
-                            borderRadius: surfaceRadius(visual, 'lg'),
-                            borderWidth: visual.borderWidthHairline,
-                        },
-                        shadowStyle(visual, colors, 'md'),
-                        frostedSurface.surfaceStyle,
-                        styleProp,
-                    ]), className: cn('border-border relative z-50 min-w-32 overflow-hidden', frosted ? 'bg-transparent' : 'bg-popover', Platform.select({
-                        web: cn('max-h-96 overflow-y-auto overflow-x-hidden', props.side === 'bottom' && 'translate-y-1', props.side === 'top' && '-translate-y-1'),
+    // Radix applies its collision variables to the listbox wrapper, while
+    // @rn-primitives renders our visual surface one level inside it. Keep the sizing
+    // on that surface as inline web CSS: the Viewport's own `width: 100%` otherwise
+    // wins class merging and lets the longest option size the outer popper.
+    const webSizingStyle = Platform.OS === 'web' && position === 'popper'
+        ? {
+            boxSizing: 'border-box',
+            width: 'var(--radix-select-trigger-width)',
+            maxWidth: 'var(--radix-select-content-available-width)',
+            maxHeight: 'var(--radix-select-content-available-height)',
+        }
+        : undefined;
+    return (_jsx(SelectPrimitive.Portal, { hostName: portalHost, children: _jsx(FullWindowOverlay, { children: _jsx(SelectPrimitive.Overlay, { style: Platform.select({ native: StyleSheet.absoluteFill }), children: _jsxs(SelectPrimitive.Content, { ref: ref, position: position, insets: insets, style: {
+                        ...webSizingStyle,
+                        ...StyleSheet.flatten([
+                            {
+                                borderRadius: surfaceRadius(visual, 'lg'),
+                                borderWidth: visual.borderWidthHairline,
+                            },
+                            shadowStyle(visual, colors, 'md'),
+                            frostedSurface.surfaceStyle,
+                            styleProp,
+                        ]),
+                    }, className: cn('border-border relative z-50 overflow-hidden', frosted ? 'bg-transparent' : 'bg-popover', Platform.select({
+                        web: cn('overflow-y-auto overflow-x-hidden', props.side === 'bottom' && 'translate-y-1', props.side === 'top' && '-translate-y-1'),
                         native: 'p-1',
-                    }), className), ...props, children: [frostedSurface.overlay, _jsx(SelectPrimitive.Viewport, { className: cn('p-1', position === 'popper' &&
-                                Platform.select({
-                                    web: 'h-(--radix-select-trigger-height) w-full min-w-(--radix-select-trigger-width)',
-                                })), children: children })] }) }) }) }));
+                    }), className), ...props, children: [frostedSurface.overlay, _jsx(SelectPrimitive.Viewport, { className: "p-1", children: children })] }) }) }) }));
 });
 SelectContent.displayName = 'SelectContent';
 const SelectItem = React.forwardRef(({ className, children, style: styleProp, ...props }, ref) => {
@@ -90,7 +102,7 @@ const SelectItem = React.forwardRef(({ className, children, style: styleProp, ..
             },
             styleProp,
             props.disabled ? { opacity: interaction.disabledOpacity } : null,
-        ]), ...props, children: [_jsx(View, { className: "absolute right-3 flex h-4 w-4 items-center justify-center", children: _jsx(SelectPrimitive.ItemIndicator, { children: _jsx(View, { className: "border-primary h-2.5 w-1.5 rotate-45 border-b-2 border-r-2 -mt-0.5" }) }) }), children, _jsx(SelectPrimitive.ItemText, { className: "text-foreground", style: typographyStyle(visual, 'body') })] }));
+        ]), ...props, children: [_jsx(View, { className: "absolute right-3 flex h-4 w-4 items-center justify-center", children: _jsx(SelectPrimitive.ItemIndicator, { children: _jsx(View, { className: "border-primary h-2.5 w-1.5 rotate-45 border-b-2 border-r-2 -mt-0.5" }) }) }), children, _jsx(SelectPrimitive.ItemText, { className: "min-w-0 flex-1 text-foreground web:whitespace-normal web:break-words", style: typographyStyle(visual, 'body') })] }));
 });
 SelectItem.displayName = 'SelectItem';
 function SelectItemIcon({ className, children }) {

package/dist/components/toast/toast.js

@@ -86,10 +86,14 @@ function Toast({ toast: toastData, onDismiss, className, style, ...props }) {
                             paddingVertical: visual.controlPaddingYSm,
                         }, children: _jsx(Text, { className: cn('font-medium', textColor), style: typographyStyle(visual, 'label'), children: action.label }) })), _jsx(Pressable, { accessibilityRole: "button", accessibilityLabel: "Dismiss", onPress: onDismiss, className: "p-1", children: _jsx(Text, { className: cn(textColor), style: typographyStyle(visual, 'emphasis'), children: "\u00D7" }) })] })] }));
 }
+function ToastContainerItem({ toast, dismiss, }) {
+    const handleDismiss = useCallback(() => dismiss(toast.id), [dismiss, toast.id]);
+    return (_jsx(View, { className: "mb-2", children: _jsx(Toast, { toast: toast, onDismiss: handleDismiss }) }));
+}
 export function ToastContainer({ position = 'top', className, style, ...props }) {
     const { toasts, dismiss } = useToast();
     const visual = useVisualTokens();
     const positionClass = position === 'top' ? 'top-0' : 'bottom-0';
-    return (_jsx(View, { className: cn('absolute left-0 right-0 z-50 py-2', positionClass, className), style: [{ paddingHorizontal: visual.surfacePaddingSm }, style], pointerEvents: "box-none", ...props, children: toasts.map((toast) => (_jsx(View, { className: "mb-2", children: _jsx(Toast, { toast: toast, onDismiss: () => dismiss(toast.id) }) }, toast.id))) }));
+    return (_jsx(View, { className: cn('absolute left-0 right-0 z-50 py-2', positionClass, className), style: [{ paddingHorizontal: visual.surfacePaddingSm }, style], pointerEvents: "box-none", ...props, children: toasts.map((toast) => (_jsx(ToastContainerItem, { toast: toast, dismiss: dismiss }, toast.id))) }));
 }
 export { Toast, toastVariants };

package/dist/index.d.ts

@@ -40,7 +40,7 @@ export { Spinner, spinnerVariants, type SpinnerProps } from './components/spinne
 export { Textarea, textareaVariants, type TextareaProps } from './components/textarea';
 export { Skeleton, skeletonVariants, type SkeletonProps } from './components/skeleton';
 export { AspectRatio, type AspectRatioProps } from './components/aspect-ratio';
-export { Avatar, AvatarImage, AvatarFallback, avatarVariants, type AvatarProps, type AvatarImageProps, type AvatarFallbackProps, } from './components/avatar';
+export { Avatar, AvatarImage, AvatarFallback, avatarVariants, type AvatarProps, type AvatarImageProps, type AvatarImageStatus, type AvatarFallbackProps, } from './components/avatar';
 export { Accordion, AccordionItem, AccordionTrigger, AccordionContent, type AccordionProps, type AccordionItemProps, type AccordionTriggerProps, type AccordionContentProps, } from './components/accordion';
 export { Collapsible, CollapsibleTrigger, CollapsibleContent, type CollapsibleProps, type CollapsibleTriggerProps, type CollapsibleContentProps, } from './components/collapsible';
 export { Container, containerVariants, type ContainerProps } from './components/container';

package/dist/lib/theme-bridge.d.ts

@@ -23,7 +23,7 @@ export declare function applyThemeMode(mode: ThemeMode): void;
 export declare function resolveThemeMode(adapter?: ThemeBridgeAdapter, fallback?: ThemeMode): Promise<ThemeMode>;
 export declare function syncThemeMode(mode: ThemeMode, adapter?: ThemeBridgeAdapter): Promise<ThemeMode>;
 export declare function useThemeBridge({ initialMode, adapter, }?: UseThemeBridgeOptions): UseThemeBridgeResult;
-export declare function ThemeBridge({ mode, initialMode, adapter }: ThemeBridgeProps): import("react").FunctionComponentElement<Pick<ThemeBridgeProps, "initialMode" | "adapter">> | import("react").FunctionComponentElement<{
+export declare function ThemeBridge({ mode, initialMode, adapter }: ThemeBridgeProps): import("react").FunctionComponentElement<Pick<ThemeBridgeProps, "adapter" | "initialMode">> | import("react").FunctionComponentElement<{
     mode: ThemeMode;
     adapter?: ThemeBridgeAdapter;
 }>;

package/dist/lib/theme-bridge.js

@@ -1,6 +1,37 @@
-import { createElement, useCallback, useEffect, useMemo, useState } from 'react';
+import { createElement, useCallback, useEffect, useMemo, useReducer } from 'react';
 import { Uniwind, useUniwind } from 'uniwind';
 const modeCycle = ['light', 'dark', 'system'];
+function themeBridgeReducer(state, action) {
+    if (action.type === 'cycle') {
+        return {
+            ...state,
+            status: 'ready',
+            mode: modeCycle[(modeCycle.indexOf(state.mode) + 1) % modeCycle.length],
+        };
+    }
+    if (action.type === 'select') {
+        return { ...state, status: 'ready', mode: action.mode };
+    }
+    if (action.type === 'hydrate') {
+        if (state.adapter === action.adapter &&
+            state.initialMode === action.initialMode &&
+            state.status === (action.adapter ? 'hydrating' : 'ready')) {
+            return state;
+        }
+        return {
+            status: action.adapter ? 'hydrating' : 'ready',
+            mode: state.mode,
+            adapter: action.adapter,
+            initialMode: action.initialMode,
+        };
+    }
+    if (state.status !== 'hydrating' ||
+        state.adapter !== action.adapter ||
+        state.initialMode !== action.initialMode) {
+        return state;
+    }
+    return { ...state, status: 'ready', mode: action.mode };
+}
 export function applyThemeMode(mode) {
     Uniwind.setTheme(mode);
 }
@@ -23,16 +54,21 @@ export async function syncThemeMode(mode, adapter) {
 }
 export function useThemeBridge({ initialMode = 'system', adapter, } = {}) {
     const { theme } = useUniwind();
-    const [mode, setMode] = useState(initialMode);
-    const [hydrated, setHydrated] = useState(!adapter);
+    const [state, dispatch] = useReducer(themeBridgeReducer, {
+        status: adapter ? 'hydrating' : 'ready',
+        mode: initialMode,
+        adapter,
+        initialMode,
+    });
     useEffect(() => {
         let mounted = true;
+        dispatch({ type: 'hydrate', adapter, initialMode });
         if (!adapter) {
             return;
         }
         // `loadThemeMode` is the consumer's storage. If it rejects — a corrupt store, a
         // keychain prompt the user dismissed — the app must still render in the initial
-        // mode; leaving `hydrated` false would strand anything gated on it forever.
+        // mode rather than remaining in the hydrating phase forever.
         void (async () => {
             let next;
             try {
@@ -44,35 +80,33 @@ export function useThemeBridge({ initialMode = 'system', adapter, } = {}) {
             if (!mounted) {
                 return;
             }
-            setMode(next);
-            setHydrated(true);
+            dispatch({ type: 'hydrated', adapter, initialMode, mode: next });
         })();
         return () => {
             mounted = false;
         };
     }, [adapter, initialMode]);
     useEffect(() => {
-        if (!hydrated) {
+        if (state.status !== 'ready' ||
+            state.adapter !== adapter ||
+            state.initialMode !== initialMode) {
             return;
         }
-        applyThemeMode(mode);
+        applyThemeMode(state.mode);
         if (adapter) {
-            void adapter.saveThemeMode(mode);
+            void adapter.saveThemeMode(state.mode);
         }
-    }, [adapter, hydrated, mode]);
-    const cycleMode = useCallback(() => {
-        setMode((currentMode) => {
-            const currentIndex = modeCycle.indexOf(currentMode);
-            const nextIndex = (currentIndex + 1) % modeCycle.length;
-            return modeCycle[nextIndex];
-        });
+    }, [adapter, initialMode, state]);
+    const setMode = useCallback((mode) => {
+        dispatch({ type: 'select', mode });
     }, []);
+    const cycleMode = useCallback(() => dispatch({ type: 'cycle' }), []);
     return useMemo(() => ({
-        mode,
+        mode: state.mode,
         resolvedTheme: theme,
         setMode,
         cycleMode,
-    }), [cycleMode, mode, theme]);
+    }), [cycleMode, setMode, state.mode, theme]);
 }
 function ControlledThemeBridge({ mode, adapter, }) {
     useEffect(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thewhileloop/whileui",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "WhileUI Native — Copy-paste components for React Native. You own the code.",
   "license": "MIT",
   "repository": {