@mrmeg/expo-ui 0.20.0 → 0.22.0

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

@@ -2,10 +2,11 @@ import { Platform } from "react-native";
 // Web font stack fallback
 const WEB_FONT_STACK = "system-ui, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif, \"Apple Color Emoji\", \"Segoe UI Emoji\", \"Segoe UI Symbol\"";
 // IMPORTANT: do NOT key these on `typeof document` / `typeof navigator`.
-// On a web bundle, Node SSR sees `undefined` for both and the client sees them,
-// producing different snapshot values at module load -> hydration mismatch on
-// every <StyledText>. `Platform.OS` (from react-native-web) returns "web" in
-// both environments, so the value is stable.
+// A web bundle is also evaluated in Node when a host app's HTML shell is
+// rendered at export time, where both are `undefined` while the browser sees
+// them — that produces different module-load snapshots and a hydration
+// mismatch on every <StyledText>. `Platform.OS` (from react-native-web)
+// returns "web" in 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

package/dist/hooks/useDimensions.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Viewport the first web render is computed from, before the real window can
+ * be read. Desktop is chosen because:
+ *   1. A desktop visitor sees no reflow — their real viewport lands in the
+ *      same breakpoint.
+ *   2. A mobile visitor gets one frame of desktop-styled content before the
+ *      post-mount effect snaps to real dimensions — better than the inverse
+ *      (every desktop visitor seeing mobile-tiny, then snapping).
+ *   3. It matches the frame the app hands `SafeAreaProvider`, and it is the
+ *      value the HTML shell `expo export` renders in Node is built from, so
+ *      the browser's first render agrees with the markup it hydrates.
+ */
+export declare const DEFAULT_VIEWPORT_WIDTH = 1280;
+export declare const DEFAULT_VIEWPORT_HEIGHT = 800;
 export declare const SCREEN_SIZES: {
     readonly SMALL: 768;
     readonly MEDIUM: 1000;
@@ -15,15 +29,13 @@ type WindowDimensions = {
 * Provides a consistent way to access window dimensions and screen size
 * information across mobile and web.
 *
-* On web SSR, the initial width comes from `SsrViewportContext`, which a
-* route's loader can populate from a `mrmeg-vw` cookie (precise, from
-* previous visit) or User-Agent heuristics. Both server and the initial
-* client render read the same context value so hydration matches; after
-* mount, real dimensions take over and the cookie is updated for next time.
-*
-* Routes that don't provide the context get the package default
-* (`SSR_VIEWPORT_DEFAULT_WIDTH` = 1280) — desktop-correct, mobile gets one
-* frame of desktop layout before snapping.
+* 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,6 +1,20 @@
 import { use, useEffect, useState } from "react";
 import { Platform, useWindowDimensions } from "react-native";
-import { SsrViewportContext, SSR_VIEWPORT_DEFAULT_HEIGHT, } from "../state/SsrViewportContext.js";
+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:
+ *   1. A desktop visitor sees no reflow — their real viewport lands in the
+ *      same breakpoint.
+ *   2. A mobile visitor gets one frame of desktop-styled content before the
+ *      post-mount effect snaps to real dimensions — better than the inverse
+ *      (every desktop visitor seeing mobile-tiny, then snapping).
+ *   3. It matches the frame the app hands `SafeAreaProvider`, and it is the
+ *      value the HTML shell `expo export` renders in Node is built from, so
+ *      the browser's first render agrees with the markup it hydrates.
+ */
+export const DEFAULT_VIEWPORT_WIDTH = 1280;
+export const DEFAULT_VIEWPORT_HEIGHT = 800;
 export const SCREEN_SIZES = {
     SMALL: 768,
     MEDIUM: 1000,
@@ -21,9 +35,9 @@ const calculateDimensionFlags = (width, height) => {
     };
 };
 // Persist the real viewport width as a cookie on first mount so subsequent
-// SSR requests can render with the user's actual layout (no flash on repeat
-// visits). The server reads this cookie via your route loader using
-// `detectSsrViewportWidth(request)` from server/lib/ssrViewport.ts.
+// 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) {
@@ -38,15 +52,13 @@ function writeViewportCookie(width) {
 * Provides a consistent way to access window dimensions and screen size
 * information across mobile and web.
 *
-* On web SSR, the initial width comes from `SsrViewportContext`, which a
-* route's loader can populate from a `mrmeg-vw` cookie (precise, from
-* previous visit) or User-Agent heuristics. Both server and the initial
-* client render read the same context value so hydration matches; after
-* mount, real dimensions take over and the cookie is updated for next time.
-*
-* Routes that don't provide the context get the package default
-* (`SSR_VIEWPORT_DEFAULT_WIDTH` = 1280) — desktop-correct, mobile gets one
-* frame of desktop layout before snapping.
+* 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";
@@ -54,13 +66,12 @@ export const useDimensions = () => {
     // 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 SSR context + the resize listener below so hydration stays exact.
+    // from the seeded frame + the resize listener below.
     const native = useWindowDimensions();
-    // Lazy initializer: both server and client first render compute identical
-    // flags from the context value, so hydration matches.
-    const [dimensions, setDimensions] = useState(() => calculateDimensionFlags(ssrWidth, SSR_VIEWPORT_DEFAULT_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) preserves the SSR-matched first paint.
+    // this in an effect (not render) keeps the first render identical to the
+    // exported markup it hydrates.
     useEffect(() => {
         if (!isWeb)
             return;

package/dist/hooks/useResources.d.ts

@@ -1,12 +1,15 @@
 /**
- * Registers the Feather icon font in expo-font's per-request SSR store.
+ * 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** on server-web (see `useResources`
- * below): expo-font enters an `AsyncLocalStorage` store per request, so a
- * module-scope registration lands in at most one request's store. Registering
- * during render means every request emits the `@font-face` rule into
- * `<style id="expo-generated-fonts">` and server-rendered `<Icon>`s agree with
- * the client's first render.
+ * 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).

package/dist/hooks/useResources.js

@@ -4,31 +4,29 @@ 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 that primes the Feather font on the *client* before
-// first render: on web it synchronously injects the @font-face rule, which is
-// what makes the client's `Font.isLoaded("feather")` check read true during
-// hydration; on native it just starts the fetch ahead of the effect below
-// (which then no-ops for the already-loaded font).
+// Eager, module-scope load that primes the Feather font before first render:
+// on web it synchronously injects the @font-face rule, so icons have their
+// glyphs on the first paint; on native it just starts the fetch ahead of the
+// effect below (which then no-ops for the already-loaded font).
 //
-// Deliberately guarded off server-web. expo-font's SSR store is per-request
-// AsyncLocalStorage, and Metro's inlineRequires defers this module's evaluation
-// until it is first required during a render — so on the server this line only
-// ever populated the store of whichever request happened to warm the module
-// cache. Requests 2+ then shipped HTML with no @font-face and empty icons while
-// the client rendered glyphs (React #418). Server registration happens
-// per-request in ensureIconFontRegistered() instead.
+// Guarded on `window` because web bundles are also evaluated in Node when
+// `expo export` renders the HTML shell, where there is no document to inject
+// into.
 if (typeof window !== "undefined") {
     void Font.loadAsync(Feather.font);
 }
 /**
- * Registers the Feather icon font in expo-font's per-request SSR store.
+ * 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** on server-web (see `useResources`
- * below): expo-font enters an `AsyncLocalStorage` store per request, so a
- * module-scope registration lands in at most one request's store. Registering
- * during render means every request emits the `@font-face` rule into
- * `<style id="expo-generated-fonts">` and server-rendered `<Icon>`s agree with
- * the client's first render.
+ * 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).
@@ -37,9 +35,9 @@ export function ensureIconFontRegistered() {
     if (Platform.OS !== "web" || typeof window !== "undefined")
         return;
     if (Font.isLoaded("feather"))
-        return; // per-request store; cheap
+        return;
     // Synchronous on server-web (expo-font routes to registerStaticFont). No
-    // `void`/try-catch: a throw here means we're outside a request scope, which
+    // `void`/try-catch: a throw here means we're outside a render scope, which
     // must be loud.
     Font.loadAsync(Feather.font);
 }
@@ -96,9 +94,8 @@ function ensureWebFontStylesheet() {
  * un-download Inter. The Feather icon font always loads.
  */
 export const useResources = () => {
-    // Render-body (not effect) so server-web registers the icon font in *this*
-    // request's expo-font store — effects never run on the server and a
-    // module-scope call only reaches one request. See ensureIconFontRegistered.
+    // 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);

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

@@ -1,17 +1,17 @@
 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.
+ * inserts their CSS rules into the sheet before the prerendered document
+ * <head> is serialized at export time.
  *
  * 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.
+ * `<style id="react-native-stylesheet">` snapshot for the head. The exported
+ * HTML shell then references class names that have no rules, which paints
+ * completely unstyled until the client re-inserts them on hydration (worst
+ * on a cold load of the shell, and on every dev rebundle). See "Enable
+ * Server Output" in docs/server-guide.md.
  *
  * Both base themes are computed eagerly at module load. Themes carrying
  * color overrides (global brand or scoped) are computed once per theme

package/dist/lib/themedStyles.js

@@ -1,17 +1,17 @@
 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.
+ * inserts their CSS rules into the sheet before the prerendered document
+ * <head> is serialized at export time.
  *
  * 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.
+ * `<style id="react-native-stylesheet">` snapshot for the head. The exported
+ * HTML shell then references class names that have no rules, which paints
+ * completely unstyled until the client re-inserts them on hydration (worst
+ * on a cold load of the shell, and on every dev rebundle). See "Enable
+ * Server Output" in docs/server-guide.md.
  *
  * Both base themes are computed eagerly at module load. Themes carrying
  * color overrides (global brand or scoped) are computed once per theme

package/dist/state/SsrViewportContext.d.ts

@@ -1,41 +1,12 @@
-/**
- * Default viewport used during SSR and the initial client render. Desktop is
- * chosen because:
- *   1. Most web traffic for app dashboards / marketing pages skews desktop.
- *   2. Desktop visitors see no layout reflow on hydration (SSR layout matches
- *      their actual viewport's breakpoint).
- *   3. Mobile visitors get one frame of desktop-styled content before
- *      `useDimensions`'s post-mount effect snaps to real dimensions — better
- *      than the inverse (every desktop visitor sees mobile-tiny then snap).
- *
- * Projects that skew mobile can override with their own Provider higher in
- * the tree, or per-page via a loader that detects from cookie / User-Agent.
- */
-export declare const SSR_VIEWPORT_DEFAULT_WIDTH = 1280;
-export declare const SSR_VIEWPORT_DEFAULT_HEIGHT = 800;
 /**
  * Per-request SSR viewport width. Consumed by `useDimensions` to seed the
- * initial responsive render so it matches what the user sees.
- *
- * Set the provider near the top of your tree (typically in a route component
- * whose loader detects the viewport from a cookie or User-Agent):
- *
- * ```tsx
- * import { SsrViewportContext } from "@mrmeg/expo-ui/state";
- * import { detectSsrViewportWidth } from "@/server/lib/ssrViewport";
- *
- * export const loader: LoaderFunction<{ ssrViewportWidth?: number }> = (request) => ({
- *   ssrViewportWidth: detectSsrViewportWidth(request),
- * });
- *
- * export default function Page() {
- *   const { ssrViewportWidth } = useLoaderData<typeof loader>();
- *   return (
- *     <SsrViewportContext.Provider value={ssrViewportWidth ?? SSR_VIEWPORT_DEFAULT_WIDTH}>
- *       ...
- *     </SsrViewportContext.Provider>
- *   );
- * }
- * ```
+ * 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>;
+export declare const SsrViewportContext: import("react").Context<number | null>;