@mrmeg/expo-ui 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -3,6 +3,58 @@
 All notable changes to `@mrmeg/expo-ui` are documented here. This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.22.0]
+
+### Added
+
+- **CSS-variable theming on web.** On web, every semantic theme color
+  (`theme.colors.*`) now resolves to a CSS custom property
+  (`var(--c-<kebab-token>)`) instead of a literal hex string, so styles built
+  from the theme — including the HTML shells baked at export time — re-theme
+  purely in CSS when `html[data-theme]` changes. Native platforms keep
+  literal values. New exports from `constants`:
+  - `getThemeCssVariables(overrides?)` — the `--c-*` (and companion
+    `--c-*-rgb` triplet) definitions per scheme, for embedding in an app's
+    `+html.tsx` global `<style>`. Accepts per-scheme brand-color overrides.
+  - `rawThemeColors.light/.dark` — the literal hex/rgba maps on every
+    platform, for sinks that cannot take `var()` (e.g.
+    `<meta name="theme-color">`).
+  - `resolveRawColor(color, scheme)` — maps a `var(--c-*)` theme color back
+    to the given scheme's literal value; literal inputs pass through.
+- **`withAlpha` is exported standalone** (in addition to the `useTheme`
+  return) so module-scope style factories can import it. It understands
+  `var(--c-*)` inputs and rewrites them onto the `--c-*-rgb` triplet
+  (`var(--c-unset, rgba(var(--c-x-rgb), a))` — the never-defined outer
+  variable makes react-native-web's compiler pass the value through), staying
+  pure CSS that re-themes with the variable. Hex-suffix alpha concatenation
+  (`theme.colors.x + "15"`) does not work with `var()` colors — use
+  `withAlpha(theme.colors.x, 0.08)`.
+
+### Changed
+
+- The contrast helpers from `useTheme` (`getContrastingColor`,
+  `getContrastRatio`, `getTextColorForBackground`) resolve `var(--c-*)`
+  inputs to the active scheme's literal value before parsing, and
+  `getContrastingColor` returns the winning candidate as originally passed
+  (a `var()` input stays a `var()` output).
+- The React Navigation theme maps (`colors.<scheme>.navigation`) stay
+  literal on web as well as native: @react-navigation internals parse their
+  theme colors with a color library, which cannot take `var()` references.
+
+## [0.21.1]
+
+### Fixed
+
+- **Exported web HTML renders icon glyphs, fixing React hydration error
+  #418 on every cold load.** `useResources` registers the Feather icon font
+  per render scope during `expo export`'s Node rendering
+  (`ensureIconFontRegistered`), so the static shell emits the glyph and its
+  font styles. Previously the shell contained an empty icon text node while
+  the client's first render (font pre-loaded at module scope) contained the
+  glyph — React 19 threw #418 and regenerated the tree on every cold load.
+  The same mechanism existed during the request-time SSR era and was removed
+  with it; static export needs it too.
+
 ## [0.21.0]
 
 ### Added

package/dist/components/BottomSheet.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { createContext, use, useCallback, useEffect, useMemo, useReducer, useRef, useSyncExternalStore } from "react";
 import { View, Pressable, StyleSheet, ScrollView, Platform, Animated, useWindowDimensions, } from "react-native";
 import { BottomSheet as NativeBottomSheet } from "@expo/ui/community/bottom-sheet";
-import { KeyboardController } from "react-native-keyboard-controller";
+import { KeyboardController } from "./keyboardController";
 import { useSafeAreaInsets, initialWindowMetrics } from "react-native-safe-area-context";
 import { useTheme } from "../hooks/useTheme.js";
 import { spacing } from "../constants/spacing.js";

package/dist/components/DismissKeyboard.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import React from "react";
 import { Platform, ScrollView, View, } from "react-native";
-import { KeyboardController, useKeyboardContext, useKeyboardState, } from "react-native-keyboard-controller";
+import { KeyboardController, useKeyboardContext, useKeyboardState, } from "./keyboardController";
 import { KeyboardAvoidingView, useKeyboardAvoidance } from "./KeyboardAvoidingView.js";
 import { isTouchInsideKeyboardFocusedInput } from "./keyboardFocusRegistry.js";
 /**

package/dist/components/KeyboardAvoidingView.d.ts

@@ -13,8 +13,10 @@ export declare function useKeyboardAvoidance(): boolean;
 /**
  * Package-level keyboard avoiding wrapper.
  *
- * Native uses `react-native-keyboard-controller` so screens can avoid the soft
- * keyboard with `automaticOffset`; web renders a plain `View`.
+ * Native uses `react-native-keyboard-controller` (through the platform-split
+ * `./keyboardController` module, which keeps the package out of the web bundle)
+ * so screens can avoid the soft keyboard with `automaticOffset`; web renders a
+ * plain `View`.
  */
 export declare function KeyboardAvoidingView({ children, style, behavior, automaticOffset, contentContainerStyle, keyboardVerticalOffset, ...props }: KeyboardAvoidingViewProps): React.JSX.Element;
 export {};

package/dist/components/KeyboardAvoidingView.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext } from "react";
 import { Platform, View, } from "react-native";
