@mrmeg/expo-ui 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -3,6 +3,89 @@
 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.23.0]
+
+### Added
+
+- **Density tokens.** `spacing` gains `smd` (12) and `mdl` (20) scale steps plus
+  semantic layout tokens: `screenPadding`, `sectionSpacing` (now 24),
+  `cardPadding`, `dialogPadding`, `rowPaddingY`/`rowPaddingX`, `rowGap`,
+  `rowMinHeight`, and `formRowMinHeight`. Components read these so a single
+  retune shifts the whole library's density.
+
+### Changed
+
+- **Compact surfaces and rows.** `Card` header/content/footer padding drops
+  from 24 to 16 with a 16px title. `Item` rows use 10/16 padding and a 12px
+  gap, with a 40px visual min height on web while native keeps the 44pt touch
+  target. `Checkbox` and `RadioGroup` rows are 32px on web (native unchanged).
+  `Dialog`/`AlertDialog` padding is 20, `StatCard` padding is 16,
+  `EmptyState` vertical padding is 32, and `Accordion` triggers use 12px
+  vertical padding.
+- **Dialog spacing is symmetric.** `DialogContent` and `AlertDialogContent`
+  space their children with a 16px gap instead of fixed header/footer
+  margins, so a header-only dialog no longer reads bottom-heavy.
+
+### Fixed
+
+- **Dialog could not be dismissed on web.** The web overlay primitive wrapped
+  the backdrop in a react-native-web `Pressable` whose click handler stopped
+  propagation, so outside presses (mouse and touch) and Escape never reached
+  Radix. `DialogContent` now renders the overlay `asChild` on web; native is
+  unchanged.
+
+## [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/LLM_USAGE.md

@@ -157,11 +157,18 @@ semantic colors without destructuring `withAlpha` outside the factory:
 const { styles } = useStyles(({ theme, spacing, withAlpha }) => ({
   card: {
     backgroundColor: withAlpha(theme.colors.primary, 0.08),
-    padding: spacing.md,
+    padding: spacing.cardPadding,
   },
 }));
 ```
 
+Layout spacing uses semantic density tokens rather than raw scale steps:
+`spacing.screenPadding` (16) for screen and block gutters, `spacing.cardPadding`
+(16) for bordered panels, `spacing.sectionSpacing` (24) between grouped lists,
+`spacing.dialogPadding` (20) for dialogs, and `spacing.rowPaddingY`/`rowPaddingX`
+(10/16) with `spacing.rowGap` (12) for list rows. `Item` already applies the row
+tokens and keeps a 44px hit area on native while rendering 40px on web.
+
 When the saved theme preference is `system`, the package theme store owns the
 OS color-scheme subscription, including web `prefers-color-scheme`. Do not add
 app-local Appearance or `matchMedia` listeners for package components; import

package/README.md

@@ -124,6 +124,24 @@ const { styles } = useStyles(({ theme, spacing, withAlpha }) => ({
 }));
 ```
 
+### Spacing and density
+
+`spacing` exposes an 8px base scale (`xxs` 2, `xs` 4, `sm` 8, `smd` 12, `md` 16, `mdl` 20, `lg` 24, `xl` 32, `xxl` 48, `xxxl` 64) plus semantic density tokens that package components read from. Reach for the semantic names in app code so a future density tune lands everywhere at once:
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `screenPadding` | 16 | Horizontal gutter for screens, scroll content, and landing blocks |
+| `sectionSpacing` | 24 | Gap between grouped lists, cards, or settings groups |
+| `cardPadding` | 16 | `Card`, `StatCard`, and any bordered panel |
+| `dialogPadding` | 20 | `Dialog` and `AlertDialog` content |
+| `rowPaddingY` / `rowPaddingX` | 10 / 16 | `Item` rows and hand-rolled list rows |
+| `rowGap` | 12 | Gap between row media, content, and actions |
+| `rowMinHeight` | 40 | Visual row height on web; native rows keep `touchTarget` |
+| `formRowMinHeight` | 32 | Checkbox and radio rows on web; native keeps `touchTarget` |
+| `touchTarget` | 44 | Minimum native hit area; pair a smaller visual height with `hitSlop` |
+
+Controls (`Button`, `TextInput`, `Select`, `Tabs`, `Toggle`) size themselves from their own `size` prop (28/32/36/40) and do not read these tokens.
+
 ### Color overrides
 
 The package ships a neutral default palette. `useTheme()` resolves colors in

