@mrmeg/expo-ui 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -3,6 +3,64 @@
 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.16.0]
+
+### Added
+
+- **`setFonts` — font injection, mirroring `setColors`.** A host app can now
+  forward its own bundled faces to the package:
+
+  ```ts
+  useThemeStore.getState().setFonts({
+    families: { sansSerif: { light: "…", regular: "…", medium: "…",
+                             semibold: "…", bold: "…" } },
+    webWeightStrategy: "family",
+  });
+  ```
+
+  Overrides are partial and per-group — pass `sansSerif` alone and `serif`
+  keeps the package default. `setFonts({})` clears back to the defaults.
+  `StyledText` subscribes to the store, so a call after mount re-renders
+  rather than leaving stale families on screen.
+
+- **`webWeightStrategy` — `"numeric" | "family"`.** Declares how a family map
+  expresses weight. `"numeric"` (the package default on web) assumes one
+  multi-weight CSS family where a numeric `fontWeight` selects the
+  `@font-face` variant. `"family"` means each weight is its own
+  separately-registered single-face family, so the family name alone carries
+  the weight and `StyledText` suppresses the numeric `fontWeight`. Native is
+  always `"family"`, unchanged.
+
+  Apps loading per-weight faces through `expo-font` need `"family"` on web:
+  `expo-font` registers each file as its own family there too, so the previous
+  always-numeric behaviour synthesised a second layer of bold on top of an
+  already-bold face.
+
+- Exported `FontFamilyMap`, `FontFamilyWeight`, `FontOverrides`,
+  `FontWeightStrategy`, and `defaultWebWeightStrategy` from `constants/fonts`.
+
+- **`createThemedStyles` — SSR-safe themed style registration**, exported from
+  `lib`. Wraps a `(theme: Theme) => styles` factory so both base themes are
+  registered with react-native-web at module scope — before expo-router
+  snapshots the server-side stylesheet — instead of lazily during render via
+  `useMemo`, which left SSR HTML referencing class names with no rules
+  (unstyled first paint until hydration). Override themes are cached per theme
+  object identity. The package's own components (Badge, Button, Card,
+  EmptyState, InputOTP, Label, Notification, Skeleton, TextInput) now use it.
+
+### Why
+
+`fontFamilies` was a module-level `const` with no injection point, so the only
+way for a consumer to use its own type was to patch `dist/` inside
+`node_modules`. Bun keys `patchedDependencies` on an exact `name@version`, so
+those patches stop applying — silently, with no warning — the moment the
+package version is bumped. Two consumer apps hit exactly that and shipped
+fallback fonts without noticing. Colors already had `setColors` for this
+reason; fonts now match.
+
+Fully backward compatible: with no `setFonts` call, font resolution is
+identical to 0.15.0.
+
 ## [0.15.0]
 
 ### Added

package/README.md

@@ -163,6 +163,50 @@ import { ThemeColorScope } from "@mrmeg/expo-ui/state";
 </ThemeColorScope>
 ```
 
+### Font overrides
+
+The package bundles Inter (sans) and Georgia (serif). Most apps ship their own
+faces — forward them with `setFonts`, the font counterpart to `setColors`.
+Call it once at startup, after your fonts are registered:
+
+```tsx
+import { useThemeStore } from "@mrmeg/expo-ui/state";
+
+useThemeStore.getState().setFonts({
+  families: {
+    sansSerif: {
+      light: "HankenGrotesk_300Light",
+      regular: "HankenGrotesk_400Regular",
+      medium: "HankenGrotesk_500Medium",
+      semibold: "HankenGrotesk_600SemiBold",
+      bold: "HankenGrotesk_700Bold",
+    },
+  },
+  webWeightStrategy: "family",
+});
+```
+
+Overrides are partial and per-group: pass `sansSerif` alone and `serif` keeps
+the package default. `setFonts({})` clears back to the defaults.
+
+**Pick the right `webWeightStrategy`** — this is the one non-obvious part:
+
+| Strategy | Use when | Effect |
+|---|---|---|
+| `"numeric"` (default) | You ship **one multi-weight CSS family** (a variable font, or Google Fonts' single `"Inter"` family) | A numeric `fontWeight` selects the `@font-face` variant |
+| `"family"` | You load **per-weight faces via `expo-font`** | The family name alone carries the weight; the numeric `fontWeight` is suppressed |
+
+If you load fonts through `expo-font` / `@expo-google-fonts`, choose
+`"family"`. `expo-font` registers each weight as its own single-face family on
+web as well as native, so emitting a numeric weight on top makes the browser
+synthesise a *second* layer of bold over an already-bold face.
+
+Native always behaves as `"family"` regardless of this setting.
+
+> Prefer `setFonts` over patching `node_modules`. Bun keys
+> `patchedDependencies` to an exact `name@version`, so a font patch silently
+> stops applying the next time you bump the package — with no warning.
+
 Use `StyledText` for theme-aware text:
 
 ```tsx