-import { KeyboardAvoidingView as NativeKeyboardAvoidingView, } from "react-native-keyboard-controller";
+import { NativeKeyboardAvoidingView } from "./keyboardController";
 const KeyboardAvoidanceContext = createContext(false);
 export function useKeyboardAvoidance() {
     return useContext(KeyboardAvoidanceContext);
@@ -9,8 +9,10 @@ export function useKeyboardAvoidance() {
 /**
  * Package-level keyboard avoiding wrapper.
  *
- * Native uses `react-native-keyboard-controller` so screens can avoid the soft
- * keyboard with `automaticOffset`; web renders a plain `View`.
+ * Native uses `react-native-keyboard-controller` (through the platform-split
+ * `./keyboardController` module, which keeps the package out of the web bundle)
+ * so screens can avoid the soft keyboard with `automaticOffset`; web renders a
+ * plain `View`.
  */
 export function KeyboardAvoidingView({ children, style, behavior = Platform.OS === "ios" ? "padding" : "height", automaticOffset = true, contentContainerStyle, keyboardVerticalOffset, ...props }) {
     if (Platform.OS === "web") {

package/dist/components/Notification.js

@@ -3,7 +3,7 @@ import { useCallback, use, useEffect, useEffectEvent, useRef } from "react";
 import { Animated, Easing, StyleSheet, View, ActivityIndicator, Pressable, Platform } from "react-native";
 import { SafeAreaInsetsContext } from "react-native-safe-area-context";
 import { Icon } from "./Icon.js";
-import { useTheme } from "../hooks/useTheme.js";
+import { useTheme, withAlpha } from "../hooks/useTheme.js";
 import { useReducedMotion } from "../hooks/useReduceMotion.js";
 import { spacing } from "../constants/spacing.js";
 import { durations } from "../constants/motion.js";
@@ -158,26 +158,26 @@ export const Notification = () => {
                 return {
                     icon: "alert-circle",
                     color: theme.colors.destructive,
-                    bgColor: theme.colors.destructive + "15",
+                    bgColor: withAlpha(theme.colors.destructive, 0.08),
                 };
             case "success":
                 return {
                     icon: "check-circle",
                     color: theme.colors.success,
-                    bgColor: theme.colors.success + "15",
+                    bgColor: withAlpha(theme.colors.success, 0.08),
                 };
             case "warning":
                 return {
                     icon: "alert-triangle",
                     color: theme.colors.warning,
-                    bgColor: theme.colors.warning + "15",
+                    bgColor: withAlpha(theme.colors.warning, 0.08),
                 };
             case "info":
             default:
                 return {
                     icon: "info",
                     color: theme.colors.accent,
-                    bgColor: theme.colors.accent + "15",
+                    bgColor: withAlpha(theme.colors.accent, 0.08),
                 };
         }
     };
@@ -223,8 +223,8 @@ export const Notification = () => {
             ], children: [_jsx(View, { style: [styles.iconBadge, { backgroundColor: iconBgColor }], children: alert?.loading ? (_jsx(ActivityIndicator, { size: "small", color: iconColor })) : (_jsx(Icon, { name: icon, size: 18, color: iconColor })) }), _jsxs(View, { style: styles.alertContent, children: [!!title && (_jsx(StyledText, { selectable: false, size: "base", fontWeight: "semibold", style: { color: theme.colors.foreground }, numberOfLines: 1, children: title })), hasMessage && (_jsx(StyledText, { selectable: false, size: "sm", style: { color: theme.colors.mutedForeground }, numberOfLines: 2, children: message }))] }), action && (_jsx(Pressable, { style: ({ pressed }) => [
                         styles.actionButton,
                         {
-                            borderColor: theme.colors.primary + "30",
-                            backgroundColor: theme.colors.primary + "10",
+                            borderColor: withAlpha(theme.colors.primary, 0.19),
+                            backgroundColor: withAlpha(theme.colors.primary, 0.06),
                         },
                         pressed && styles.actionButtonPressed,
                     ], hitSlop: spacing.xs, onPress: handleActionPress, accessibilityLabel: action.label, accessibilityRole: "button", children: _jsx(StyledText, { selectable: false, size: "sm", fontWeight: "semibold", style: { color: theme.colors.primary }, numberOfLines: 1, children: action.label }) })), _jsx(Pressable, { style: styles.closeButton, hitSlop: spacing.sm, onPress: animateOut, accessibilityLabel: "Dismiss notification", accessibilityRole: "button", children: _jsx(Icon, { name: "x", size: 16, color: theme.colors.mutedForeground }) })] }) }));

package/dist/components/keyboardController.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Keyboard-controller indirection — web variant (inert stubs).
+ *
+ * `react-native-keyboard-controller` drags a large native animation runtime
+ * into every bundle that imports it, and none of that code can run on web.
+ * Components therefore import the keyboard API from this module instead of the
+ * package: Metro resolves `keyboardController.native.ts` (the real re-exports)
+ * on iOS/Android and this file on web, so the package never reaches the web
+ * bundle.
+ *
+ * Both variants are typed against the package's own types — type-only imports
+ * are erased at compile time and bundle nothing — so the two files stay
+ * interchangeable to the type checker. TypeScript always resolves this `.ts`
+ * variant for consumers, which is why the stubs must keep the full native
+ * signatures.
+ *
+ * Every stub here is a plain function that calls no hooks, so the `use*`
+ * exports are safe from any call site (rules of hooks can't be violated by a
+ * function that has no hook calls of its own).
+ */
+import React from "react";
+import { View } from "react-native";
+import type { IKeyboardState, KeyboardAnimationContext, KeyboardAvoidingViewProps, KeyboardControllerModule } from "react-native-keyboard-controller";
+/** No-op imperative module: there is no IME to dismiss or preload on web. */
+export declare const KeyboardController: KeyboardControllerModule;
+/**
+ * Applies `selector` to a permanently "keyboard hidden" state.
+ *
+ * @param selector - Picks the fields a caller needs from the keyboard state.
+ * @returns The selected value, or the whole state when no selector is given.
+ */
+export declare function useKeyboardState<T = IKeyboardState>(selector?: (state: IKeyboardState) => T): T;
+/**
+ * @returns A stable, empty keyboard context (no focused input layout on web).
+ */
+export declare function useKeyboardContext(): KeyboardAnimationContext;
+type NativeKeyboardAvoidingViewProps = KeyboardAvoidingViewProps & {
+    children?: React.ReactNode;
+};
+/**
+ * Plain `View` passthrough. Keyboard-avoidance props are accepted (so callers
+ * stay identical across platforms) and dropped, since the browser handles
+ * viewport resizing itself.
+ */
+export declare function NativeKeyboardAvoidingView({ behavior, contentContainerStyle, keyboardVerticalOffset, automaticOffset, enabled, children, ...viewProps }: NativeKeyboardAvoidingViewProps): React.CElement<import("react-native").ViewProps, View>;
+export {};

package/dist/components/keyboardController.js

@@ -0,0 +1,89 @@
+/**
+ * Keyboard-controller indirection — web variant (inert stubs).
+ *
+ * `react-native-keyboard-controller` drags a large native animation runtime
+ * into every bundle that imports it, and none of that code can run on web.
+ * Components therefore import the keyboard API from this module instead of the
+ * package: Metro resolves `keyboardController.native.ts` (the real re-exports)
+ * on iOS/Android and this file on web, so the package never reaches the web
+ * bundle.
+ *
+ * Both variants are typed against the package's own types — type-only imports
+ * are erased at compile time and bundle nothing — so the two files stay
+ * interchangeable to the type checker. TypeScript always resolves this `.ts`
+ * variant for consumers, which is why the stubs must keep the full native
+ * signatures.
+ *
+ * Every stub here is a plain function that calls no hooks, so the `use*`
+ * exports are safe from any call site (rules of hooks can't be violated by a
+ * function that has no hook calls of its own).
+ */
+import React from "react";
+import { View } from "react-native";
+/** There is no software keyboard to observe on web, so state is constant. */
+const HIDDEN_KEYBOARD_STATE = {
+    isVisible: false,
+    height: 0,
+    duration: 0,
+    timestamp: 0,
+    target: -1,
+    type: "default",
+    appearance: "light",
+};
+/**
+ * Inert keyboard context.
+ *
+ * The real context exposes animation values that only exist alongside the
+ * native module, so this is a minimal stand-in cast to the package's type: the
+ * only field consumers read on web-capable paths is `layout.value`. It is a
+ * module-level singleton because `DismissKeyboard` puts the context object in a
+ * `useCallback` dependency list — a fresh object per call would invalidate it
+ * on every render.
+ */
+const INERT_KEYBOARD_CONTEXT = {
+    enabled: false,
+    layout: { value: null },
+    update: () => Promise.resolve(),
+    setKeyboardHandlers: () => () => undefined,
+    setInputHandlers: () => () => undefined,
+    setEnabled: () => undefined,
+};
+/** No-op imperative module: there is no IME to dismiss or preload on web. */
+export const KeyboardController = {
+    setDefaultMode: () => undefined,
+    setInputMode: () => undefined,
+    preload: () => undefined,
+    dismiss: () => Promise.resolve(),
+    setFocusTo: () => undefined,
+    isVisible: () => false,
+    state: () => HIDDEN_KEYBOARD_STATE,
+};
+/**
+ * Applies `selector` to a permanently "keyboard hidden" state.
+ *
+ * @param selector - Picks the fields a caller needs from the keyboard state.
+ * @returns The selected value, or the whole state when no selector is given.
+ */
+export function useKeyboardState(selector) {
+    return selector ? selector(HIDDEN_KEYBOARD_STATE) : HIDDEN_KEYBOARD_STATE;
+}
+/**
+ * @returns A stable, empty keyboard context (no focused input layout on web).
+ */
+export function useKeyboardContext() {
+    return INERT_KEYBOARD_CONTEXT;
+}
+/**
+ * Plain `View` passthrough. Keyboard-avoidance props are accepted (so callers
+ * stay identical across platforms) and dropped, since the browser handles
+ * viewport resizing itself.
+ */
+export function NativeKeyboardAvoidingView({ behavior, contentContainerStyle, keyboardVerticalOffset, automaticOffset, enabled, children, ...viewProps }) {
+    // Dropped rather than forwarded so they never reach the DOM node.
+    void behavior;
+    void contentContainerStyle;
+    void keyboardVerticalOffset;
+    void automaticOffset;
+    void enabled;
+    return React.createElement(View, viewProps, children);
+}