package/dist/components/Accordion.js

@@ -132,7 +132,7 @@ function AccordionTrigger({ children, style: styleOverride, disabled, ...props }
                                     justifyContent: "space-between",
                                     gap: spacing.md,
                                     borderRadius: spacing.radiusMd,
-                                    paddingVertical: spacing.md,
+                                    paddingVertical: spacing.smd,
                                     ...(Platform.OS === "web" && {
                                         cursor: "pointer",
                                         userSelect: "none",

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/Card.js

@@ -98,24 +98,24 @@ const createCardStyles = (theme) => StyleSheet.create({
         backgroundColor: "transparent",
     },
     header: {
-        padding: spacing.lg,
+        padding: spacing.cardPadding,
         paddingBottom: spacing.xs,
         gap: spacing.xs,
     },
     content: {
-        paddingHorizontal: spacing.lg,
-        paddingBottom: spacing.lg,
+        paddingHorizontal: spacing.cardPadding,
+        paddingBottom: spacing.cardPadding,
     },
     footer: {
         flexDirection: "row",
         alignItems: "center",
-        paddingHorizontal: spacing.lg,
-        paddingBottom: spacing.lg,
+        paddingHorizontal: spacing.cardPadding,
+        paddingBottom: spacing.cardPadding,
         paddingTop: 0,
     },
     title: {
-        fontSize: 18,
-        lineHeight: 24,
+        fontSize: 16,
+        lineHeight: 22,
         letterSpacing: 0,
     },
     description: {

package/dist/components/Checkbox.js

@@ -117,7 +117,7 @@ const styles = StyleSheet.create({
         flexDirection: "row",
         alignItems: "center",
         gap: spacing.sm,
-        minHeight: spacing.touchTarget,
+        minHeight: Platform.select({ web: spacing.formRowMinHeight, default: spacing.touchTarget }),
     },
     labelContainer: {
         flex: 1,

package/dist/components/Dialog.js

@@ -22,7 +22,25 @@ function DialogRoot({ children, ...props }) {
 function DialogContent({ portalHost, style, children, ...props }) {
     const { theme, getShadowStyle, getContrastingColor } = useTheme();
     const textColor = getContrastingColor(theme.colors.popover, palette.white, palette.black);
-    return (_jsx(DialogPrimitive.Portal, { hostName: portalHost, children: _jsx(FullWindowOverlay, { children: _jsx(DialogPrimitive.Overlay, { style: StyleSheet.flatten([
+    return (_jsx(DialogPrimitive.Portal, { hostName: portalHost, children: _jsx(FullWindowOverlay, { children: _jsx(DialogPrimitive.Overlay
+            // On web the primitive wraps the overlay in a react-native-web
+            // Pressable whose click handler stops propagation unconditionally.
+            // With that Pressable between the overlay and the Radix content,
+            // outside presses (mouse and touch) and Escape never dismissed the
+            // dialog, so a dialog without a Close button was stuck. `asChild`
+            // makes the primitive clone our fade wrapper instead, removing the
+            // Pressable; Radix dismissal then works. Native keeps the Pressable,
+            // which is what implements closeOnPress there.
+            , { 
+                // On web the primitive wraps the overlay in a react-native-web
+                // Pressable whose click handler stops propagation unconditionally.
+                // With that Pressable between the overlay and the Radix content,
+                // outside presses (mouse and touch) and Escape never dismissed the
+                // dialog, so a dialog without a Close button was stuck. `asChild`
+                // makes the primitive clone our fade wrapper instead, removing the
+                // Pressable; Radix dismissal then works. Native keeps the Pressable,
+                // which is what implements closeOnPress there.
+                asChild: Platform.OS === "web", style: StyleSheet.flatten([
                     StyleSheet.absoluteFill,
                     { backgroundColor: theme.colors.overlay },
                     Platform.OS === "web" && { zIndex: 50 },
@@ -32,7 +50,8 @@ function DialogContent({ portalHost, style, children, ...props }) {
                                                 borderColor: theme.colors.border,
                                                 borderWidth: 1,
                                                 borderRadius: spacing.radiusLg,
-                                                padding: spacing.lg,
+                                                padding: spacing.dialogPadding,
+                                                gap: spacing.md,
                                                 width: "100%",
                                                 ...getShadowStyle("soft"),
                                             },
@@ -40,7 +59,7 @@ function DialogContent({ portalHost, style, children, ...props }) {
                                         ]), ...props, children: children }) }) }) }) }) }) }) }) }));
 }
 function DialogHeader({ children, style, ...props }) {
-    return (_jsx(View, { style: StyleSheet.flatten([{ gap: spacing.xs, marginBottom: spacing.md }, style]), ...props, children: children }));
+    return (_jsx(View, { style: StyleSheet.flatten([{ gap: spacing.xs }, style]), ...props, children: children }));
 }
 function DialogFooter({ children, style, ...props }) {
     return (_jsx(View, { style: StyleSheet.flatten([
@@ -48,7 +67,6 @@ function DialogFooter({ children, style, ...props }) {
                 flexDirection: "row",
                 justifyContent: "flex-end",
                 gap: spacing.sm,
-                marginTop: spacing.lg,
             },
             style,
         ]), ...props, children: children }));
@@ -107,7 +125,8 @@ function AlertDialogContent({ portalHost, style, children, ...props }) {
                                                 borderColor: theme.colors.border,
                                                 borderWidth: 1,
                                                 borderRadius: spacing.radiusLg,
-                                                padding: spacing.lg,
+                                                padding: spacing.dialogPadding,
+                                                gap: spacing.md,
                                                 width: "100%",
                                                 ...getShadowStyle("soft"),
                                             },

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/EmptyState.js

@@ -33,7 +33,7 @@ const createStyles = (theme) => StyleSheet.create({
     container: {
         alignItems: "center",
         justifyContent: "center",
-        paddingVertical: spacing.xxl,
+        paddingVertical: spacing.xl,
         paddingHorizontal: spacing.lg,
     },
     bordered: {
@@ -41,7 +41,7 @@ const createStyles = (theme) => StyleSheet.create({
         borderStyle: "dashed",
         borderColor: theme.colors.border,
         borderRadius: spacing.radiusLg,
-        padding: spacing.xl,
+        padding: spacing.lg,
     },
     iconWrapper: {
         width: MEDIA_SIZE,

package/dist/components/Item.d.ts

@@ -16,8 +16,9 @@ export interface ItemProps {
 /**
  * Item
  *
- * Grouped-list row container: `spacing.md` padding and gap, a comfortable
- * 44pt min height, and an optional pressable scale interaction. Compose
+ * Grouped-list row container: compact row padding (`spacing.rowPaddingY` /
+ * `spacing.rowPaddingX`) and gap, a 44pt min height on native (40 on web),
+ * and an optional pressable scale interaction. Compose
  * with `ItemMedia`, `ItemContent` (+ `ItemTitle`/`ItemDescription`), and
  * `ItemActions`.
  *

package/dist/components/Item.js

@@ -8,12 +8,13 @@ import { spacing } from "../constants/spacing.js";
 // Default ItemMedia footprint (see ItemMedia's `size` prop) — used to inset
 // the optional separator past the media slot without needing a context.
 const DEFAULT_MEDIA_SIZE = 40;
-const SEPARATOR_INSET = spacing.md + DEFAULT_MEDIA_SIZE + spacing.md;
+const SEPARATOR_INSET = spacing.rowPaddingX + DEFAULT_MEDIA_SIZE + spacing.rowGap;
 /**
  * Item
  *
- * Grouped-list row container: `spacing.md` padding and gap, a comfortable
- * 44pt min height, and an optional pressable scale interaction. Compose
+ * Grouped-list row container: compact row padding (`spacing.rowPaddingY` /
+ * `spacing.rowPaddingX`) and gap, a 44pt min height on native (40 on web),
+ * and an optional pressable scale interaction. Compose
  * with `ItemMedia`, `ItemContent` (+ `ItemTitle`/`ItemDescription`), and
  * `ItemActions`.
  *
@@ -104,9 +105,10 @@ const styles = StyleSheet.create({
     row: {
         flexDirection: "row",
         alignItems: "center",
-        minHeight: spacing.touchTarget,
-        padding: spacing.md,
-        gap: spacing.md,
+        minHeight: Platform.select({ web: spacing.rowMinHeight, default: spacing.touchTarget }),
+        paddingVertical: spacing.rowPaddingY,
+        paddingHorizontal: spacing.rowPaddingX,
+        gap: spacing.rowGap,
     },
     content: {
         flex: 1,

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/RadioGroup.js

@@ -151,7 +151,7 @@ const styles = StyleSheet.create({
         flexDirection: "row",
         alignItems: "center",
         gap: spacing.sm,
-        minHeight: spacing.touchTarget,
+        minHeight: Platform.select({ web: spacing.formRowMinHeight, default: spacing.touchTarget }),
     },
     labelContainer: {
         flex: 1,

package/dist/components/StatCard.js

@@ -37,5 +37,5 @@ export function StatCard({ label, value, unit, change, icon, onPress, style }) {
             : change.direction === "down"
                 ? theme.colors.destructive
                 : theme.colors.textDim;
-    return (_jsx(Card, { onPress: onPress, style: style, children: _jsxs(View, { style: { padding: spacing.lg, gap: spacing.xs }, children: [_jsxs(View, { style: { flexDirection: "row", alignItems: "center", justifyContent: "space-between" }, children: [_jsx(CaptionText, { selectable: false, style: { color: theme.colors.textDim, textTransform: "uppercase", letterSpacing: 0.96 }, children: label }), !!icon && _jsx(Icon, { name: icon, size: spacing.iconSm, color: theme.colors.mutedForeground, decorative: true })] }), _jsxs(View, { style: { flexDirection: "row", alignItems: "flex-end" }, children: [_jsx(StyledText, { selectable: false, size: "xxl", fontWeight: "bold", style: { color: theme.colors.foreground, fontVariant: ["tabular-nums"] }, children: value }), !!unit && (_jsx(StyledText, { selectable: false, size: "base", style: { color: theme.colors.textDim, marginLeft: spacing.xxs, marginBottom: 2 }, children: unit }))] }), !!change && (_jsxs(View, { style: { flexDirection: "row", alignItems: "center", gap: spacing.xxs }, children: [change.direction !== "neutral" && (_jsx(Icon, { name: DIRECTION_ICON[change.direction], size: spacing.iconXs, color: changeColor, decorative: true })), _jsx(StyledText, { selectable: false, size: "sm", style: { color: changeColor }, children: change.value })] }))] }) }));
+    return (_jsx(Card, { onPress: onPress, style: style, children: _jsxs(View, { style: { padding: spacing.cardPadding, gap: spacing.xs }, children: [_jsxs(View, { style: { flexDirection: "row", alignItems: "center", justifyContent: "space-between" }, children: [_jsx(CaptionText, { selectable: false, style: { color: theme.colors.textDim, textTransform: "uppercase", letterSpacing: 0.96 }, children: label }), !!icon && _jsx(Icon, { name: icon, size: spacing.iconSm, color: theme.colors.mutedForeground, decorative: true })] }), _jsxs(View, { style: { flexDirection: "row", alignItems: "flex-end" }, children: [_jsx(StyledText, { selectable: false, size: "xxl", fontWeight: "bold", style: { color: theme.colors.foreground, fontVariant: ["tabular-nums"] }, children: value }), !!unit && (_jsx(StyledText, { selectable: false, size: "base", style: { color: theme.colors.textDim, marginLeft: spacing.xxs, marginBottom: 2 }, children: unit }))] }), !!change && (_jsxs(View, { style: { flexDirection: "row", alignItems: "center", gap: spacing.xxs }, children: [change.direction !== "neutral" && (_jsx(Icon, { name: DIRECTION_ICON[change.direction], size: spacing.iconXs, color: changeColor, decorative: true })), _jsx(StyledText, { selectable: false, size: "sm", style: { color: changeColor }, children: change.value })] }))] }) }));
 }

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/constants/spacing.d.ts

@@ -1,15 +1,19 @@
 /**
  * Spacing Constants
  *
- * A consistent spacing scale based on an 8px base unit.
- * Use these constants throughout the app for consistent spacing.
+ * A consistent spacing scale based on an 8px base unit, plus a small set of
+ * density tokens that components reach for when composing rows, surfaces, and
+ * screens. Tune the density tokens to shift the whole library's feel without
+ * touching the base scale.
  */
 export declare const spacing: {
     readonly base: 8;
     readonly xxs: 2;
     readonly xs: 4;
     readonly sm: 8;
+    readonly smd: 12;
     readonly md: 16;
+    readonly mdl: 20;
     readonly lg: 24;
     readonly xl: 32;
     readonly xxl: 48;
@@ -17,12 +21,18 @@ export declare const spacing: {
     readonly gutter: 16;
     readonly gutterVertical: 24;
     readonly screenPadding: 16;
+    readonly sectionSpacing: 24;
+    readonly rowPaddingY: 10;
+    readonly rowPaddingX: 16;
+    readonly rowGap: 12;
+    readonly rowMinHeight: 40;
+    readonly formRowMinHeight: 32;
+    readonly cardPadding: 16;
+    readonly dialogPadding: 20;
+    readonly touchTarget: 44;
     readonly buttonPadding: 10;
     readonly inputPadding: 10;
-    readonly cardPadding: 16;
-    readonly sectionSpacing: 32;
     readonly listItemSpacing: 8;
-    readonly touchTarget: 44;
     readonly radiusNone: 0;
     readonly radiusXs: 4;
     readonly radiusSm: 8;
@@ -37,5 +47,5 @@ export declare const spacing: {
     readonly iconLg: 32;
     readonly iconXl: 48;
 };
-export declare const base: 8, xxs: 2, xs: 4, sm: 8, md: 16, lg: 24, xl: 32, xxl: 48, xxxl: 64, gutter: 16, gutterVertical: 24, screenPadding: 16, buttonPadding: 10, inputPadding: 10, cardPadding: 16, sectionSpacing: 32, listItemSpacing: 8, touchTarget: 44, radiusNone: 0, radiusXs: 4, radiusSm: 8, radiusMd: 12, radiusLg: 14, radiusXl: 18, radius2xl: 24, radiusFull: 9999, iconXs: 12, iconSm: 16, iconMd: 24, iconLg: 32, iconXl: 48;
+export declare const base: 8, xxs: 2, xs: 4, sm: 8, smd: 12, md: 16, mdl: 20, lg: 24, xl: 32, xxl: 48, xxxl: 64, gutter: 16, gutterVertical: 24, screenPadding: 16, sectionSpacing: 24, rowPaddingY: 10, rowPaddingX: 16, rowGap: 12, rowMinHeight: 40, formRowMinHeight: 32, cardPadding: 16, dialogPadding: 20, touchTarget: 44, buttonPadding: 10, inputPadding: 10, listItemSpacing: 8, radiusNone: 0, radiusXs: 4, radiusSm: 8, radiusMd: 12, radiusLg: 14, radiusXl: 18, radius2xl: 24, radiusFull: 9999, iconXs: 12, iconSm: 16, iconMd: 24, iconLg: 32, iconXl: 48;
 export declare const space: (multiplier: number) => number;

package/dist/constants/spacing.js

@@ -1,8 +1,10 @@
 /**
  * Spacing Constants
  *
- * A consistent spacing scale based on an 8px base unit.
- * Use these constants throughout the app for consistent spacing.
+ * A consistent spacing scale based on an 8px base unit, plus a small set of
+ * density tokens that components reach for when composing rows, surfaces, and
+ * screens. Tune the density tokens to shift the whole library's feel without
+ * touching the base scale.
  */
 export const spacing = {
     // Base unit: 8px
@@ -11,7 +13,9 @@ export const spacing = {
     xxs: 2, // 2px  - Minimal spacing
     xs: 4, // 4px  - Extra small
     sm: 8, // 8px  - Small (1 unit)
+    smd: 12, // 12px - Between small and medium (1.5 units); compact gaps and row padding
     md: 16, // 16px - Medium (2 units)
+    mdl: 20, // 20px - Between medium and large (2.5 units); dialog and sheet padding
     lg: 24, // 24px - Large (3 units)
     xl: 32, // 32px - Extra large (4 units)
     xxl: 48, // 48px - 2x extra large (6 units)
@@ -20,13 +24,20 @@ export const spacing = {
     gutter: 16, // Standard horizontal gutter
     gutterVertical: 24, // Standard vertical spacing
     screenPadding: 16, // Default screen edge padding
+    sectionSpacing: 24, // Space between major sections / grouped lists
+    // Density tokens — rows, surfaces, overlays
+    rowPaddingY: 10, // Vertical padding for list / settings rows
+    rowPaddingX: 16, // Horizontal padding for list / settings rows
+    rowGap: 12, // Gap between media, content, and actions in a row
+    rowMinHeight: 40, // Visual min height for rows on pointer surfaces (web)
+    formRowMinHeight: 32, // Visual min height for checkbox / radio rows on web
+    cardPadding: 16, // Default card / stat card padding
+    dialogPadding: 20, // Default dialog / alert dialog padding
+    touchTarget: 44, // Minimum comfortable native touch target
     // Component-specific
     buttonPadding: 10, // Default button padding
     inputPadding: 10, // Default input padding
-    cardPadding: 16, // Default card padding
-    sectionSpacing: 32, // Space between major sections
     listItemSpacing: 8, // Space between list items
-    touchTarget: 44, // Minimum comfortable native touch target
     // Border radius — shadcn-inspired scale (radiusMd = 12px default)
     radiusNone: 0,
     radiusXs: 4,
@@ -44,6 +55,6 @@ export const spacing = {
     iconXl: 48,
 };
 // Export individual constants for convenience
-export const { base, xxs, xs, sm, md, lg, xl, xxl, xxxl, gutter, gutterVertical, screenPadding, buttonPadding, inputPadding, cardPadding, sectionSpacing, listItemSpacing, touchTarget, radiusNone, radiusXs, radiusSm, radiusMd, radiusLg, radiusXl, radius2xl, radiusFull, iconXs, iconSm, iconMd, iconLg, iconXl, } = spacing;
+export const { base, xxs, xs, sm, smd, md, mdl, lg, xl, xxl, xxxl, gutter, gutterVertical, screenPadding, sectionSpacing, rowPaddingY, rowPaddingX, rowGap, rowMinHeight, formRowMinHeight, cardPadding, dialogPadding, touchTarget, buttonPadding, inputPadding, listItemSpacing, radiusNone, radiusXs, radiusSm, radiusMd, radiusLg, radiusXl, radius2xl, radiusFull, iconXs, iconSm, iconMd, iconLg, iconXl, } = spacing;
 // Helper function to multiply base spacing
 export const space = (multiplier) => spacing.base * multiplier;

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.23.0",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [
@@ -83,7 +83,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "jest --config ../../jest.config.js packages/ui/src --runInBand --watchman=false && bun run check:forbidden-imports",
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/fix-ui-package-esm.mjs && bun run check:forbidden-imports",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/fix-package-esm.mjs ui && bun run check:forbidden-imports",
     "check:forbidden-imports": "node ../../scripts/check-ui-forbidden-imports.mjs",
     "publish:dry-run": "bun pm pack --dry-run"
   },
@@ -98,7 +98,7 @@
     "@rn-primitives/dropdown-menu": "~1.5.2",
     "@rn-primitives/label": "~1.5.2",
     "@rn-primitives/popover": "~1.5.2",
-    "@rn-primitives/portal": "~1.5.2",
+    "@rn-primitives/portal": "~1.5.3",
     "@rn-primitives/radio-group": "~1.5.2",
     "@rn-primitives/select": "~1.5.2",
     "@rn-primitives/separator": "~1.5.2",
@@ -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"
   }
 }