@mrmeg/expo-ui 0.17.0 → 0.20.0

package/dist/components/Carousel.d.ts

@@ -0,0 +1,73 @@
+import React from "react";
+import { type StyleProp, type ViewStyle } from "react-native";
+export interface CarouselProps {
+    /** Slides to page through. Each child is wrapped in a fixed-width slide. */
+    children?: React.ReactNode;
+    /**
+     * Slide width. Values `<= 1` are a fraction of the carousel's own width —
+     * the default `0.85` leaves the next slide peeking. Values `> 1` are
+     * absolute pixels.
+     * @default 0.85
+     */
+    itemWidth?: number;
+    /** Space between slides. @default spacing.md */
+    gap?: number;
+    /** Horizontal inset before the first and after the last slide. @default spacing.lg */
+    contentPadding?: number;
+    /** Render the dot indicators. Auto-hidden for a single slide. @default true */
+    showDots?: boolean;
+    /** Slide shown on mount. @default 0 */
+    initialIndex?: number;
+    /** Called with the new active index whenever it changes. */
+    onIndexChange?: (index: number) => void;
+    /** Snap to slide boundaries. @default true */
+    snap?: boolean;
+    /** Custom style override for the outer container. */
+    style?: StyleProp<ViewStyle>;
+    /** Custom style override for the scroll content row. */
+    contentContainerStyle?: StyleProp<ViewStyle>;
+    /**
+     * testID prefix. Emits `<testID>`, `-scroll`, `-item-<i>`, `-dots`,
+     * `-dot-<i>`, and `-status`.
+     * @default "carousel"
+     */
+    testID?: string;
+}
+/**
+ * Active slide index for a horizontal scroll offset.
+ *
+ * `interval` is the slide pitch (item width + gap), so page `i` sits at
+ * `i * interval` for both the native snap offsets and web's CSS scroll-snap
+ * (see `scrollPaddingLeft` below). Clamped to `[0, count - 1]` so rubber-band
+ * overscroll at either end can't report an out-of-range page. Returns `0` for
+ * a degenerate interval — which is also the pre-measurement state on the
+ * server.
+ */
+export declare function getCarouselIndex(offsetX: number, interval: number, count: number): number;
+/** Resolves the `itemWidth` prop against a container width (fraction vs px). */
+export declare function resolveCarouselItemWidth(itemWidth: number, containerWidth: number): number;
+/**
+ * Carousel Component
+ *
+ * Horizontally snapping row of slides with dot indicators and an optional
+ * peek of the next slide. Children-based: every child becomes one slide at the
+ * resolved item width.
+ *
+ * Built on `ScrollView` — not a virtualized list — on purpose: every slide is
+ * in the server-rendered tree, so web SSR ships the real content instead of an
+ * empty scroller that only fills in after measurement. Snapping uses the
+ * platform scroller (`snapToInterval` on native, CSS scroll-snap on web); no
+ * animation library is involved.
+ *
+ * @example
+ * ```tsx
+ * <Carousel itemWidth={0.8} onIndexChange={setPage}>
+ *   {testimonials.map((t) => (
+ *     <Card key={t.name}>
+ *       <BodyText>{t.quote}</BodyText>
+ *     </Card>
+ *   ))}
+ * </Carousel>
+ * ```
+ */
+export declare function Carousel({ children, itemWidth, gap, contentPadding, showDots, initialIndex, onIndexChange, snap, style: styleOverride, contentContainerStyle, testID, }: CarouselProps): React.JSX.Element;

package/dist/components/Carousel.js

@@ -0,0 +1,184 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { Platform, ScrollView, StyleSheet, Text, View, } from "react-native";
+import { useTheme } from "../hooks/useTheme.js";
+import { useDimensions } from "../hooks/useDimensions.js";
+import { spacing } from "../constants/spacing.js";
+import { createThemedStyles } from "../lib/themedStyles.js";
+// ============================================================================
+// Index math
+// ============================================================================
+/**
+ * Active slide index for a horizontal scroll offset.
+ *
+ * `interval` is the slide pitch (item width + gap), so page `i` sits at
+ * `i * interval` for both the native snap offsets and web's CSS scroll-snap
+ * (see `scrollPaddingLeft` below). Clamped to `[0, count - 1]` so rubber-band
+ * overscroll at either end can't report an out-of-range page. Returns `0` for
+ * a degenerate interval — which is also the pre-measurement state on the
+ * server.
+ */
+export function getCarouselIndex(offsetX, interval, count) {
+    if (!Number.isFinite(offsetX) || !Number.isFinite(interval))
+        return 0;
+    if (interval <= 0 || count <= 0)
+        return 0;
+    const raw = Math.round(offsetX / interval);
+    if (raw < 0)
+        return 0;
+    if (raw > count - 1)
+        return count - 1;
+    return raw;
+}
+/** Resolves the `itemWidth` prop against a container width (fraction vs px). */
+export function resolveCarouselItemWidth(itemWidth, containerWidth) {
+    if (!Number.isFinite(itemWidth) || itemWidth <= 0)
+        return 0;
+    if (itemWidth > 1)
+        return Math.round(itemWidth);
+    if (!Number.isFinite(containerWidth) || containerWidth <= 0)
+        return 0;
+    return Math.round(containerWidth * itemWidth);
+}
+function clampIndex(index, count) {
+    if (count <= 0)
+        return 0;
+    return Math.min(count - 1, Math.max(0, Math.trunc(index)));
+}
+// ============================================================================
+// Carousel
+// ============================================================================
+/**
+ * Carousel Component
+ *
+ * Horizontally snapping row of slides with dot indicators and an optional
+ * peek of the next slide. Children-based: every child becomes one slide at the
+ * resolved item width.
+ *
+ * Built on `ScrollView` — not a virtualized list — on purpose: every slide is
+ * in the server-rendered tree, so web SSR ships the real content instead of an
+ * empty scroller that only fills in after measurement. Snapping uses the
+ * platform scroller (`snapToInterval` on native, CSS scroll-snap on web); no
+ * animation library is involved.
+ *
+ * @example
+ * ```tsx
+ * <Carousel itemWidth={0.8} onIndexChange={setPage}>
+ *   {testimonials.map((t) => (
+ *     <Card key={t.name}>
+ *       <BodyText>{t.quote}</BodyText>
+ *     </Card>
+ *   ))}
+ * </Carousel>
+ * ```
+ */
+export function Carousel({ children, itemWidth = 0.85, gap = spacing.md, contentPadding = spacing.lg, showDots = true, initialIndex = 0, onIndexChange, snap = true, style: styleOverride, contentContainerStyle, testID = "carousel", }) {
+    const { theme } = useTheme();
+    const styles = themedStyles(theme);
+    const items = React.Children.toArray(children);
+    const count = items.length;
+    // Width source of truth: the measured container after mount, seeded from the
+    // viewport so the server and the client's first render agree. `useDimensions`
+    // reads the SSR viewport context rather than `window`, which is what keeps
+    // that seed hydration-safe (docs/ssr-hydration.md §4).
+    const { width: viewportWidth } = useDimensions();
+    const [measuredWidth, setMeasuredWidth] = useState(null);
+    const containerWidth = measuredWidth ?? viewportWidth;
+    const slideWidth = resolveCarouselItemWidth(itemWidth, containerWidth);
+    const interval = slideWidth + gap;
+    const [activeIndex, setActiveIndex] = useState(() => clampIndex(initialIndex, count));
+    // Mirrors activeIndex so the scroll handler can dedupe without re-reading
+    // state: one settle emits many scroll events, onIndexChange must fire once.
+    const activeIndexRef = useRef(activeIndex);
+    const scrollRef = useRef(null);
+    const hasScrolledToInitial = useRef(false);
+    const commitIndex = useCallback((next) => {
+        if (next === activeIndexRef.current)
+            return;
+        activeIndexRef.current = next;
+        setActiveIndex(next);
+        onIndexChange?.(next);
+    }, [onIndexChange]);
+    const handleScroll = useCallback((event) => {
+        commitIndex(getCarouselIndex(event.nativeEvent.contentOffset.x, interval, count));
+    }, [commitIndex, count, interval]);
+    const handleLayout = useCallback((event) => {
+        const next = event.nativeEvent.layout.width;
+        if (!(next > 0))
+            return;
+        setMeasuredWidth((current) => current !== null && Math.abs(current - next) < 1 ? current : next);
+    }, []);
+    // Jump to initialIndex once, after the first real layout — the seeded
+    // viewport width would put the offset in the wrong place. `contentOffset` is
+    // iOS-only, so drive it imperatively for Android/web parity.
+    const targetIndex = clampIndex(initialIndex, count);
+    useEffect(() => {
+        if (hasScrolledToInitial.current || measuredWidth === null || interval <= 0)
+            return;
+        hasScrolledToInitial.current = true;
+        if (targetIndex === 0)
+            return;
+        scrollRef.current?.scrollTo({ x: targetIndex * interval, animated: false });
+    }, [interval, measuredWidth, targetIndex]);
+    const isWeb = Platform.OS === "web";
+    const useCssSnap = isWeb && snap;
+    const dotsVisible = showDots && count > 1;
+    return (_jsxs(View, { style: [styles.container, styleOverride], onLayout: handleLayout, testID: testID, children: [_jsx(ScrollView, { ref: scrollRef, testID: `${testID}-scroll`, horizontal: true, showsHorizontalScrollIndicator: false, 
+                // Native snapping. react-native-web drops these (they aren't in its
+                // forwarded-prop list), so web uses the CSS scroll-snap styles instead.
+                snapToInterval: snap && interval > 0 ? interval : undefined, snapToAlignment: "start", decelerationRate: snap ? "fast" : "normal", 
+                // react-native-web only emits scroll ticks when the throttle is > 0 and
+                // never emits momentum events — this is what keeps the dots live for
+                // wheel/trackpad scrolling.
+                scrollEventThrottle: 16, onScroll: handleScroll, onMomentumScrollEnd: handleScroll, style: useCssSnap
+                    ? [webStyles.scroller, { scrollPaddingLeft: contentPadding }]
+                    : undefined, contentContainerStyle: [{ paddingHorizontal: contentPadding, gap }, contentContainerStyle], children: items.map((child, index) => (_jsx(View, { testID: `${testID}-item-${index}`, style: [slideWidth > 0 && { width: slideWidth }, useCssSnap && webStyles.item], children: child }, React.isValidElement(child) && child.key != null ? child.key : index))) }), count > 1 && (_jsx(View, { testID: `${testID}-status`, style: styles.status, "aria-live": "polite", children: _jsx(Text, { style: styles.statusText, children: `${activeIndex + 1} of ${count}` }) })), dotsVisible && (_jsx(View, { testID: `${testID}-dots`, style: styles.dots, accessibilityRole: "tablist", children: items.map((_, index) => (_jsx(View, { testID: `${testID}-dot-${index}`, accessibilityRole: "tab", accessibilityState: { selected: index === activeIndex }, accessibilityLabel: `Slide ${index + 1} of ${count}`, style: [styles.dot, index === activeIndex ? styles.dotActive : styles.dotInactive] }, index))) }))] }));
+}
+// ============================================================================
+// Styles
+// ============================================================================
+const DOT_SIZE = 8;
+// Web-only CSS scroll-snap. `scrollPaddingLeft` is applied inline at the call
+// site (it tracks the contentPadding prop) so the leading inset survives the
+// browser snapping slide 0 to the scrollport start — which also makes page `i`
+// land on `i * interval`, matching the native snap offsets.
+const webStyles = StyleSheet.create({
+    scroller: { scrollSnapType: "x mandatory" },
+    item: { scrollSnapAlign: "start" },
+});
+const createStyles = (theme) => StyleSheet.create({
+    container: {
+        width: "100%",
+    },
+    // Clipped to 1x1 rather than removed: screen readers skip
+    // display:none/opacity:0 nodes, and there is no visual affordance to show.
+    status: {
+        position: "absolute",
+        width: 1,
+        height: 1,
+        overflow: "hidden",
+    },
+    statusText: {
+        fontSize: 1,
+        color: "transparent",
+    },
+    dots: {
+        flexDirection: "row",
+        alignItems: "center",
+        justifyContent: "center",
+        gap: spacing.xs,
+        marginTop: spacing.md,
+    },
+    dot: {
+        width: DOT_SIZE,
+        height: DOT_SIZE,
+        borderRadius: spacing.radiusFull,
+    },
+    dotActive: {
+        backgroundColor: theme.colors.accent,
+    },
+    dotInactive: {
+        backgroundColor: theme.colors.border,
+    },
+});
+const themedStyles = createThemedStyles(createStyles);

package/dist/components/Drawer.js

@@ -395,7 +395,9 @@ function DrawerOverlayContent({ swipeEnabled = true, swipeThreshold = 0.3, veloc
         bottom: 0,
         width,
         [side]: 0,
-        backgroundColor: theme.colors.background,
+        // App chrome sits on the sunken tier so it reads as a layer beneath the
+        // content pane rather than the same surface.
+        backgroundColor: theme.colors.surfaceSunken,
         borderColor: theme.colors.border,
         ...(side === "left"
             ? { borderRightWidth: 1 }
@@ -502,7 +504,8 @@ swipeEnabled: _swipeEnabled, swipeThreshold: _swipeThreshold, velocityThreshold:
     const panelStyle = {
         width: Platform.OS === "web" ? targetWidth : widthAnim,
         overflow: "hidden",
-        backgroundColor: theme.colors.background,
+        // Rail chrome sits on the sunken tier, one step below the content pane.
+        backgroundColor: theme.colors.surfaceSunken,
         borderColor: theme.colors.border,
         ...(side === "left" ? { borderRightWidth: 1 } : { borderLeftWidth: 1 }),
         paddingTop: insets.top,

package/dist/components/index.d.ts

@@ -1,10 +1,12 @@
 export * from "./Accordion";
 export * from "./Alert";
 export * from "./AnimatedView";
+export * from "./Avatar";
 export * from "./Badge";
 export * from "./BottomSheet";
 export * from "./Button";
 export * from "./Card";
+export * from "./Carousel";
 export * from "./Checkbox";
 export * from "./Collapsible";
 export * from "./Dialog";

package/dist/components/index.js

@@ -1,10 +1,12 @@
 export * from "./Accordion.js";
 export * from "./Alert.js";
 export * from "./AnimatedView.js";
+export * from "./Avatar.js";
 export * from "./Badge.js";
 export * from "./BottomSheet.js";
 export * from "./Button.js";
 export * from "./Card.js";
+export * from "./Carousel.js";
 export * from "./Checkbox.js";
 export * from "./Collapsible.js";
 export * from "./Dialog.js";

package/dist/constants/colors.d.ts

@@ -22,11 +22,13 @@ declare const palette: {
     readonly gray900: "#18181B";
     readonly gray950: "#09090B";
     readonly black: "#000000";
+    readonly dark950: "#050506";
     readonly dark900: "#09090B";
     readonly dark800: "#18181B";
     readonly dark700: "#27272A";
     readonly dark600: "#3F3F46";
     readonly dark400: "#A1A1AA";
+    readonly dark350: "#B0B0B8";
     readonly dark300: "#D4D4D8";
     readonly dark100: "#F4F4F5";
     readonly green500: "#22C55E";
@@ -40,6 +42,7 @@ declare const palette: {
  * Semantic color interface - what colors mean in the UI
  */
 export interface ThemeColors {
+    surfaceSunken: string;
     background: string;
     foreground: string;
     card: string;
@@ -61,6 +64,7 @@ export interface ThemeColors {
     success: string;
     warning: string;
     border: string;
+    borderStrong: string;
     input: string;
     ring: string;
     overlay: string;

package/dist/constants/colors.js

@@ -25,11 +25,15 @@ const palette = {
     gray950: "#09090B",
     black: "#000000",
     // Dark mode surfaces — zinc-based
+    // `dark950` sits below zinc-950 as the app-chrome tier; `dark350` is a
+    // zinc-350 midpoint used for dim text that stays comfortably readable.
+    dark950: "#050506",
     dark900: "#09090B",
     dark800: "#18181B",
     dark700: "#27272A",
     dark600: "#3F3F46",
     dark400: "#A1A1AA",
+    dark350: "#B0B0B8",
     dark300: "#D4D4D8",
     dark100: "#F4F4F5",
     // Status
@@ -44,6 +48,7 @@ const lightTheme = {
     dark: false,
     fonts: navigationFonts,
     colors: {
+        surfaceSunken: palette.gray50,
         background: palette.white,
         foreground: palette.gray950,
         card: palette.white,
@@ -51,13 +56,13 @@ const lightTheme = {
         popover: palette.white,
         popoverForeground: palette.gray950,
         text: palette.gray950,
-        textDim: palette.gray500,
+        textDim: palette.gray600,
         primary: palette.gray900,
         primaryForeground: palette.gray50,
         secondary: palette.gray100,
         secondaryForeground: palette.gray900,
         muted: palette.gray100,
-        mutedForeground: palette.gray500,
+        mutedForeground: palette.gray600,
         accent: palette.teal500,
         accentForeground: palette.white,
         destructive: palette.red500,
@@ -65,6 +70,7 @@ const lightTheme = {
         success: palette.green500,
         warning: palette.amber500,
         border: palette.gray200,
+        borderStrong: palette.gray300,
         input: palette.gray200,
         ring: palette.gray400,
         overlay: "rgba(0, 0, 0, 0.5)",
@@ -82,6 +88,7 @@ const darkTheme = {
     dark: true,
     fonts: navigationFonts,
     colors: {
+        surfaceSunken: palette.dark950,
         background: palette.dark900,
         foreground: palette.dark100,
         card: palette.dark800,
@@ -89,13 +96,13 @@ const darkTheme = {
         popover: palette.dark800,
         popoverForeground: palette.dark100,
         text: palette.dark100,
-        textDim: palette.dark400,
+        textDim: palette.dark350,
         primary: palette.gray50,
         primaryForeground: palette.gray900,
         secondary: palette.gray800,
         secondaryForeground: palette.gray50,
         muted: palette.dark700,
-        mutedForeground: palette.dark400,
+        mutedForeground: palette.dark350,
         accent: palette.teal400,
         accentForeground: palette.gray900,
         destructive: palette.red400,
@@ -103,6 +110,7 @@ const darkTheme = {
         success: palette.green400,
         warning: palette.amber400,
         border: palette.dark700,
+        borderStrong: palette.dark600,
         input: palette.dark700,
         ring: palette.dark400,
         overlay: "rgba(0, 0, 0, 0.7)",

package/dist/hooks/useResources.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Registers the Feather icon font in expo-font's per-request SSR store.
+ *
+ * Must be called from a **render body** on server-web (see `useResources`
+ * below): expo-font enters an `AsyncLocalStorage` store per request, so a
+ * module-scope registration lands in at most one request's store. Registering
+ * during render means every request emits the `@font-face` rule into
+ * `<style id="expo-generated-fonts">` and server-rendered `<Icon>`s agree with
+ * the client's first render.
+ *
+ * No-op on native and on client web (both already covered: native by the
+ * effect below, client web by the module-scope call above).
+ */
+export declare function ensureIconFontRegistered(): void;
 interface LoadResourcesResult {
     loaded: boolean;
     error: Error | null;

package/dist/hooks/useResources.js

@@ -4,15 +4,45 @@ import Feather from "@expo/vector-icons/Feather";
 import { Inter_400Regular, Inter_500Medium, Inter_600SemiBold, Inter_700Bold, } from "@expo-google-fonts/inter";
 import { Platform } from "react-native";
 import { useThemeStore } from "../state/themeStore.js";
-// Eager, module-scope load so expo-font registers Feather in its SSR
-// serverContext. When the server renders the HTML document, expo-font emits
-// an @font-face <style> into the head — without this kickoff, server-rendered
-// <Icon> components paint as empty glyphs until hydration runs the effect
-// below, producing a visible icon-pop flash on icon-heavy SSR screens
-// (e.g. OnboardingFlow). On the client this also primes the font ahead of
-// the effect; the effect's loadAsync becomes a no-op for the already-loaded
-// font.
-void Font.loadAsync(Feather.font);
+// Eager, module-scope load that primes the Feather font on the *client* before
+// first render: on web it synchronously injects the @font-face rule, which is
+// what makes the client's `Font.isLoaded("feather")` check read true during
+// hydration; on native it just starts the fetch ahead of the effect below
+// (which then no-ops for the already-loaded font).
+//
+// Deliberately guarded off server-web. expo-font's SSR store is per-request
+// AsyncLocalStorage, and Metro's inlineRequires defers this module's evaluation
+// until it is first required during a render — so on the server this line only
+// ever populated the store of whichever request happened to warm the module
+// cache. Requests 2+ then shipped HTML with no @font-face and empty icons while
+// the client rendered glyphs (React #418). Server registration happens
+// per-request in ensureIconFontRegistered() instead.
+if (typeof window !== "undefined") {
+    void Font.loadAsync(Feather.font);
+}
+/**
+ * Registers the Feather icon font in expo-font's per-request SSR store.
+ *
+ * Must be called from a **render body** on server-web (see `useResources`
+ * below): expo-font enters an `AsyncLocalStorage` store per request, so a
+ * module-scope registration lands in at most one request's store. Registering
+ * during render means every request emits the `@font-face` rule into
+ * `<style id="expo-generated-fonts">` and server-rendered `<Icon>`s agree with
+ * the client's first render.
+ *
+ * No-op on native and on client web (both already covered: native by the
+ * effect below, client web by the module-scope call above).
+ */
+export function ensureIconFontRegistered() {
+    if (Platform.OS !== "web" || typeof window !== "undefined")
+        return;
+    if (Font.isLoaded("feather"))
+        return; // per-request store; cheap
+    // Synchronous on server-web (expo-font routes to registerStaticFont). No
+    // `void`/try-catch: a throw here means we're outside a request scope, which
+    // must be loud.
+    Font.loadAsync(Feather.font);
+}
 // The four static Inter weights StyledText's native family keys point at
 // (see constants/fonts.ts). Native-only: web never renders these family names
 // ("Inter_400Regular" etc.) — fontFamilies.sansSerif resolves every weight to
@@ -66,6 +96,10 @@ function ensureWebFontStylesheet() {
  * un-download Inter. The Feather icon font always loads.
  */
 export const useResources = () => {
+    // Render-body (not effect) so server-web registers the icon font in *this*
+    // request's expo-font store — effects never run on the server and a
+    // module-scope call only reaches one request. See ensureIconFontRegistered.
+    ensureIconFontRegistered();
     const [loaded, setLoaded] = useState(false);
     const [error, setError] = useState(null);
     useEffect(() => {

package/dist/hooks/useTheme.js

@@ -3,6 +3,7 @@ import { colors } from "../constants/colors.js";
 import { Platform, StyleSheet } from "react-native";
 import { resolveThemePreference, useThemeStore } from "../state/themeStore.js";
 import { useThemeColorScope } from "../state/themeColorScope.js";
+import { useSsrThemeSeed } from "../state/ssrTheme.js";
 import { spacing as spacingConstants } from "../constants/spacing.js";
 // Module-level cache for contrast calculations to avoid memory leak
 // and share across components
@@ -45,11 +46,24 @@ function getCachedOrCompute(key, compute) {
  * - getShadowStyle('base') → { boxShadow: "0px 2px 6px rgba(0, 0, 0, 0.05), 0px 4px 12px rgba(0, 0, 0, 0.03)" }
  */
 export function useTheme() {
-    const userTheme = useThemeStore((s) => s.userTheme);
-    const systemTheme = useThemeStore((s) => s.systemTheme);
+    const storeUserTheme = useThemeStore((s) => s.userTheme);
+    const storeSystemTheme = useThemeStore((s) => s.systemTheme);
+    const hasLoadedTheme = useThemeStore((s) => s.hasLoadedTheme);
     const setTheme = useThemeStore((s) => s.setTheme);
     const colorOverrides = useThemeStore((s) => s.colorOverrides);
     const scoped = useThemeColorScope();
+    const seed = useSsrThemeSeed();
+    // Before persistence has been read, a web render must resolve from the
+    // per-request SSR seed instead of store state. The store is a module
+    // singleton shared across concurrent SSR requests, so it can only ever hold
+    // the SSR-safe boot defaults ("system"/light); the seed is cookie-derived,
+    // which is the one signal the server and the browser read identically —
+    // that's what keeps the hydrated tree matching the server HTML. After mount
+    // `syncThemeFromEnvironment()` flips `hasLoadedTheme` and store state (real
+    // localStorage/AsyncStorage + live OS listener) takes over for good.
+    const useSeed = Platform.OS === "web" && !hasLoadedTheme;
+    const userTheme = useSeed ? seed.userTheme : storeUserTheme;
+    const systemTheme = useSeed ? seed.systemTheme : storeSystemTheme;
     // Determine which theme to use (user preference or system)
     const effectiveScheme = resolveThemePreference(userTheme, systemTheme);
     const base = colors[effectiveScheme];

package/dist/state/index.d.ts

@@ -2,4 +2,5 @@ export * from "./globalUIStore";
 export * from "./notify";
 export * from "./themeStore";
 export * from "./themeColorScope";
+export * from "./ssrTheme";
 export * from "./SsrViewportContext";

package/dist/state/index.js

@@ -2,4 +2,5 @@ export * from "./globalUIStore.js";
 export * from "./notify.js";
 export * from "./themeStore.js";
 export * from "./themeColorScope.js";
+export * from "./ssrTheme.js";
 export * from "./SsrViewportContext.js";

package/dist/state/ssrTheme.d.ts

@@ -0,0 +1,41 @@
+import type { ResolvedTheme, ThemePreference } from "./themeStore";
+/**
+ * The theme values the FIRST render must use on web — server and client alike.
+ *
+ * `useThemeStore` is a module singleton shared by every concurrent SSR request,
+ * so a per-request theme can never be written into it. This context is the
+ * per-request channel instead: the host app resolves it from the request (a
+ * cookie the client mirrors) and provides it above the tree, and `useTheme`
+ * reads it until the store has loaded real persistence after mount.
+ */
+export type SsrThemeSeed = {
+    userTheme: ThemePreference;
+    systemTheme: ResolvedTheme;
+};
+/**
+ * What a first-time visitor gets: no persisted preference, light scheme. Same
+ * values the store boots with, so a host app that never provides the context
+ * behaves exactly as it did before the seed existed.
+ */
+export declare const SSR_THEME_SEED_DEFAULT: SsrThemeSeed;
+/**
+ * Per-request theme seed consumed by `useTheme`/`useStyles` while
+ * `hasLoadedTheme` is false (i.e. on the server render and the client's first
+ * render, before `syncThemeFromEnvironment()` reads real persistence).
+ *
+ * Provide it near the top of the tree from a value BOTH the server and the
+ * browser can derive from the same bytes — a cookie. Reading `localStorage`
+ * for this would reintroduce the hydration mismatch it exists to remove,
+ * because the server cannot see `localStorage`.
+ *
+ * ```tsx
+ * import { SsrThemeSeedContext } from "@mrmeg/expo-ui/state";
+ *
+ * <SsrThemeSeedContext.Provider value={seedFromCookie}>
+ *   <App />
+ * </SsrThemeSeedContext.Provider>
+ * ```
+ */
+export declare const SsrThemeSeedContext: import("react").Context<SsrThemeSeed>;
+/** Read the active SSR theme seed (the default when no provider is mounted). */
+export declare function useSsrThemeSeed(): SsrThemeSeed;

package/dist/state/ssrTheme.js

@@ -0,0 +1,33 @@
+import { createContext, use } from "react";
+/**
+ * What a first-time visitor gets: no persisted preference, light scheme. Same
+ * values the store boots with, so a host app that never provides the context
+ * behaves exactly as it did before the seed existed.
+ */
+export const SSR_THEME_SEED_DEFAULT = {
+    userTheme: "system",
+    systemTheme: "light",
+};
+/**
+ * Per-request theme seed consumed by `useTheme`/`useStyles` while
+ * `hasLoadedTheme` is false (i.e. on the server render and the client's first
+ * render, before `syncThemeFromEnvironment()` reads real persistence).
+ *
+ * Provide it near the top of the tree from a value BOTH the server and the
+ * browser can derive from the same bytes — a cookie. Reading `localStorage`
+ * for this would reintroduce the hydration mismatch it exists to remove,
+ * because the server cannot see `localStorage`.
+ *
+ * ```tsx
+ * import { SsrThemeSeedContext } from "@mrmeg/expo-ui/state";
+ *
+ * <SsrThemeSeedContext.Provider value={seedFromCookie}>
+ *   <App />
+ * </SsrThemeSeedContext.Provider>
+ * ```
+ */
+export const SsrThemeSeedContext = createContext(SSR_THEME_SEED_DEFAULT);
+/** Read the active SSR theme seed (the default when no provider is mounted). */
+export function useSsrThemeSeed() {
+    return use(SsrThemeSeedContext);
+}

package/dist/state/themeStore.d.ts

@@ -2,6 +2,16 @@ import type { ThemeColors } from "../constants/colors";
 import type { FontOverrides } from "../constants/fonts";
 export type ThemePreference = "system" | "light" | "dark";
 export type ResolvedTheme = "light" | "dark";
+/**
+ * Cookie name the web build mirrors the persisted preference into, so a
+ * server-rendered host can seed its first render with the visitor's real
+ * theme instead of shipping a light tree that recolors after hydration.
+ *
+ * Same name as the `localStorage` key on purpose: one string to grep, and the
+ * blocking color-scheme script in a host's `+html.tsx` already reads it.
+ * `localStorage` stays the source of truth; the cookie is a render hint only.
+ */
+export declare const THEME_COOKIE_NAME = "user-theme-preference";
 /**
  * Per-scheme color overrides a host app can inject to brand the package.
  *
@@ -44,6 +54,15 @@ export type ShapeOverrides = {
 export type ThemeStore = {
     userTheme: ThemePreference;
     systemTheme: ResolvedTheme;
+    /**
+     * True once the persisted preference has actually been read (or explicitly
+     * set by the user). Until then, a web render must not trust `userTheme` /
+     * `systemTheme` — they still hold the SSR-safe boot defaults, and `useTheme`
+     * uses `SsrThemeSeedContext` (cookie-derived, identical on server and
+     * client) instead. Mirrors `hasLoadedOnboarding` in the host app's
+     * onboarding store.
+     */
+    hasLoadedTheme: boolean;
     /**
      * App-injected palette overrides, applied by `useTheme` on top of the
      * package defaults. Empty by default — zero override means the package