package/dist/components/keyboardController.native.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Keyboard-controller indirection — native variant.
+ *
+ * Re-exports the real `react-native-keyboard-controller` API under the names the
+ * package's components import. See `keyboardController.ts` (the web variant)
+ * for why the components go through this module instead of importing the
+ * package directly.
+ */
+export { KeyboardController, KeyboardAvoidingView as NativeKeyboardAvoidingView, useKeyboardContext, useKeyboardState, } from "react-native-keyboard-controller";

package/dist/components/keyboardController.native.js

@@ -0,0 +1,9 @@
+/**
+ * Keyboard-controller indirection — native variant.
+ *
+ * Re-exports the real `react-native-keyboard-controller` API under the names the
+ * package's components import. See `keyboardController.ts` (the web variant)
+ * for why the components go through this module instead of importing the
+ * package directly.
+ */
+export { KeyboardController, KeyboardAvoidingView as NativeKeyboardAvoidingView, useKeyboardContext, useKeyboardState, } from "react-native-keyboard-controller";

package/dist/constants/colors.d.ts

@@ -86,5 +86,39 @@ export interface Colors {
     light: Theme;
     dark: Theme;
 }
+/**
+ * Raw hex/rgba theme colors, always literal strings on every platform. Use
+ * these for sinks that cannot take CSS `var()` — e.g. `<meta name="theme-color">`,
+ * color parsing/math — and for generating the CSS variable definitions below.
+ */
+export declare const rawThemeColors: {
+    light: ThemeColors;
+    dark: ThemeColors;
+};
+/**
+ * Resolves a theme color value to a literal color string. On web, theme
+ * colors are `var(--c-*)` references; this maps one back to the given
+ * scheme's raw hex/rgba. Literal inputs (including app override colors)
+ * pass through unchanged.
+ */
+export declare function resolveRawColor(color: string, scheme: "light" | "dark"): string;
+/**
+ * CSS custom-property definitions for every semantic theme color, for
+ * embedding in a web app's `+html.tsx` global `<style>`. Each token gets
+ * `--c-<kebab-token>` (the color value) and `--c-<kebab-token>-rgb` (a
+ * comma-separated RGB triplet, alpha stripped — `withAlpha` builds
+ * `rgba(var(--c-x-rgb), a)` from it).
+ *
+ * Light values are defined on `:root`; dark values apply under
+ * `html[data-theme="dark"]`, with a `prefers-color-scheme` fallback for the
+ * paint before any theme script stamps `data-theme`.
+ *
+ * Apps that override brand colors can pass those overrides so the emitted
+ * CSS matches their theme.
+ */
+export declare function getThemeCssVariables(overrides?: {
+    light?: Partial<ThemeColors>;
+    dark?: Partial<ThemeColors>;
+}): string;
 export declare const colors: Colors;
 export { palette };

package/dist/constants/colors.js

@@ -1,3 +1,4 @@
+import { Platform } from "react-native";
 import { navigationFonts } from "./fonts.js";
 /**
  * Raw color palette - use semantic colors in components instead
@@ -124,9 +125,98 @@ const darkTheme = {
         notification: palette.teal400,
     },
 };
-export const colors = {
-    light: lightTheme,
-    dark: darkTheme,
+/**
+ * Raw hex/rgba theme colors, always literal strings on every platform. Use
+ * these for sinks that cannot take CSS `var()` — e.g. `<meta name="theme-color">`,
+ * color parsing/math — and for generating the CSS variable definitions below.
+ */
+export const rawThemeColors = {
+    light: lightTheme.colors,
+    dark: darkTheme.colors,
 };