package/dist/components/Badge.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import React, { useMemo } from "react";
+import React from "react";
 import { View, StyleSheet } from "react-native";
 import { useTheme } from "../hooks/useTheme.js";
 import { spacing } from "../constants/spacing.js";
 import { StyledText } from "./StyledText.js";
+import { createThemedStyles } from "../lib/themedStyles.js";
 /**
  * Badge Component
  *
@@ -19,7 +20,7 @@ import { StyledText } from "./StyledText.js";
  */
 function Badge({ children, text, variant = "default", style: styleOverride }) {
     const { theme } = useTheme();
-    const styles = useMemo(() => createStyles(theme), [theme]);
+    const styles = themedStyles(theme);
     const badgeContent = text ?? children;
     const textStyle = [
         styles.text,
@@ -74,4 +75,5 @@ const createStyles = (theme) => StyleSheet.create({
         userSelect: "none",
     },
 });
+const themedStyles = createThemedStyles(createStyles);
 export { Badge };

package/dist/components/Button.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { use, useCallback, useMemo, useState } from "react";
+import { use, useCallback, useState } from "react";
 import { Pressable, StyleSheet, View, Platform, ActivityIndicator, Animated, } from "react-native";
 import { spacing } from "../constants/spacing.js";
 import { StyledText } from "./StyledText.js";
@@ -9,6 +9,7 @@ import { fontFamilies } from "../constants/fonts.js";
 import { palette } from "../constants/colors.js";
 import { useTheme } from "../hooks/useTheme.js";
 import { useScalePress } from "../hooks/useScalePress.js";
+import { createThemedStyles } from "../lib/themedStyles.js";
 const SIZE_CONFIGS = {
     sm: {
         paddingVertical: spacing.xxs,
@@ -72,7 +73,7 @@ const getNativeHitSlop = (sizeConfig) => Math.ceil(Math.max(0, spacing.touchTarg
 function ButtonRoot(props) {
     const { tx, text, txOptions, style: styleOverride, pressedStyle: pressedStyleOverride, textStyle: textStyleOverride, pressedTextStyle: pressedTextStyleOverride, disabledTextStyle: disabledTextStyleOverride, children, RightAccessory, LeftAccessory, disabled, disabledStyle: disabledStyleOverride, withShadow: withShadowProp, preset = "default", size = "md", loading = false, fullWidth = false, onFocus, onBlur, onPressIn, onPressOut, ...rest } = props;
     const { theme, getContrastingColor, getFocusRingStyle, getShadowStyle } = useTheme();
-    const styles = useMemo(() => createStyles(theme, size), [theme, size]);
+    const styles = themedStyles(theme)[size];
     const shadowStyle = getShadowStyle("subtle");
     const sizeConfig = SIZE_CONFIGS[size];
     // Filled (`default`) buttons float by default; ghost/outline/link stay flat
@@ -321,6 +322,11 @@ const createStyles = (theme, size) => {
         },
     });
 };
+const themedStyles = createThemedStyles((theme) => ({
+    sm: createStyles(theme, "sm"),
+    md: createStyles(theme, "md"),
+    lg: createStyles(theme, "lg"),
+}));
 /**
  * Button with explicit subcomponents.
  * - `Button.Text` for label text (inherits control typography)

package/dist/components/Card.js

@@ -5,6 +5,7 @@ import { StyledText } from "./StyledText.js";
 import { useTheme } from "../hooks/useTheme.js";
 import { useScalePress } from "../hooks/useScalePress.js";
 import { spacing } from "../constants/spacing.js";
+import { createThemedStyles } from "../lib/themedStyles.js";
 /**
  * Card Component
  *
@@ -30,15 +31,15 @@ import { spacing } from "../constants/spacing.js";
 const CardContext = createContext(null);
 function useCardContext() {
     const ctx = use(CardContext);
-    // useTheme must run unconditionally (Rules of Hooks); createCardStyles is a
+    // useTheme must run unconditionally (Rules of Hooks); themedStyles is a
     // plain function, so the `??` keeps the fallback styles lazy.
     const { theme } = useTheme();
     // Fallback for standalone usage without a Card parent.
-    return ctx ?? { theme, styles: createCardStyles(theme) };
+    return ctx ?? { theme, styles: themedStyles(theme) };
 }
 function Card({ children, style: styleOverride, variant = "default", onPress, disabled }) {
     const { theme, getShadowStyle } = useTheme();
-    const styles = createCardStyles(theme);
+    const styles = themedStyles(theme);
     const shadowStyle = getShadowStyle("subtle");
     const ctx = { theme, styles };
     const { animatedStyle: scaleStyle, pressHandlers } = useScalePress({
@@ -122,4 +123,5 @@ const createCardStyles = (theme) => StyleSheet.create({
         lineHeight: 20,
     },
 });
+const themedStyles = createThemedStyles(createCardStyles);
 export { Card, CardHeader, CardContent, CardFooter, CardTitle, CardDescription };

package/dist/components/EmptyState.js

@@ -1,11 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo } from "react";
 import { View, StyleSheet } from "react-native";
 import { SansSerifBoldText, SansSerifText } from "./StyledText.js";
 import { Button } from "./Button.js";
 import { Icon } from "./Icon.js";
 import { useTheme } from "../hooks/useTheme.js";
 import { spacing } from "../constants/spacing.js";
+import { createThemedStyles } from "../lib/themedStyles.js";
 /**
  * EmptyState Component
  *
@@ -25,7 +25,7 @@ import { spacing } from "../constants/spacing.js";
  */
 export function EmptyState({ icon, iconSize = spacing.iconMd, title, description, actionLabel, onAction, actionPreset = "default", style, children, bordered = false, }) {
     const { theme } = useTheme();
-    const styles = useMemo(() => createStyles(theme), [theme]);
+    const styles = themedStyles(theme);
     return (_jsxs(View, { style: [styles.container, bordered && styles.bordered, style], children: [!!icon && (_jsx(View, { style: styles.iconWrapper, children: _jsx(Icon, { name: icon, size: iconSize, color: theme.colors.mutedForeground }) })), _jsx(SansSerifBoldText, { selectable: false, size: "lg", style: styles.title, children: title }), !!description && (_jsx(SansSerifText, { selectable: false, size: "base", style: styles.description, children: description })), children, !!actionLabel && onAction && (_jsx(Button, { preset: actionPreset, onPress: onAction, text: actionLabel, style: styles.action }))] }));
 }
 const MEDIA_SIZE = 56;
@@ -74,3 +74,4 @@ const createStyles = (theme) => StyleSheet.create({
         alignSelf: "center",
     },
 });
+const themedStyles = createThemedStyles(createStyles);

package/dist/components/InputOTP.js

@@ -1,10 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo, useRef, useState, useCallback } from "react";
+import { useRef, useState, useCallback } from "react";
 import { View, TextInput as RNTextInput, Pressable, StyleSheet, Platform, } from "react-native";
 import { useTheme } from "../hooks/useTheme.js";
 import { spacing } from "../constants/spacing.js";
 import { fontFamilies } from "../constants/fonts.js";
 import { StyledText } from "./StyledText.js";
+import { createThemedStyles } from "../lib/themedStyles.js";
 const CELL_WIDTH = 36;
 const CELL_HEIGHT = 40;
 const CELL_FONT_SIZE = 20;
@@ -30,7 +31,7 @@ function InputOTP({ length = 6, value = "", onChangeText, onComplete, error = fa
     const { theme } = useTheme();
     const inputRef = useRef(null);
     const [focused, setFocused] = useState(false);
-    const styles = useMemo(() => createStyles(theme), [theme]);
+    const styles = themedStyles(theme);
     const hasError = error || !!errorText;
     // Active cell index: next empty cell, or last cell when full
     const activeIndex = Math.min(value.length, length - 1);
@@ -132,4 +133,5 @@ const createStyles = (theme) => StyleSheet.create({
         marginTop: spacing.xs,
     },
 });
+const themedStyles = createThemedStyles(createStyles);
 export { InputOTP };

package/dist/components/Label.js

@@ -1,11 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo } from "react";
 import { StyleSheet, Platform } from "react-native";
 import * as LabelPrimitive from "@rn-primitives/label";
 import { useTheme } from "../hooks/useTheme.js";
 import { spacing } from "../constants/spacing.js";
 import { fontFamilies } from "../constants/fonts.js";
 import { StyledText } from "./StyledText.js";
+import { createThemedStyles } from "../lib/themedStyles.js";
 const SIZE_CONFIGS = {
     sm: { fontSize: 12 },
     md: { fontSize: 14 },
@@ -37,7 +37,7 @@ const SIZE_CONFIGS = {
  */
 export function Label({ children, nativeID, required, size = "md", error, disabled, style, onPress, }) {
     const { theme } = useTheme();
-    const styles = useMemo(() => createStyles(theme), [theme]);
+    const styles = themedStyles(theme);
     const sizeConfig = SIZE_CONFIGS[size];
     const textStyle = StyleSheet.flatten([
         styles.label,
@@ -78,3 +78,4 @@ const createStyles = (theme) => StyleSheet.create({
         opacity: 0.6,
     },
 });
+const themedStyles = createThemedStyles(createStyles);

package/dist/components/Notification.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo, useCallback, use, useEffect, useEffectEvent, useRef } from "react";
+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";
@@ -10,6 +10,7 @@ import { durations } from "../constants/motion.js";
 import { StyledText } from "./StyledText.js";
 import { palette } from "../constants/colors.js";
 import { translateText } from "../lib/i18n.js";
+import { createThemedStyles } from "../lib/themedStyles.js";
 import { globalUIStore } from "../state/globalUIStore.js";
 const timingIn = { duration: durations.fast, easing: Easing.out(Easing.quad), useNativeDriver: true };
 const timingOut = { duration: durations.instant, easing: Easing.in(Easing.quad), useNativeDriver: true };
@@ -36,7 +37,7 @@ export const Notification = () => {
     const reduceMotion = useReducedMotion();
     const insets = use(SafeAreaInsetsContext);
     const { alert, hide } = globalUIStore();
-    const styles = useMemo(() => createStyles(theme), [theme]);
+    const styles = themedStyles(theme);
     const position = alert?.position ?? "top";
     const isBottom = position === "bottom";
     // Just opacity + translateY — no scale (scale = bouncy feel)
@@ -301,3 +302,4 @@ const createStyles = (theme) => StyleSheet.create({
         ...(Platform.OS === "web" && { cursor: "pointer" }),
     },
 });
+const themedStyles = createThemedStyles(createStyles);

package/dist/components/Skeleton.js

@@ -4,6 +4,7 @@ import { View, StyleSheet, Animated } from "react-native";
 import { useTheme } from "../hooks/useTheme.js";
 import { useReducedMotion } from "../hooks/useReduceMotion.js";
 import { spacing } from "../constants/spacing.js";
+import { createThemedStyles } from "../lib/themedStyles.js";
 /**
  * Skeleton Component
  *
@@ -72,7 +73,7 @@ export function SkeletonAvatar({ size = 40, style }) {
  */
 export function SkeletonCard({ showImage = true, imageHeight = 140, showAvatar = true, textLines = 3, style, }) {
     const { theme, getShadowStyle } = useTheme();
-    const styles = createCardStyles(theme);
+    const styles = themedStyles(theme);
     return (_jsxs(View, { style: [styles.card, getShadowStyle("subtle"), style], children: [showImage && (_jsx(Skeleton, { width: "100%", height: imageHeight, borderRadius: 0 })), _jsxs(View, { style: styles.body, children: [showAvatar && (_jsxs(View, { style: styles.avatarRow, children: [_jsx(SkeletonAvatar, { size: 36 }), _jsxs(View, { style: styles.avatarText, children: [_jsx(Skeleton, { width: "50%", height: 14 }), _jsx(Skeleton, { width: "30%", height: 12 })] })] })), _jsx(SkeletonText, { lines: textLines })] })] }));
 }
 const createCardStyles = (theme) => StyleSheet.create({
@@ -97,3 +98,4 @@ const createCardStyles = (theme) => StyleSheet.create({
         gap: spacing.xs,
     },
 });
+const themedStyles = createThemedStyles(createCardStyles);

package/dist/components/StyledText.js

@@ -2,7 +2,8 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { use } from "react";
 import { Platform, Text as RNText, StyleSheet } from "react-native";
 import { useTheme } from "../hooks/useTheme.js";
-import { fontFamilies } from "../constants/fonts.js";
+import { fontFamilies, defaultWebWeightStrategy } from "../constants/fonts.js";
+import { useThemeStore } from "../state/themeStore.js";
 import { translateText } from "../lib/i18n.js";
 import { TextColorContext, TextSelectabilityContext, TextStyleContext } from "./StyledText.context";
 const FONT_SIZES = {
@@ -89,6 +90,9 @@ const WEB_FONT_WEIGHTS = {
 export function StyledText(props) {
     const { tx, text, txOptions, style, variant = "sansSerif", fontWeight, size, semantic, align, selectable, children, ref, ...otherProps } = props;
     const { theme } = useTheme();
+    // Subscribed, not read via getState(), so a `setFonts` call after mount
+    // re-renders text instead of leaving stale families on screen.
+    const fontOverrides = useThemeStore((s) => s.fontOverrides);
     // Check if there's a color override from parent context (e.g., Button)
     const contextColor = use(TextColorContext);
     const contextTextStyle = use(TextStyleContext);
@@ -100,18 +104,31 @@ export function StyledText(props) {
     const semanticConfig = semantic ? SEMANTIC_CONFIGS[semantic] : undefined;
     const finalSize = semanticConfig?.size ?? size ?? "body";
     const finalFontWeight = semanticConfig?.weight ?? fontWeight ?? "regular";
-    // Get font family based on variant and weight
+    // Get font family based on variant and weight. Host apps can replace the
+    // package's bundled faces via `setFonts` (see constants/fonts.ts); merging
+    // per-group means an app overriding only `sansSerif` keeps the default serif.
     const fontFamilyWeight = getFontFamilyWeight(finalFontWeight);
-    // Georgia (serif) only has one weight — use it regardless of requested weight
+    const overriddenFamilies = fontOverrides.families;
+    const serifFamilies = overriddenFamilies?.serif ?? fontFamilies.serif;
+    const sansSerifFamilies = overriddenFamilies?.sansSerif ?? fontFamilies.sansSerif;
+    // The serif slot has a single usable weight — use it regardless of the
+    // requested weight.
     const fontFamily = variant === "serif"
-        ? fontFamilies.serif.regular
-        : fontFamilies.sansSerif[fontFamilyWeight] ?? fontFamilies.sansSerif.regular;
-    // Web ships one Inter family for every weight, so a numeric fontWeight picks
-    // the right @font-face variant. Native ships a discrete static font file per
-    // weight (see constants/fonts.ts) — the family name alone carries the
-    // weight there, and adding a numeric fontWeight on top would faux-bold an
-    // already-bold file, so this stays web-only.
-    const resolvedFontWeight = Platform.OS === "web" ? WEB_FONT_WEIGHTS[finalFontWeight] : undefined;
+        ? serifFamilies.regular
+        : sansSerifFamilies[fontFamilyWeight] ?? sansSerifFamilies.regular;
+    // Weight is carried either by a numeric `fontWeight` (one multi-weight CSS
+    // family) or by the family name itself (discrete per-weight faces). Native
+    // is always the latter: adding a numeric weight on top of an already-bold
+    // file faux-bolds it. Web defaults to numeric for the package's own single
+    // "Inter" family, but an app loading per-weight faces through `expo-font`
+    // gets its own family per weight on web too, and must declare
+    // `webWeightStrategy: "family"` to avoid a second synthesised layer of bold.
+    const weightStrategy = Platform.OS === "web"
+        ? fontOverrides.webWeightStrategy ?? defaultWebWeightStrategy
+        : "family";
+    const resolvedFontWeight = weightStrategy === "numeric"
+        ? WEB_FONT_WEIGHTS[finalFontWeight]
+        : undefined;
     // Get fontSize and lineHeight from size variant
     const fontSize = FONT_SIZES[finalSize];
     const lineHeight = LINE_HEIGHTS[finalSize];

package/dist/components/TextInput.js

@@ -8,6 +8,7 @@ import { fontFamilies } from "../constants/fonts.js";
 import { StyledText } from "./StyledText.js";
 import { Icon } from "./Icon.js";
 import { hapticLight } from "../lib/haptics.js";
+import { createThemedStyles } from "../lib/themedStyles.js";
 import { palette } from "../constants/colors.js";
 import { clearKeyboardFocusedInputLayout, setKeyboardFocusedInputLayout, } from "./keyboardFocusRegistry.js";
 const NUMERIC_REGEX = /^[0-9]*$/;
@@ -91,7 +92,7 @@ export function TextInput(props) {
  */
 function WebTextInput({ variant = "outline", size = "md", label, helperText, errorText, error, required, rows, showSecureEntryToggle, leftElement, rightElement, clearable = false, wrapperStyle, focusedStyle, forceLight, secureTextEntry, inputMode, style, onChangeText, onFocus, onBlur, value, multiline, editable = true, ref, ...rest }) {
     const { theme, getContrastingColor, getFocusRingStyle } = useTheme();
-    const styles = useMemo(() => createStyles(theme, variant, size), [theme, variant, size]);
+    const styles = themedStyles(theme)[variant][size];
     const [focused, setFocused] = useState(false);
     const [contentHeight, setContentHeight] = useState(0);
     const [passwordVisible, setPasswordVisible] = useState(false);
@@ -197,7 +198,7 @@ function NativeTextInput({ variant = "outline", size = "md", label, helperText,
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 leftElement, rightElement, clearable, focusedStyle, style, ...rest }) {
     const { theme, getContrastingColor } = useTheme();
-    const styles = useMemo(() => createStyles(theme, variant, size), [theme, variant, size]);
+    const styles = themedStyles(theme)[variant][size];
     const [passwordVisible, setPasswordVisible] = useState(false);
     const hasError = error || !!errorText;
     const sizeConfig = SIZE_CONFIGS[size];
@@ -443,3 +444,9 @@ const createStyles = (theme, variant, size) => StyleSheet.create({
         zIndex: 1,
     },
 });
+const VARIANT_KEYS = ["outline", "filled", "underlined"];
+const SIZE_KEYS = ["sm", "md", "lg"];
+const themedStyles = createThemedStyles((theme) => Object.fromEntries(VARIANT_KEYS.map((variant) => [
+    variant,
+    Object.fromEntries(SIZE_KEYS.map((size) => [size, createStyles(theme, variant, size)])),
+])));

package/dist/constants/fonts.d.ts

@@ -9,19 +9,55 @@ interface NavigationFonts {
     bold: FontStyle;
     heavy: FontStyle;
 }
-export declare const fontFamilies: {
+/** Weight slots every sans-serif family map must provide. */
+export type FontFamilyWeight = "light" | "regular" | "medium" | "semibold" | "bold";
+/**
+ * How a platform expresses weight for a given family map.
+ *
+ * - `"numeric"` — one multi-weight CSS family (the package's own web default:
+ *   a single `"Inter"` family where a numeric `fontWeight` selects the
+ *   `@font-face` variant).
+ * - `"family"` — each weight is its own separately-registered single-face
+ *   family, so the family name alone carries the weight. Emitting a numeric
+ *   `fontWeight` on top of one makes the renderer synthesise a second layer of
+ *   bold, so `StyledText` suppresses it.
+ *
+ * Native is always `"family"` (discrete static font files). Web is `"numeric"`
+ * by default, but apps that load per-weight faces through `expo-font` — which
+ * registers each file as its own family on web too — must declare `"family"`.
+ */
+export type FontWeightStrategy = "numeric" | "family";
+export type FontFamilyMap = {
     serif: {
         regular: string;
         bold: string;
     };
-    sansSerif: {
-        light: string;
-        regular: string;
-        medium: string;
-        semibold: string;
-        bold: string;
-    };
+    sansSerif: Record<FontFamilyWeight, string>;
 };
+/**
+ * Font overrides a host app can inject to brand the package.
+ *
+ * Mirrors `setColors`: the package ships neutral defaults, but a consuming app
+ * almost always bundles its own faces. Without an injection point, package
+ * components render the package's fonts while app-authored siblings render the
+ * app's — and the only remaining lever is patching `node_modules`, which is
+ * keyed to an exact version and silently stops applying on the next bump.
+ *
+ * Partial by design: override `sansSerif` alone and `serif` keeps its default.
+ */
+export type FontOverrides = {
+    families?: Partial<FontFamilyMap>;
+    /** Defaults to the package's own per-platform behaviour when omitted. */
+    webWeightStrategy?: FontWeightStrategy;
+};
+/** The package's built-in families. Override per-app via `setFonts`. */
+export declare const fontFamilies: FontFamilyMap;
+/**
+ * The package's own web weight strategy: one multi-weight "Inter" family, so
+ * weight comes from a numeric `fontWeight`. Native always behaves as
+ * `"family"` regardless of this value.
+ */
+export declare const defaultWebWeightStrategy: FontWeightStrategy;
 /**
  * Typography scale — Tailwind-matching sizes for consistent text hierarchy.
  * Components can progressively adopt these tokens.

package/dist/constants/fonts.js

@@ -42,10 +42,17 @@ const sansSerifFamilies = isWebRuntime
             semibold: "sans-serif",
             bold: "sans-serif",
         };
+/** The package's built-in families. Override per-app via `setFonts`. */
 export const fontFamilies = {
     serif: serifFamilies,
     sansSerif: sansSerifFamilies,
 };
+/**
+ * The package's own web weight strategy: one multi-weight "Inter" family, so
+ * weight comes from a numeric `fontWeight`. Native always behaves as
+ * `"family"` regardless of this value.
+ */
+export const defaultWebWeightStrategy = "numeric";
 export const typography = {
     xs: { fontSize: 12, lineHeight: 16 },
     sm: { fontSize: 14, lineHeight: 20 },

package/dist/lib/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./animations";
 export * from "./haptics";
 export * from "./i18n";
+export * from "./themedStyles";

package/dist/lib/index.js

@@ -1,3 +1,4 @@
 export * from "./animations.js";
 export * from "./haptics.js";
 export * from "./i18n.js";
+export * from "./themedStyles.js";

package/dist/lib/themedStyles.d.ts

@@ -0,0 +1,21 @@
+import { type Theme } from "../constants/colors";
+/**
+ * Registers theme-dependent styles at module scope so react-native-web
+ * inserts their CSS rules into the server-side sheet before the document
+ * <head> is serialized.
+ *
+ * Styles created lazily during render — the
+ * `useMemo(() => createStyles(theme), [theme])` idiom — are inserted into
+ * RNW's sheet *after* expo-router has already captured the
+ * `<style id="react-native-stylesheet">` snapshot for the head. The SSR
+ * HTML then references class names that have no rules, which paints
+ * completely unstyled until hydration re-inserts them client-side (worst
+ * on the first request after a server cold start, and on every dev
+ * rebundle). See docs/ssr-hydration.md.
+ *
+ * Both base themes are computed eagerly at module load. Themes carrying
+ * color overrides (global brand or scoped) are computed once per theme
+ * object identity — `useTheme` keeps that identity stable, so the WeakMap
+ * behaves like the old `useMemo` without the render-time registration.
+ */
+export declare function createThemedStyles<T extends object>(factory: (theme: Theme) => T): (theme: Theme) => T;

package/dist/lib/themedStyles.js

@@ -0,0 +1,33 @@
+import { colors } from "../constants/colors.js";
+/**
+ * Registers theme-dependent styles at module scope so react-native-web
+ * inserts their CSS rules into the server-side sheet before the document
+ * <head> is serialized.
+ *
+ * Styles created lazily during render — the
+ * `useMemo(() => createStyles(theme), [theme])` idiom — are inserted into
+ * RNW's sheet *after* expo-router has already captured the
+ * `<style id="react-native-stylesheet">` snapshot for the head. The SSR
+ * HTML then references class names that have no rules, which paints
+ * completely unstyled until hydration re-inserts them client-side (worst
+ * on the first request after a server cold start, and on every dev
+ * rebundle). See docs/ssr-hydration.md.
+ *
+ * Both base themes are computed eagerly at module load. Themes carrying
+ * color overrides (global brand or scoped) are computed once per theme
+ * object identity — `useTheme` keeps that identity stable, so the WeakMap
+ * behaves like the old `useMemo` without the render-time registration.
+ */
+export function createThemedStyles(factory) {
+    const cache = new WeakMap();
+    cache.set(colors.light, factory(colors.light));
+    cache.set(colors.dark, factory(colors.dark));
+    return (theme) => {
+        const cached = cache.get(theme);
+        if (cached)
+            return cached;
+        const created = factory(theme);
+        cache.set(theme, created);
+        return created;
+    };
+}

package/dist/state/themeStore.d.ts

@@ -1,4 +1,5 @@
 import type { ThemeColors } from "../constants/colors";
+import type { FontOverrides } from "../constants/fonts";
 export type ThemePreference = "system" | "light" | "dark";
 export type ResolvedTheme = "light" | "dark";
 /**
@@ -28,6 +29,12 @@ export type ThemeStore = {
      * behaves exactly as before this field existed (fully backward compatible).
      */
     colorOverrides: ColorOverrides;
+    /**
+     * App-injected font overrides, applied by `StyledText` on top of the package
+     * defaults. Empty by default — zero override means the package behaves
+     * exactly as before this field existed (fully backward compatible).
+     */
+    fontOverrides: FontOverrides;
     setTheme: (theme: ThemePreference) => void;
     setSystemTheme: (theme: ResolvedTheme) => void;
     /**
@@ -35,6 +42,16 @@ export type ThemeStore = {
      * clear overrides and fall back to the package defaults.
      */
     setColors: (overrides: ColorOverrides) => void;
+    /**
+     * Replace the active font overrides. Pass `{}` to clear them and fall back
+     * to the package's bundled faces.
+     *
+     * Call this once at startup, after the app's fonts have been registered
+     * (e.g. alongside `setColors` in a theme-sync component). Apps loading
+     * per-weight faces via `expo-font` should also pass
+     * `webWeightStrategy: "family"` — see `FontWeightStrategy`.
+     */
+    setFonts: (overrides: FontOverrides) => void;
     loadTheme: () => void;
 };
 export declare function resolveThemePreference(userTheme: ThemePreference, systemTheme: ResolvedTheme): ResolvedTheme;

package/dist/state/themeStore.js

@@ -19,9 +19,15 @@ export const useThemeStore = create((set) => ({
     // No overrides by default: the package renders with its built-in palette
     // until a host app calls `setColors`.
     colorOverrides: {},
+    // Same contract as `colorOverrides`: the package renders with its bundled
+    // faces until a host app calls `setFonts`.
+    fontOverrides: {},
     setColors: (overrides) => {
         set({ colorOverrides: overrides ?? {} });
     },
+    setFonts: (overrides) => {
+        set({ fontOverrides: overrides ?? {} });
+    },
     setTheme: (theme) => {
         set({
             userTheme: theme,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrmeg/expo-ui",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [