@mrmeg/expo-ui 0.15.0 → 0.17.0

package/dist/components/StyledText.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { use } from "react";
-import { Platform, Text as RNText, StyleSheet } from "react-native";
+import { Text as RNText, StyleSheet } from "react-native";
 import { useTheme } from "../hooks/useTheme.js";
-import { fontFamilies } from "../constants/fonts.js";
+import { resolveFontStyle } 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 = {
@@ -54,22 +55,6 @@ const SEMANTIC_CONFIGS = {
     // and the textTransform applied in StyledText below.
     eyebrow: { size: "sm", weight: "semibold" },
 };
-// Font family weight keys now map 1:1 onto FontWeight — every weight has a
-// real family entry (native: a distinct static Inter file; web: shared
-// "Inter" family + numeric fontWeight, see WEB_FONT_WEIGHTS). Defaults to
-// "regular" when no weight is requested.
-const getFontFamilyWeight = (weight) => weight ?? "regular";
-// Web-only: the numeric fontWeight that picks the right @font-face variant
-// out of the single shared "Inter" CSS family. "light" has no loaded 300
-// weight (mirrors the native light->regular mapping in constants/fonts.ts),
-// so it renders at 400 like "regular".
-const WEB_FONT_WEIGHTS = {
-    light: "400",
-    regular: "400",
-    medium: "500",
-    semibold: "600",
-    bold: "700",
-};
 /**
  * Base Text component with theme and variant support
  * Uses theme colors automatically - text by default
@@ -89,6 +74,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 +88,12 @@ 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
-    const fontFamilyWeight = getFontFamilyWeight(finalFontWeight);
-    // Georgia (serif) only has one weight — use it regardless of 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;
+    // Get font family (+ numeric fontWeight under the web "numeric" strategy)
+    // based on variant and weight. Host apps replace the package's bundled
+    // faces via `setFonts`; resolution — including the per-group merge and the
+    // numeric-vs-family weight strategy — lives in `resolveFontStyle`
+    // (constants/fonts.ts), shared with the control components' `useFontStyle`.
+    const { fontFamily, fontWeight: resolvedFontWeight } = resolveFontStyle(fontOverrides, variant, finalFontWeight);
     // Get fontSize and lineHeight from size variant
     const fontSize = FONT_SIZES[finalSize];
     const lineHeight = LINE_HEIGHTS[finalSize];
@@ -160,6 +142,15 @@ export function SerifText(props) {
 export function SansSerifText(props) {
     return _jsx(StyledText, { ...props, variant: "sansSerif" });
 }
+/**
+ * Mono Text Component
+ * Uses the monospace font family (the platform's system monospace by
+ * default; host apps swap in their own via `setFonts`) — for code, IDs,
+ * and tabular figures
+ */
+export function MonoText(props) {
+    return _jsx(StyledText, { ...props, variant: "mono" });
+}
 /**
  * Serif Bold Text Component
  * Uses the serif font family — Georgia's only shipped weight is regular

package/dist/components/Switch.js

@@ -1,6 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { palette } from "../constants/colors.js";
-import { fontFamilies } from "../constants/fonts.js";
 import { spacing } from "../constants/spacing.js";
 import { useTheme } from "../hooks/useTheme.js";
 import { hapticLight } from "../lib/haptics.js";
@@ -119,8 +118,7 @@ function Switch({ variant = "default", labelOn, labelOff, size = { width: 44, he
                         left: labelHorizontalInset,
                         right: thumbInset + thumbSize + labelGap,
                         opacity: props.checked ? 1 : 0,
-                    }, children: _jsx(StyledText, { selectable: false, style: {
-                            fontFamily: fontFamilies.sansSerif.bold,
+                    }, children: _jsx(StyledText, { selectable: false, fontWeight: "bold", style: {
                             fontSize: labelFontSize,
                             color: labelOnColor,
                             userSelect: "none",
@@ -143,8 +141,7 @@ function Switch({ variant = "default", labelOn, labelOff, size = { width: 44, he
                         left: thumbInset + thumbSize + labelGap,
                         right: labelHorizontalInset,
                         opacity: props.checked ? 0 : 1,
-                    }, children: _jsx(StyledText, { selectable: false, style: {
-                            fontFamily: fontFamilies.sansSerif.bold,
+                    }, children: _jsx(StyledText, { selectable: false, fontWeight: "bold", style: {
                             fontSize: labelFontSize,
                             color: theme.colors.text,
                             userSelect: "none",

package/dist/components/TextInput.js

@@ -4,10 +4,11 @@ import { StyleSheet, TextInput as RNTextInput, Platform, View, Pressable, } from
 import { Host, TextInput as ExpoTextInput, useNativeState, } from "@expo/ui";
 import { useTheme } from "../hooks/useTheme.js";
 import { spacing } from "../constants/spacing.js";
-import { fontFamilies } from "../constants/fonts.js";
+import { useFontStyle } from "../hooks/useFontStyle.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,8 @@ 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 inputFont = useFontStyle("regular");
     const [focused, setFocused] = useState(false);
     const [contentHeight, setContentHeight] = useState(0);
     const [passwordVisible, setPasswordVisible] = useState(false);
@@ -148,6 +150,9 @@ function WebTextInput({ variant = "outline", size = "md", label, helperText, err
     };
     return (_jsxs(View, { style: wrapperStyle, children: [!!label && (_jsx(View, { style: styles.labelContainer, children: _jsxs(StyledText, { selectable: false, size: "base", fontWeight: "medium", style: styles.label, children: [label, required && _jsx(StyledText, { selectable: false, fontWeight: "bold", style: styles.required, children: " *" })] }) })), _jsxs(View, { style: [styles.wrapper, focused && getFocusRingStyle()], children: [leftElement && _jsx(View, { style: styles.leftElement, children: leftElement }), _jsx(RNTextInput, { ref: ref, ...rest, editable: editable, inputMode: inputMode || "text", multiline: multiline, numberOfLines: rows, secureTextEntry: secureTextEntry && !passwordVisible, onChangeText: inputMode === "numeric" ? handleNumericChange : handleTextChange, onFocus: showInputFocusRing, onBlur: hideInputFocusRing, onContentSizeChange: (e) => setContentHeight(e.nativeEvent.contentSize.height), scrollEnabled: shouldScroll, placeholderTextColor: theme.colors.textDim, style: [
                             styles.input,
+                            // Resolved through the theme store so `setFonts` overrides apply;
+                            // identical to the old hardcoded regular family by default.
+                            inputFont,
                             {
                                 backgroundColor,
                                 borderColor,
@@ -197,7 +202,8 @@ 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 inputFont = useFontStyle("regular");
     const [passwordVisible, setPasswordVisible] = useState(false);
     const hasError = error || !!errorText;
     const sizeConfig = SIZE_CONFIGS[size];
@@ -318,10 +324,12 @@ leftElement, rightElement, clearable, focusedStyle, style, ...rest }) {
     // @expo/ui passes the family verbatim to SwiftUI's Font.custom / Compose,
     // where no such font exists — the fallback ignores fontSize and renders at
     // the 17pt default, blowing up text and secure-entry dots. Omit the family
-    // so the native side uses the system font at our requested size.
-    const nativeFontFamily = fontFamilies.sansSerif.regular === "System"
+    // so the native side uses the system font at our requested size. The family
+    // itself resolves through the theme store (`useFontStyle` above) so
+    // `setFonts` overrides reach the native field too.
+    const nativeFontFamily = inputFont.fontFamily === "System"
         ? undefined
-        : fontFamilies.sansSerif.regular;
+        : inputFont.fontFamily;
     const textStyle = {
         color: textColor,
         fontSize: sizeConfig.fontSize,
@@ -352,7 +360,8 @@ const createStyles = (theme, variant, size) => StyleSheet.create({
         justifyContent: "center",
     },
     input: {
-        fontFamily: fontFamilies.sansSerif.regular,
+        // fontFamily is resolved per-render through the theme store (see
+        // `useFontStyle("regular")` in WebTextInput) so `setFonts` applies.
         borderRadius: spacing.radiusMd,
         borderWidth: 1,
         ...(Platform.OS === "web" && { outlineStyle: "none" }),
@@ -443,3 +452,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,80 @@ interface NavigationFonts {
     bold: FontStyle;
     heavy: FontStyle;
 }
-export declare const fontFamilies: {
-    serif: {
-        regular: string;
-        bold: string;
-    };
-    sansSerif: {
-        light: string;
-        regular: string;
-        medium: string;
-        semibold: string;
-        bold: string;
-    };
+/** 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";
+/** The font variants text components can render. */
+export type FontVariant = "sansSerif" | "serif" | "mono";
+export type FontFamilyMap = Record<FontVariant, Record<FontFamilyWeight, string>>;
+/**
+ * A per-variant override group. Partial per weight: missing weights fall back
+ * to the group's own `regular` (not the package default), so an app that
+ * registers only Regular + Medium never leaks a package face into its brand.
+ */
+export type FontFamilyOverride = Partial<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`/`mono` keep their
+ * defaults.
+ */
+export type FontOverrides = {
+    families?: Partial<Record<FontVariant, FontFamilyOverride>>;
+    /** 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;
+export type ResolvedFontStyle = {
+    fontFamily: string;
+    /** Present only under the `"numeric"` weight strategy (web). */
+    fontWeight?: "400" | "500" | "600" | "700";
+};
+/**
+ * Resolve the `fontFamily` (+ optional numeric `fontWeight`) for a variant and
+ * weight, honouring any host-app `setFonts` overrides.
+ *
+ * This is the single source of truth every text-rendering component goes
+ * through — `StyledText` directly, control components via `useFontStyle` —
+ * so a host override re-skins package text everywhere at once.
+ *
+ * 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.
+ */
+export declare function resolveFontStyle(overrides: FontOverrides, variant: FontVariant, weight: FontFamilyWeight): ResolvedFontStyle;
 /**
  * Typography scale — Tailwind-matching sizes for consistent text hierarchy.
  * Components can progressively adopt these tokens.

package/dist/constants/fonts.js

@@ -8,9 +8,45 @@ const WEB_FONT_STACK = "system-ui, \"Segoe UI\", Roboto, Helvetica, Arial, sans-
 // both environments, so the value is stable.
 const isWebRuntime = Platform.OS === "web";
 const isReactNativeRuntime = Platform.OS !== "web";
+// Georgia ships as one face per platform; every weight slot points at the
+// same family and weight differentiation only appears when a host app
+// overrides serif with real per-weight faces via `setFonts`.
+const webSerifFamily = "Georgia, 'Times New Roman', serif";
 const serifFamilies = isWebRuntime
-    ? { regular: "Georgia, 'Times New Roman', serif", bold: "Georgia, 'Times New Roman', serif" }
-    : { regular: "Georgia", bold: "Georgia" };
+    ? {
+        light: webSerifFamily,
+        regular: webSerifFamily,
+        medium: webSerifFamily,
+        semibold: webSerifFamily,
+        bold: webSerifFamily,
+    }
+    : {
+        light: "Georgia",
+        regular: "Georgia",
+        medium: "Georgia",
+        semibold: "Georgia",
+        bold: "Georgia",
+    };
+// Same single-face story as serif: the package doesn't bundle a mono font, it
+// leans on each platform's system monospace. Menlo on iOS ("monospace" isn't
+// a resolvable family name there); Android resolves "monospace" natively.
+const WEB_MONO_STACK = "ui-monospace, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace";
+const nativeMonoFamily = Platform.OS === "ios" ? "Menlo" : "monospace";
+const monoFamilies = isWebRuntime
+    ? {
+        light: WEB_MONO_STACK,
+        regular: WEB_MONO_STACK,
+        medium: WEB_MONO_STACK,
+        semibold: WEB_MONO_STACK,
+        bold: WEB_MONO_STACK,
+    }
+    : {
+        light: nativeMonoFamily,
+        regular: nativeMonoFamily,
+        medium: nativeMonoFamily,
+        semibold: nativeMonoFamily,
+        bold: nativeMonoFamily,
+    };
 // Web ships one Inter CSS family for every weight — weight differentiation
 // comes from a numeric `fontWeight` set alongside this family (see
 // StyledText's getFontFamilyWeight). Native ships four discrete Inter static
@@ -42,10 +78,60 @@ 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,
+    mono: monoFamilies,
+};
+/**
+ * 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";
+/**
+ * Web-only numeric weights, used under the `"numeric"` strategy to pick the
+ * right `@font-face` variant out of a single multi-weight CSS family.
+ * `light` has no loaded 300 weight (mirrors the native light->regular file
+ * mapping above), so it renders at 400 like `regular`.
+ */
+const WEB_FONT_WEIGHTS = {
+    light: "400",
+    regular: "400",
+    medium: "500",
+    semibold: "600",
+    bold: "700",
 };
+/**
+ * Resolve the `fontFamily` (+ optional numeric `fontWeight`) for a variant and
+ * weight, honouring any host-app `setFonts` overrides.
+ *
+ * This is the single source of truth every text-rendering component goes
+ * through — `StyledText` directly, control components via `useFontStyle` —
+ * so a host override re-skins package text everywhere at once.
+ *
+ * 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.
+ */
+export function resolveFontStyle(overrides, variant, weight) {
+    const defaults = fontFamilies[variant];
+    const overrideGroup = overrides.families?.[variant];
+    const fontFamily = overrideGroup
+        ? overrideGroup[weight] ?? overrideGroup.regular ?? defaults[weight]
+        : defaults[weight];
+    const strategy = Platform.OS === "web"
+        ? overrides.webWeightStrategy ?? defaultWebWeightStrategy
+        : "family";
+    return strategy === "numeric"
+        ? { fontFamily, fontWeight: WEB_FONT_WEIGHTS[weight] }
+        : { fontFamily };
+}
 export const typography = {
     xs: { fontSize: 12, lineHeight: 16 },
     sm: { fontSize: 14, lineHeight: 20 },

package/dist/hooks/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./useDimensions";
+export * from "./useFontStyle";
 export * from "./useReduceMotion";
 export * from "./useResources";
 export * from "./useScalePress";

package/dist/hooks/index.js

@@ -1,4 +1,5 @@
 export * from "./useDimensions.js";
+export * from "./useFontStyle.js";
 export * from "./useReduceMotion.js";
 export * from "./useResources.js";
 export * from "./useScalePress.js";

package/dist/hooks/useFontStyle.d.ts

@@ -0,0 +1,11 @@
+import { type FontFamilyWeight, type FontVariant, type ResolvedFontStyle } from "../constants/fonts";
+/**
+ * Resolve a `{ fontFamily, fontWeight? }` style through the theme store's
+ * font overrides, re-rendering when a host app calls `setFonts`.
+ *
+ * For control components (Button, Label, TextInput, …) whose typography is
+ * a fixed weight rather than caller-driven. With no overrides set, the result
+ * is identical to the package's hardcoded families, so layering it after a
+ * static themed style changes nothing by default.
+ */
+export declare function useFontStyle(weight?: FontFamilyWeight, variant?: FontVariant): ResolvedFontStyle;

package/dist/hooks/useFontStyle.js

@@ -0,0 +1,17 @@
+import { resolveFontStyle, } from "../constants/fonts.js";
+import { useThemeStore } from "../state/themeStore.js";
+/**
+ * Resolve a `{ fontFamily, fontWeight? }` style through the theme store's
+ * font overrides, re-rendering when a host app calls `setFonts`.
+ *
+ * For control components (Button, Label, TextInput, …) whose typography is
+ * a fixed weight rather than caller-driven. With no overrides set, the result
+ * is identical to the package's hardcoded families, so layering it after a
+ * static themed style changes nothing by default.
+ */
+export function useFontStyle(weight = "regular", variant = "sansSerif") {
+    // Subscribed, not read via getState(), so a `setFonts` call after mount
+    // re-renders instead of leaving stale families on screen.
+    const fontOverrides = useThemeStore((s) => s.fontOverrides);
+    return resolveFontStyle(fontOverrides, variant, weight);
+}

package/dist/hooks/useResources.d.ts

@@ -9,6 +9,13 @@ interface LoadResourcesResult {
  * @expo-google-fonts/inter) so StyledText's weight range resolves to real
  * font files. Web loads Inter from Google Fonts as a single CSS family;
  * weight differentiation there comes from a numeric fontWeight instead.
+ *
+ * A host app that overrides the sans-serif families via `setFonts` owns
+ * loading its own faces (typically through `expo-font`), so the Inter fetch
+ * is skipped entirely — nothing would reference those files. For the skip to
+ * apply, call `setFonts` before this hook mounts (module scope or ahead of
+ * rendering the root); a later call still re-skins text, it just doesn't
+ * un-download Inter. The Feather icon font always loads.
  */
 export declare const useResources: () => LoadResourcesResult;
 export {};

package/dist/hooks/useResources.js

@@ -3,6 +3,7 @@ import * as Font from "expo-font";
 import Feather from "@expo/vector-icons/Feather";
 import { Inter_400Regular, Inter_500Medium, Inter_600SemiBold, Inter_700Bold, } from "@expo-google-fonts/inter";
 import { Platform } from "react-native";
+import { useThemeStore } from "../state/themeStore.js";
 // Eager, module-scope load so expo-font registers Feather in its SSR
 // serverContext. When the server renders the HTML document, expo-font emits
 // an @font-face <style> into the head — without this kickoff, server-rendered
@@ -56,18 +57,28 @@ function ensureWebFontStylesheet() {
  * @expo-google-fonts/inter) so StyledText's weight range resolves to real
  * font files. Web loads Inter from Google Fonts as a single CSS family;
  * weight differentiation there comes from a numeric fontWeight instead.
+ *
+ * A host app that overrides the sans-serif families via `setFonts` owns
+ * loading its own faces (typically through `expo-font`), so the Inter fetch
+ * is skipped entirely — nothing would reference those files. For the skip to
+ * apply, call `setFonts` before this hook mounts (module scope or ahead of
+ * rendering the root); a later call still re-skins text, it just doesn't
+ * un-download Inter. The Feather icon font always loads.
  */
 export const useResources = () => {
     const [loaded, setLoaded] = useState(false);
     const [error, setError] = useState(null);
     useEffect(() => {
         let timeoutId;
+        // Read once at mount, not subscribed: font loading is a one-shot startup
+        // effect and cannot be undone by a later override.
+        const sansSerifOverridden = !!useThemeStore.getState().fontOverrides.families?.sansSerif;
         async function loadResourcesAndDataAsync() {
             try {
                 const fontPromise = Promise.all([
                     Font.loadAsync(Feather.font),
-                    loadNativeInterFonts(),
-                    ensureWebFontStylesheet(),
+                    sansSerifOverridden ? Promise.resolve() : loadNativeInterFonts(),
+                    sansSerifOverridden ? Promise.resolve() : ensureWebFontStylesheet(),
                 ]);
                 // Timeout after 5 seconds — proceed with system fallback fonts
                 const timeoutPromise = new Promise((_, reject) => {

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";
 /**
@@ -19,6 +20,27 @@ export type ColorOverrides = {
     light?: Partial<ThemeColors>;
     dark?: Partial<ThemeColors>;
 };
+/**
+ * Shape overrides a host app can inject, grouped per component so future
+ * shape knobs (card radius, input radius, …) slot in without reshaping the
+ * API. Every field is optional; omitted fields keep the package default.
+ */
+export type ShapeOverrides = {
+    button?: {
+        /**
+         * Border radius applied to every Button preset. Package default:
+         * `spacing.radiusMd` (12). Use 9999 for pill buttons. A caller `style`
+         * still wins over this, as it always has.
+         */
+        borderRadius?: number;
+        /**
+         * Whether the `default` preset renders its shadow. Package default: true.
+         * Other presets stay flat regardless; the per-instance `withShadow` prop
+         * still wins over this.
+         */
+        withShadow?: boolean;
+    };
+};
 export type ThemeStore = {
     userTheme: ThemePreference;
     systemTheme: ResolvedTheme;
@@ -28,6 +50,18 @@ 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;
+    /**
+     * App-injected shape overrides (button radius, default-preset shadow).
+     * Same contract as the other override slots: empty by default, fully
+     * backward compatible when unset.
+     */
+    shapeOverrides: ShapeOverrides;
     setTheme: (theme: ThemePreference) => void;
     setSystemTheme: (theme: ResolvedTheme) => void;
     /**
@@ -35,6 +69,21 @@ 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;
+    /**
+     * Replace the active shape overrides. Pass `{}` to clear them and fall back
+     * to the package defaults (button radius 12, default-preset shadow on).
+     */
+    setShape: (overrides: ShapeOverrides) => void;
     loadTheme: () => void;
 };
 export declare function resolveThemePreference(userTheme: ThemePreference, systemTheme: ResolvedTheme): ResolvedTheme;