+const themeColorTokens = Object.keys(lightTheme.colors);
+// `surfaceSunken` → `--c-surface-sunken`
+function cssVarName(token) {
+    return `--c-${token.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+}
+// Reverse lookup: "var(--c-surface-sunken)" → "surfaceSunken"
+const varToToken = new Map(themeColorTokens.map((token) => [`var(${cssVarName(token)})`, token]));
+/**
+ * Resolves a theme color value to a literal color string. On web, theme
+ * colors are `var(--c-*)` references; this maps one back to the given
+ * scheme's raw hex/rgba. Literal inputs (including app override colors)
+ * pass through unchanged.
+ */
+export function resolveRawColor(color, scheme) {
+    const token = varToToken.get(color);
+    return token ? rawThemeColors[scheme][token] : color;
+}
+// "R, G, B" from "#RRGGBB", "#RGB", or "rgb(a)(R, G, B[, A])" (alpha dropped).
+function toRgbTriplet(value) {
+    const rgbaMatch = value.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
+    if (rgbaMatch)
+        return `${rgbaMatch[1]}, ${rgbaMatch[2]}, ${rgbaMatch[3]}`;
+    let hex = value.replace(/^#/, "");
+    if (hex.length === 3)
+        hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
+    const match = /^([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+    if (!match)
+        return null;
+    return `${parseInt(match[1], 16)}, ${parseInt(match[2], 16)}, ${parseInt(match[3], 16)}`;
+}
+/**
+ * CSS custom-property definitions for every semantic theme color, for
+ * embedding in a web app's `+html.tsx` global `<style>`. Each token gets
+ * `--c-<kebab-token>` (the color value) and `--c-<kebab-token>-rgb` (a
+ * comma-separated RGB triplet, alpha stripped — `withAlpha` builds
+ * `rgba(var(--c-x-rgb), a)` from it).
+ *
+ * Light values are defined on `:root`; dark values apply under
+ * `html[data-theme="dark"]`, with a `prefers-color-scheme` fallback for the
+ * paint before any theme script stamps `data-theme`.
+ *
+ * Apps that override brand colors can pass those overrides so the emitted
+ * CSS matches their theme.
+ */
+export function getThemeCssVariables(overrides) {
+    const declarations = (scheme) => themeColorTokens
+        .map((token) => {
+        const value = overrides?.[scheme]?.[token] ?? rawThemeColors[scheme][token];
+        const name = cssVarName(token);
+        const rgb = toRgbTriplet(value);
+        return `${name}: ${value};${rgb ? ` ${name}-rgb: ${rgb};` : ""}`;
+    })
+        .join("\n      ");
+    return `
+    :root {
+      ${declarations("light")}
+    }
+
+    @media (prefers-color-scheme: dark) {
+      html:not([data-theme]) {
+        ${declarations("dark")}
+      }
+    }
+
+    html[data-theme="dark"] {
+      ${declarations("dark")}
+    }
+  `;
+}
+// On web, semantic theme colors resolve to CSS custom properties so the
+// build-time exported HTML is theme-agnostic: the first frame paints in the
+// visitor's scheme purely from CSS, before any JS runs. Native keeps literal
+// values (no CSS engine). The `navigation` maps stay literal on both
+// platforms: @react-navigation internals color-parse their theme values.
+const webVarColors = Object.fromEntries(themeColorTokens.map((token) => [token, `var(${cssVarName(token)})`]));
+export const colors = Platform.OS === "web"
+    ? {
+        light: { ...lightTheme, colors: { ...webVarColors } },
+        dark: { ...darkTheme, colors: { ...webVarColors } },
+    }
+    : {
+        light: lightTheme,
+        dark: darkTheme,
+    };
 // Export palette for rare one-off cases
 export { palette };

package/dist/hooks/useDimensions.d.ts

@@ -29,11 +29,13 @@ type WindowDimensions = {
 * Provides a consistent way to access window dimensions and screen size
 * information across mobile and web.
 *
-* On web the first render uses `DEFAULT_VIEWPORT_WIDTH` / `_HEIGHT` — the
-* window can't be read while the HTML shell is rendered in Node at export
-* time, and reading it during the browser's first render would disagree with
-* that markup. A post-mount effect swaps in the real viewport and follows
-* resize from there.
+* On web the first render can't read the window: server-side there is no DOM,
+* and reading it during the browser's first render would disagree with the
+* markup it hydrates. The width comes from `SsrViewportContext` when the host
+* provides a per-request value (server render + first client render must
+* provide the same one), falling back to `DEFAULT_VIEWPORT_WIDTH` / `_HEIGHT`.
+* A post-mount effect swaps in the real viewport and follows resize from
+* there.
 */
 export declare const useDimensions: () => WindowDimensions;
 export {};

package/dist/hooks/useDimensions.js

@@ -1,5 +1,6 @@
-import { useEffect, useState } from "react";
+import { use, useEffect, useState } from "react";
 import { Platform, useWindowDimensions } from "react-native";
+import { SsrViewportContext } from "../state/SsrViewportContext.js";
 /**
  * Viewport the first web render is computed from, before the real window can
  * be read. Desktop is chosen because:
@@ -33,24 +34,41 @@ const calculateDimensionFlags = (width, height) => {
         isLargeScreen: width > SCREEN_SIZES.MEDIUM,
     };
 };
+// Persist the real viewport width as a cookie on first mount so subsequent
+// SSR requests can render at the user's actual layout (no reflow on repeat
+// visits). The server reads this cookie via resolveSsrViewportWidth in
+// server/lib/ssrViewport.ts.
+const SSR_VIEWPORT_COOKIE = "mrmeg-vw";
+const SSR_VIEWPORT_COOKIE_MAX_AGE = 60 * 60 * 24 * 365; // 1 year
+function writeViewportCookie(width) {
+    if (typeof document === "undefined")
+        return;
+    // Round to nearest 10 so resize-driven writes don't bust HTTP caching on
+    // every pixel of horizontal movement.
+    const rounded = Math.round(width / 10) * 10;
+    document.cookie = `${SSR_VIEWPORT_COOKIE}=${rounded}; path=/; max-age=${SSR_VIEWPORT_COOKIE_MAX_AGE}; SameSite=Lax`;
+}
 /**
 * Provides a consistent way to access window dimensions and screen size
 * information across mobile and web.
 *
-* On web the first render uses `DEFAULT_VIEWPORT_WIDTH` / `_HEIGHT` — the
-* window can't be read while the HTML shell is rendered in Node at export
-* time, and reading it during the browser's first render would disagree with
-* that markup. A post-mount effect swaps in the real viewport and follows
-* resize from there.
+* On web the first render can't read the window: server-side there is no DOM,
+* and reading it during the browser's first render would disagree with the
+* markup it hydrates. The width comes from `SsrViewportContext` when the host
+* provides a per-request value (server render + first client render must
+* provide the same one), falling back to `DEFAULT_VIEWPORT_WIDTH` / `_HEIGHT`.
+* A post-mount effect swaps in the real viewport and follows resize from
+* there.
 */
 export const useDimensions = () => {
     const isWeb = Platform.OS === "web";
+    const ssrWidth = use(SsrViewportContext);
     // Native reads come from useWindowDimensions, which subscribes to rotation /
     // split-screen / resize and tears the listener down for us — no manual
     // Dimensions.addEventListener to leak. On web we ignore it and drive layout
-    // from the default frame + the resize listener below.
+    // from the seeded frame + the resize listener below.
     const native = useWindowDimensions();
-    const [dimensions, setDimensions] = useState(() => calculateDimensionFlags(DEFAULT_VIEWPORT_WIDTH, DEFAULT_VIEWPORT_HEIGHT));
+    const [dimensions, setDimensions] = useState(() => calculateDimensionFlags(ssrWidth ?? DEFAULT_VIEWPORT_WIDTH, DEFAULT_VIEWPORT_HEIGHT));
     // Web: read the real viewport after mount and follow resize events. Keeping
     // this in an effect (not render) keeps the first render identical to the
     // exported markup it hydrates.
@@ -59,6 +77,7 @@ export const useDimensions = () => {
             return;
         const syncFromWindow = () => {
             setDimensions(calculateDimensionFlags(window.innerWidth, window.innerHeight));
+            writeViewportCookie(window.innerWidth);
         };
         syncFromWindow();
         window.addEventListener("resize", syncFromWindow);

package/dist/hooks/useResources.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Registers the Feather icon font in expo-font's server store during
+ * export-time rendering (`expo export` renders every route's HTML shell in
+ * Node, where the module-scope client load above is guarded off).
+ *
+ * Must be called from a **render body** (see `useResources` below): expo-font
+ * scopes its server store per render context, so a module-scope registration
+ * lands in at most one route's shell. Registering during render means every
+ * exported shell emits the `@font-face` rule and renders `<Icon>` glyphs —
+ * without it the shell contains an EMPTY icon text node while the client's
+ * first render (font pre-loaded above) contains the glyph, and React throws
+ * hydration error #418 on every cold load and regenerates the tree.
+ *
+ * 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

@@ -15,6 +15,32 @@ import { useThemeStore } from "../state/themeStore.js";
 if (typeof window !== "undefined") {
     void Font.loadAsync(Feather.font);
 }
+/**
+ * Registers the Feather icon font in expo-font's server store during
+ * export-time rendering (`expo export` renders every route's HTML shell in
+ * Node, where the module-scope client load above is guarded off).
+ *
+ * Must be called from a **render body** (see `useResources` below): expo-font
+ * scopes its server store per render context, so a module-scope registration
+ * lands in at most one route's shell. Registering during render means every
+ * exported shell emits the `@font-face` rule and renders `<Icon>` glyphs —
+ * without it the shell contains an EMPTY icon text node while the client's
+ * first render (font pre-loaded above) contains the glyph, and React throws
+ * hydration error #418 on every cold load and regenerates the tree.
+ *
+ * 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;
+    // Synchronous on server-web (expo-font routes to registerStaticFont). No
+    // `void`/try-catch: a throw here means we're outside a render 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
@@ -68,6 +94,9 @@ function ensureWebFontStylesheet() {
  * un-download Inter. The Feather icon font always loads.
  */
 export const useResources = () => {
+    // Export-time renders need the icon font registered per render scope; the
+    // module-scope call only reaches the client. See ensureIconFontRegistered.
+    ensureIconFontRegistered();
     const [loaded, setLoaded] = useState(false);
     const [error, setError] = useState(null);
     useEffect(() => {

package/dist/hooks/useTheme.d.ts

@@ -39,6 +39,24 @@ export declare function useTheme(): ExtendedColorScheme & {
     setTheme: (theme: "system" | "light" | "dark") => void;
     currentTheme: "system" | "light" | "dark";
 };
+/**
+ * Generates an alpha-modified version of a color
+ * @param color - The color to modify (hex, rgba, or a `var(--c-*)` theme color)
+ * @param alpha - Alpha value between 0 and 1 (replaces any existing alpha)
+ * @returns rgba color string with the specified alpha
+ *
+ * On web, theme colors are `var(--c-*)` references. Those rewrite onto the
+ * companion `--c-*-rgb` triplet variable (see `getThemeCssVariables`), so the
+ * result is pure CSS that re-themes with the variable — usable from
+ * module-scope style factories, which run once for both schemes.
+ *
+ * The result is wrapped in `var(--c-unset, …)` — a custom property that is
+ * never defined, so browsers always use the fallback. react-native-web's
+ * style compiler only passes a color value through verbatim when it starts
+ * with `var(`; a bare `rgba(var(…))` fails its color parser and the
+ * declaration is silently dropped.
+ */
+export declare function withAlpha(color: string, alpha: number): string;
 /**
  * Style factory context passed to the createStyles callback
  */

package/dist/hooks/useTheme.js

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useMemo } from "react";
-import { colors } from "../constants/colors.js";
+import { colors, resolveRawColor } from "../constants/colors.js";
 import { Platform, StyleSheet } from "react-native";
 import { resolveThemePreference, useThemeStore } from "../state/themeStore.js";
 import { useThemeColorScope } from "../state/themeColorScope.js";
@@ -170,10 +170,12 @@ export function useTheme() {
             boxShadow: `0 0 0 ${offset}px ${theme.colors.background}, 0 0 0 ${offset + 2}px ${theme.colors.ring}`,
         };
     }, [theme.colors.background, theme.colors.ring]);
-    // Helper to calculate contrast ratio between two colors
+    // Helper to calculate contrast ratio between two colors.
+    // On web theme colors are `var(--c-*)` strings, which cannot be parsed —
+    // resolve them to the active scheme's literal value first.
     const getContrastRatio = useCallback((color1, color2) => {
-        const rgb1 = parseColor(color1);
-        const rgb2 = parseColor(color2);
+        const rgb1 = parseColor(resolveRawColor(color1, effectiveScheme));
+        const rgb2 = parseColor(resolveRawColor(color2, effectiveScheme));
         if (!rgb1 || !rgb2) {
             console.error("Invalid colors for contrast ratio:", color1, color2);
             return 1; // Default to minimum contrast
@@ -181,13 +183,25 @@ export function useTheme() {
         const lum1 = calculateLuminance(rgb1[0], rgb1[1], rgb1[2]);
         const lum2 = calculateLuminance(rgb2[0], rgb2[1], rgb2[2]);
         return calculateContrastRatio(lum1, lum2);
-    }, []);
+    }, [effectiveScheme]);
     // Cached version of getContrastingColor for performance
-    // Uses module-level cache to prevent memory leak
+    // Uses module-level cache to prevent memory leak. `var(--c-*)` inputs are
+    // resolved per scheme BEFORE the cache so keys stay scheme-specific, and
+    // the winning candidate is returned as originally passed (a `var()` input
+    // stays a `var()` output, so the picked color keeps re-theming via CSS).
     const getCachedContrastingColor = useCallback((backgroundColor, color1, color2) => {
-        const cacheKey = `${backgroundColor}-${color1}-${color2}`;
-        return getCachedOrCompute(cacheKey, () => getBetterContrast(backgroundColor, color1, color2));
-    }, []);
+        const bg = resolveRawColor(backgroundColor, effectiveScheme);
+        const c1 = color1 === undefined ? undefined : resolveRawColor(color1, effectiveScheme);
+        const c2 = color2 === undefined ? undefined : resolveRawColor(color2, effectiveScheme);
+        const cacheKey = `${bg}-${c1}-${c2}`;
+        const winner = getCachedOrCompute(cacheKey, () => getBetterContrast(bg, c1, c2));
+        if (color1 !== undefined && winner === c1)
+            return color1;
+        if (color2 !== undefined && winner === c2)
+            return color2;
+        return winner;
+    }, [effectiveScheme]);
+    const getResolvedTextColorForBackground = useCallback((backgroundColor) => getTextColorForBackground(resolveRawColor(backgroundColor, effectiveScheme)), [effectiveScheme]);
     return useMemo(() => ({
         theme,
         scheme: theme.dark ? "dark" : "light",
@@ -197,13 +211,14 @@ export function useTheme() {
         setTheme,
         currentTheme: userTheme,
         getContrastingColor: getCachedContrastingColor,
-        getTextColorForBackground,
+        getTextColorForBackground: getResolvedTextColorForBackground,
         withAlpha,
         getContrastRatio,
     }), [
         getCachedContrastingColor,
         getContrastRatio,
         getFocusRingStyle,
+        getResolvedTextColorForBackground,
         getShadowStyle,
         setTheme,
         theme,
@@ -326,11 +341,26 @@ function getTextColorForBackground(backgroundColor) {
 }
 /**
  * Generates an alpha-modified version of a color
- * @param color - The color to modify (hex or rgba)
- * @param alpha - Alpha value between 0 and 1
+ * @param color - The color to modify (hex, rgba, or a `var(--c-*)` theme color)
+ * @param alpha - Alpha value between 0 and 1 (replaces any existing alpha)
  * @returns rgba color string with the specified alpha
+ *
+ * On web, theme colors are `var(--c-*)` references. Those rewrite onto the
+ * companion `--c-*-rgb` triplet variable (see `getThemeCssVariables`), so the
+ * result is pure CSS that re-themes with the variable — usable from
+ * module-scope style factories, which run once for both schemes.
+ *
+ * The result is wrapped in `var(--c-unset, …)` — a custom property that is
+ * never defined, so browsers always use the fallback. react-native-web's
+ * style compiler only passes a color value through verbatim when it starts
+ * with `var(`; a bare `rgba(var(…))` fails its color parser and the
+ * declaration is silently dropped.
  */
-function withAlpha(color, alpha) {
+export function withAlpha(color, alpha) {
+    const varMatch = /^var\((--c-[a-z0-9-]+)\)$/.exec(color);
+    if (varMatch) {
+        return `var(--c-unset, rgba(var(${varMatch[1]}-rgb), ${alpha}))`;
+    }
     const rgb = parseColor(color);
     if (!rgb) {
         console.error("Invalid color for alpha:", color);

package/dist/state/SsrViewportContext.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Per-request SSR viewport width. Consumed by `useDimensions` to seed the
+ * server render and the browser's FIRST render, so a server that detected a
+ * phone lays the tree out at phone width and hydration matches byte-for-byte.
+ *
+ * `null` (the default, when no provider is mounted) means "no per-request
+ * signal" and `useDimensions` falls back to `DEFAULT_VIEWPORT_WIDTH`. The
+ * host app is expected to provide the same value on the server and on the
+ * client's first render — both derived from signals both sides can read
+ * (cookie / User-Agent), never from `window`.
+ */
+export declare const SsrViewportContext: import("react").Context<number | null>;

package/dist/state/SsrViewportContext.js

@@ -0,0 +1,13 @@
+import { createContext } from "react";
+/**
+ * Per-request SSR viewport width. Consumed by `useDimensions` to seed the
+ * server render and the browser's FIRST render, so a server that detected a
+ * phone lays the tree out at phone width and hydration matches byte-for-byte.
+ *
+ * `null` (the default, when no provider is mounted) means "no per-request
+ * signal" and `useDimensions` falls back to `DEFAULT_VIEWPORT_WIDTH`. The
+ * host app is expected to provide the same value on the server and on the
+ * client's first render — both derived from signals both sides can read
+ * (cookie / User-Agent), never from `window`.
+ */
+export const SsrViewportContext = createContext(null);

package/dist/state/index.d.ts

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

package/dist/state/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrmeg/expo-ui",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [
@@ -125,7 +125,7 @@
     "zustand": ">=5.0.0 <6.0.0"
   },
   "devDependencies": {
-    "@types/react": "~19.2.17",
+    "@types/react": "~19.2.18",
     "typescript": "~6.0.3"
   }
 }