@oxyhq/services 28.0.0 → 29.0.0

package/src/ui/hooks/useSessionManagement.ts

@@ -1,7 +1,6 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useMemo, useRef } from 'react';
 import { isDev, type ApiError, type User } from '@oxyhq/core';
 import type { ClientSession } from '@oxyhq/core';
-import { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual } from '@oxyhq/core';
 import { fetchSessionsWithFallback } from '../utils/sessionHelpers';
 import { getStorageKeys, type StorageInterface } from '../utils/storageHelpers';
 import { handleAuthError, isInvalidSessionError } from '../utils/errorHandlers';
@@ -10,109 +9,80 @@ import type { QueryClient } from '@tanstack/react-query';
 import { clearQueryCache } from './queryClient';
 import { isWebBrowser } from '../utils/isWebBrowser';
 import { resetSessionScopedStores } from '../stores/resetSessionScopedStores';
+import type { OxyRuntime } from '../runtime';
 
 export interface UseSessionManagementOptions {
   oxyServices: OxyServices;
+  /** The one owner of `sessions` / `activeSessionId` / the signed-in account. */
+  runtime: OxyRuntime;
   storage: StorageInterface | null;
   storageKeyPrefix?: string;
-  loginSuccess: (user: User) => void;
-  logoutStore: () => void;
   onAuthStateChange?: (user: User | null) => void;
   onError?: (error: ApiError) => void;
   setAuthError?: (message: string | null) => void;
   logger?: (message: string, error?: unknown) => void;
-  setTokenReady?: (ready: boolean) => void;
   queryClient?: QueryClient | null;
 }
 
 export interface UseSessionManagementResult {
-  sessions: ClientSession[];
-  activeSessionId: string | null;
-  setActiveSessionId: (sessionId: string | null) => void;
-  updateSessions: (incoming: ClientSession[], options?: { merge?: boolean; preserveSessionIds?: string[] }) => void;
+  /** Persist the projected session-id list. Handed to the runtime as its projection sink. */
+  saveSessionIds: (sessionIds: string[]) => void;
+  saveActiveSessionId: (sessionId: string) => Promise<void>;
+  /**
+   * The legacy `validateSession`-keyed switch. Reachable from exactly ONE
+   * caller: `performSignIn`'s same-user duplicate-session dedup. The switch a
+   * consumer sees on the context is the `SessionClient` one in `OxyContext`.
+   */
   switchSession: (sessionId: string) => Promise<User>;
-  refreshSessions: (activeUserId?: string) => Promise<void>;
+  /** Tear down the local session: runtime projection, caches, storage, tokens. */
   clearSessionState: () => Promise<void>;
-  saveActiveSessionId: (sessionId: string) => Promise<void>;
-  trackRemovedSession: (sessionId: string) => void;
   storageKeys: ReturnType<typeof getStorageKeys>;
-  isRefreshInFlight: boolean;
 }
 
 const DEFAULT_SAVE_ERROR_MESSAGE = 'Failed to save session data';
 const CLEAR_STORAGE_ERROR = 'Failed to clear storage';
 
 /**
- * Manage session state, persistence, and high-level multi-session operations.
+ * Session persistence and the one legacy switch left, over the runtime.
  *
- * @param options - Session management configuration
+ * This hook used to hold its OWN `sessions` / `activeSessionId` React state
+ * plus six refs mirroring them so its callbacks could avoid widening their
+ * dependency arrays. That made it a second owner of facts `SessionClient`
+ * already had, reconciled only by whichever `useEffect` ran last. Both are gone:
+ * the runtime owns them, this hook writes through it, and the refs mirrored
+ * nothing once there was nothing local to mirror.
+ *
+ * `refreshSessions`, `trackRemovedSession` and `isRefreshInFlight` are deleted
+ * outright — every one of them was dropped unread at the single call site.
  */
 export const useSessionManagement = ({
   oxyServices,
+  runtime,
   storage,
   storageKeyPrefix,
-  loginSuccess,
-  logoutStore,
   onAuthStateChange,
   onError,
   setAuthError,
   logger,
-  setTokenReady,
   queryClient,
 }: UseSessionManagementOptions): UseSessionManagementResult => {
-  const [sessions, setSessions] = useState<ClientSession[]>([]);
-  const [activeSessionId, setActiveSessionId] = useState<string | null>(null);
-
-  // Refs to avoid recreating callbacks when sessions/activeSessionId change
-  const sessionsRef = useRef(sessions);
-  sessionsRef.current = sessions;
-  const activeSessionIdRef = useRef(activeSessionId);
-  activeSessionIdRef.current = activeSessionId;
-
-  const refreshInFlightRef = useRef<Promise<void> | null>(null);
-  const removedSessionsRef = useRef<Set<string>>(new Set());
-  const lastRefreshRef = useRef<number>(0);
-
   const storageKeys = useMemo(() => getStorageKeys(storageKeyPrefix), [storageKeyPrefix]);
+  const runtimeRef = useRef(runtime);
+  runtimeRef.current = runtime;
 
   const saveSessionIds = useCallback(
-    async (sessionIds: string[]): Promise<void> => {
+    (sessionIds: string[]): void => {
       if (!storage) return;
-      try {
-        const uniqueIds = Array.from(new Set(sessionIds));
-        await storage.setItem(storageKeys.sessionIds, JSON.stringify(uniqueIds));
-      } catch (error) {
+      const uniqueIds = Array.from(new Set(sessionIds));
+      storage.setItem(storageKeys.sessionIds, JSON.stringify(uniqueIds)).catch((error: unknown) => {
         if (logger) {
           logger(DEFAULT_SAVE_ERROR_MESSAGE, error);
         } else if (isDev()) {
           console.warn('Failed to save session IDs:', error);
         }
-      }
-    },
-    [logger, storage, storageKeys.sessionIds],
-  );
-
-  const updateSessions = useCallback(
-    (incoming: ClientSession[], options: { merge?: boolean; preserveSessionIds?: string[] } = {}): void => {
-      setSessions((prevSessions) => {
-        const processed = options.merge
-          ? mergeSessions(prevSessions, incoming, activeSessionIdRef.current, false)
-          : normalizeAndSortSessions(incoming, activeSessionIdRef.current, false);
-
-        if (storage) {
-          void saveSessionIds([
-            ...processed.map((session) => session.sessionId),
-            ...(options.preserveSessionIds ?? []),
-          ]);
-        }
-
-        if (sessionsArraysEqual(prevSessions, processed)) {
-          return prevSessions;
-        }
-        return processed;
       });
     },
-    [saveSessionIds, storage],
+    [logger, storage, storageKeys.sessionIds],
   );
 
   const saveActiveSessionId = useCallback(
@@ -133,27 +103,11 @@ export const useSessionManagement = ({
     [logger, onError, setAuthError, storage, storageKeys.activeSessionId],
   );
 
-  const removeActiveSessionId = useCallback(async (): Promise<void> => {
-    if (!storage) return;
-    try {
-      await storage.removeItem(storageKeys.activeSessionId);
-    } catch (error) {
-      handleAuthError(error, {
-        defaultMessage: DEFAULT_SAVE_ERROR_MESSAGE,
-        code: 'SESSION_PERSISTENCE_ERROR',
-        onError,
-        setAuthError,
-        logger,
-      });
-    }
-  }, [logger, onError, setAuthError, storage, storageKeys.activeSessionId]);
-
   const clearSessionStorage = useCallback(async (): Promise<void> => {
     if (!storage) return;
     try {
       await storage.removeItem(storageKeys.activeSessionId);
       await storage.removeItem(storageKeys.sessionIds);
-      // Note: Identity sync state ('oxy_identity_synced') is managed by accounts app
     } catch (error) {
       handleAuthError(error, {
         defaultMessage: CLEAR_STORAGE_ERROR,
@@ -166,25 +120,21 @@ export const useSessionManagement = ({
   }, [logger, onError, setAuthError, storage, storageKeys.activeSessionId, storageKeys.sessionIds]);
 
   const clearSessionState = useCallback(async (): Promise<void> => {
-    setSessions([]);
-    setActiveSessionId(null);
-    logoutStore();
+    runtimeRef.current.clearSession();
     resetSessionScopedStores();
 
-    // Clear the access token on the client instance. Without this the
-    // TokenStore retained the stale bearer until the next 401, leaving the
-    // instance "logged in" at the HTTP layer and — via OxyProvider's
-    // token-change mirror — leaking that stale token onto the shared
-    // `oxyClient` singleton after sign-out. Clearing here fires
-    // `onTokensChanged(null)`, propagating the logged-out state everywhere.
+    // Clear the access token on the client instance. Without this the token
+    // store retained the stale bearer until the next 401, leaving the instance
+    // "logged in" at the HTTP layer and — via the provider's token mirror —
+    // leaking that stale token onto the shared `oxyClient` singleton after
+    // sign-out. Clearing here fires `onTokensChanged(null)`, propagating the
+    // logged-out state everywhere.
     oxyServices.clearTokens();
 
-    // Clear TanStack Query cache (in-memory)
     if (queryClient) {
       queryClient.clear();
     }
-    
-    // Clear persisted query cache
+
     if (storage) {
       try {
         await clearQueryCache(storage);
@@ -194,49 +144,19 @@ export const useSessionManagement = ({
         }
       }
     }
-    
+
     await clearSessionStorage();
     onAuthStateChange?.(null);
-  }, [clearSessionStorage, logoutStore, onAuthStateChange, oxyServices, queryClient, storage, logger]);
-
-  const activateSession = useCallback(
-    async (sessionId: string, user: User): Promise<void> => {
-      setTokenReady?.(true);
-      setActiveSessionId(sessionId);
-      loginSuccess(user);
-      await saveActiveSessionId(sessionId);
-      onAuthStateChange?.(user);
-    },
-    [loginSuccess, onAuthStateChange, saveActiveSessionId, setTokenReady],
-  );
-
-  const removalTimerIdsRef = useRef<Set<ReturnType<typeof setTimeout>>>(new Set());
-
-  const trackRemovedSession = useCallback((sessionId: string) => {
-    removedSessionsRef.current.add(sessionId);
-    const timerId = setTimeout(() => {
-      removedSessionsRef.current.delete(sessionId);
-      removalTimerIdsRef.current.delete(timerId);
-    }, 5000);
-    removalTimerIdsRef.current.add(timerId);
-  }, []);
-
-  useEffect(() => {
-    return () => {
-      removalTimerIdsRef.current.forEach(clearTimeout);
-    };
-  }, []);
+  }, [clearSessionStorage, onAuthStateChange, oxyServices, queryClient, storage, logger]);
 
   const switchSession = useCallback(
     async (sessionId: string): Promise<User> => {
       try {
-        // On web, the bearer must already be in memory (planted by
-        // `claimSessionByToken`, a cold-boot silent-restore step, or a prior
+        // On web the bearer must already be in memory (planted by
+        // `claimSessionByToken`, a cold-boot restore step, or a prior
         // `SessionClient` sync) before validating — there is no client-side
-        // `oxy_rt` refresh-cookie slot to fall back on; the device account SET
-        // is server-authoritative via `SessionClient` now. The native path
-        // arrives here only after a bearer has been planted by
-        // `claimSessionByToken` or secure shared-session restore.
+        // refresh-cookie slot to fall back on. The native path arrives here only
+        // after a bearer has been planted too.
         if (isWebBrowser() && !oxyServices.getAccessToken()) {
           throw new Error('Session is invalid or expired');
         }
@@ -245,20 +165,26 @@ export const useSessionManagement = ({
         if (!validation?.valid) {
           throw new Error('Session is invalid or expired');
         }
-
         if (!validation.user) {
           throw new Error('User data not available from session validation');
         }
 
         const user = validation.user as User;
-        await activateSession(sessionId, user);
+        const activeRuntime = runtimeRef.current;
+        activeRuntime.batch(() => {
+          activeRuntime.setTokenReady(true);
+          activeRuntime.setActiveSessionId(sessionId);
+          activeRuntime.setAccount(user);
+        });
+        await saveActiveSessionId(sessionId);
+        onAuthStateChange?.(user);
 
         try {
           const deviceSessions = await fetchSessionsWithFallback(oxyServices, sessionId, {
             fallbackUserId: user.id,
             logger,
           });
-          updateSessions(deviceSessions, { merge: true });
+          activeRuntime.mergeSessions(deviceSessions, { merge: true });
         } catch (error) {
           if (isDev()) {
             console.warn('Failed to synchronize sessions after switch:', error);
@@ -271,11 +197,12 @@ export const useSessionManagement = ({
 
         if (invalidSession) {
           // Server authority (`SessionClient` bootstrap/sync) reconciles which
-          // account is actually active — just drop the invalid session from
-          // the local view rather than guessing at a replacement.
-          updateSessions(sessionsRef.current.filter((session) => session.sessionId !== sessionId), {
-            merge: false,
-          });
+          // account is actually active — just drop the invalid session from the
+          // local view rather than guessing at a replacement.
+          const remaining: ClientSession[] = runtimeRef.current
+            .getSnapshot()
+            .sessions.filter((session) => session.sessionId !== sessionId);
+          runtimeRef.current.mergeSessions(remaining, { merge: false });
         }
 
         handleAuthError(error, {
@@ -288,90 +215,14 @@ export const useSessionManagement = ({
         throw error instanceof Error ? error : new Error('Failed to switch session');
       }
     },
-    [
-      activateSession,
-      logger,
-      onError,
-      oxyServices,
-      setAuthError,
-      updateSessions,
-    ],
-  );
-
-  const refreshSessions = useCallback(
-    async (activeUserId?: string): Promise<void> => {
-      // Capture the active session id once so the async closure below uses a
-      // narrowed, non-null local instead of re-reading the ref (which the
-      // compiler cannot prove stays non-null across awaits).
-      const activeSessionId = activeSessionIdRef.current;
-      if (!activeSessionId) return;
-
-      if (refreshInFlightRef.current) {
-        await refreshInFlightRef.current;
-        return;
-      }
-
-      const now = Date.now();
-      if (now - lastRefreshRef.current < 500) {
-        return;
-      }
-      lastRefreshRef.current = now;
-
-      const refreshPromise = (async () => {
-        try {
-          const deviceSessions = await fetchSessionsWithFallback(oxyServices, activeSessionId, {
-            fallbackUserId: activeUserId,
-            logger,
-          });
-          updateSessions(deviceSessions, { merge: true });
-        } catch (error) {
-          if (isInvalidSessionError(error)) {
-            // Server authority (`SessionClient` bootstrap/sync) reconciles
-            // which account is actually active — just clear local state
-            // rather than guessing at a replacement session.
-            await clearSessionState();
-            return;
-          }
-
-          handleAuthError(error, {
-            defaultMessage: 'Failed to refresh sessions',
-            code: 'SESSION_REFRESH_ERROR',
-            onError,
-            setAuthError,
-            logger,
-          });
-        } finally {
-          refreshInFlightRef.current = null;
-          lastRefreshRef.current = Date.now();
-        }
-      })();
-
-      refreshInFlightRef.current = refreshPromise;
-      await refreshPromise;
-    },
-    [
-      clearSessionState,
-      logger,
-      onError,
-      oxyServices,
-      setAuthError,
-      updateSessions,
-    ],
+    [logger, onAuthStateChange, onError, oxyServices, saveActiveSessionId, setAuthError],
   );
 
-  const isRefreshInFlight = Boolean(refreshInFlightRef.current);
-
   return {
-    sessions,
-    activeSessionId,
-    setActiveSessionId,
-    updateSessions,
+    saveSessionIds,
+    saveActiveSessionId,
     switchSession,
-    refreshSessions,
     clearSessionState,
-    saveActiveSessionId,
-    trackRemovedSession,
     storageKeys,
-    isRefreshInFlight,
   };
 };

package/src/ui/index.ts

@@ -29,7 +29,7 @@ export { default as OxyPayButton } from './components/OxyPayButton';
 export { default as ProfileButton } from './components/ProfileButton';
 
 // Context + hooks
-export { useOxy } from './context/OxyContext';
+export { useOxy, useOptionalOxy, OxyProviderMissingError } from './context/OxyContext';
 export { useAuth } from './hooks/useAuth';
 export { useFollow, useSeedFollowStatuses } from './hooks/useFollow';
 export { useStorage } from './hooks/useStorage';
@@ -44,7 +44,6 @@ export { default as AccountSettingsScreen } from './screens/AccountSettingsScree
 
 // Stores
 export { useAuthStore } from './stores/authStore';
-export { useAccountStore } from './stores/accountStore';
 
 // Error handlers (pure functions)
 export {

package/src/ui/navigation/routes.ts

@@ -1,10 +1,6 @@
-import type { ComponentType } from 'react';
+import { lazy, type ComponentType } from 'react';
 import type { BaseScreenProps } from '../types/navigation';
 
-// Lazy loading: Screens are loaded on-demand to break require cycles
-// This prevents screens (which import OxyContext) from being loaded
-// before OxyContext is fully initialized
-
 // Define all available route names
 export type RouteName =
     | 'ManageAccount'    // Unified "Manage your Oxy Account" surface
@@ -46,85 +42,99 @@ export type RouteName =
     | 'Preferences' // General user preferences (theme, reduce-motion, etc.)
     | 'AccountDialog'; // Unified account switcher + sign-in surface (OxyAccountDialogScreen body)
 
-// Lazy screen loaders - functions that return screen components on-demand
-// This breaks the require cycle by deferring imports until screens are actually needed
-const screenLoaders: Record<RouteName, () => ComponentType<BaseScreenProps>> = {
-    ManageAccount: () => require('../screens/ManageAccountScreen').default,
-    AccountVerification: () => require('../screens/AccountVerificationScreen').default,
-    PaymentGateway: () => require('../screens/PaymentGatewayScreen').default,
-    Profile: () => require('../screens/ProfileScreen').default,
-    LanguageSelector: () => require('../screens/LanguageSelectorScreen').default,
-    PrivacySettings: () => require('../screens/PrivacySettingsScreen').default,
-    SearchSettings: () => require('../screens/SearchSettingsScreen').default,
-    FileManagement: () => require('../screens/FileManagementScreen').default,
-    HelpSupport: () => require('../screens/HelpSupportScreen').default,
-    FAQ: () => require('../screens/FAQScreen').default,
-    Feedback: () => require('../screens/FeedbackScreen').default,
-    LegalDocuments: () => require('../screens/LegalDocumentsScreen').default,
-    AppInfo: () => require('../screens/AppInfoScreen').default,
-    PremiumSubscription: () => require('../screens/PremiumSubscriptionScreen').default,
-    WelcomeNewUser: () => require('../screens/WelcomeNewUserScreen').default,
-    UserLinks: () => require('../screens/UserLinksScreen').default,
-    HistoryView: () => require('../screens/HistoryViewScreen').default,
-    SavesCollections: () => require('../screens/SavesCollectionsScreen').default,
-    EditProfile: () => require('../screens/EditProfileScreen').default,
-    EditProfileField: () => require('../screens/EditProfileFieldScreen').default,
+/**
+ * The component for each route, loaded on demand.
+ *
+ * Every entry is `lazy(() => import(...))`: the screen module is fetched and
+ * evaluated the first time its surface is presented, never at import time. That
+ * matters twice over — screens import `OxyContext`, which reaches back here, so
+ * eager evaluation would run screens mid-cycle; and it keeps native-only screen
+ * dependencies out of the evaluation path of every consumer that merely touches
+ * the SDK.
+ *
+ * What defers the load must NOT be `require()`. `@oxyhq/services` ships an ESM
+ * build, and a `require()` in ESM output forces web bundlers into CommonJS
+ * interop: rolldown-vite defers every module in the required subgraph behind a
+ * lazy initializer and then hands a consumer that statically imported one of
+ * them the still-`undefined` binding. That is how `OxySignInRequestSurface`
+ * reached auth.oxy.so/authorize as `undefined` and blanked the page with React
+ * error #130 — this registry pulled `OxyAccountDialogScreen`, and the whole
+ * sign-in surface subgraph with it, through `require()`.
+ *
+ * The value type is `ComponentType<never>`, which every screen satisfies. A few
+ * screens (`Profile`, `PaymentGateway`, `UserLinks`, `FollowersList`,
+ * `FollowingList`) declare props BEYOND {@link BaseScreenProps} — `userId`,
+ * `amount` — that only reach them through the route's untyped props bag
+ * (`present(route, props)`), so this map cannot prove they are satisfied. The
+ * previous `require()` returned `any` and hid that entirely; stating it here
+ * confines the gap to one documented widening in {@link getScreenComponent}.
+ */
+const screenComponents: Record<RouteName, ComponentType<never>> = {
+    ManageAccount: lazy(() => import('../screens/ManageAccountScreen')),
+    AccountVerification: lazy(() => import('../screens/AccountVerificationScreen')),
+    PaymentGateway: lazy(() => import('../screens/PaymentGatewayScreen')),
+    Profile: lazy(() => import('../screens/ProfileScreen')),
+    LanguageSelector: lazy(() => import('../screens/LanguageSelectorScreen')),
+    PrivacySettings: lazy(() => import('../screens/PrivacySettingsScreen')),
+    SearchSettings: lazy(() => import('../screens/SearchSettingsScreen')),
+    FileManagement: lazy(() => import('../screens/FileManagementScreen')),
+    HelpSupport: lazy(() => import('../screens/HelpSupportScreen')),
+    FAQ: lazy(() => import('../screens/FAQScreen')),
+    Feedback: lazy(() => import('../screens/FeedbackScreen')),
+    LegalDocuments: lazy(() => import('../screens/LegalDocumentsScreen')),
+    AppInfo: lazy(() => import('../screens/AppInfoScreen')),
+    PremiumSubscription: lazy(() => import('../screens/PremiumSubscriptionScreen')),
+    WelcomeNewUser: lazy(() => import('../screens/WelcomeNewUserScreen')),
+    UserLinks: lazy(() => import('../screens/UserLinksScreen')),
+    HistoryView: lazy(() => import('../screens/HistoryViewScreen')),
+    SavesCollections: lazy(() => import('../screens/SavesCollectionsScreen')),
+    EditProfile: lazy(() => import('../screens/EditProfileScreen')),
+    EditProfileField: lazy(() => import('../screens/EditProfileFieldScreen')),
     // Informational screens
-    LearnMoreUsernames: () => require('../screens/LearnMoreUsernamesScreen').default,
+    LearnMoreUsernames: lazy(() => import('../screens/LearnMoreUsernamesScreen')),
     // Oxy Trust screens
-    TrustCenter: () => require('../screens/trust/TrustCenterScreen').default,
-    TrustLeaderboard: () => require('../screens/trust/TrustLeaderboardScreen').default,
-    TrustRewards: () => require('../screens/trust/TrustRewardsScreen').default,
-    TrustRules: () => require('../screens/trust/TrustRulesScreen').default,
-    AboutTrust: () => require('../screens/trust/TrustAboutScreen').default,
-    TrustFAQ: () => require('../screens/trust/TrustFAQScreen').default,
+    TrustCenter: lazy(() => import('../screens/trust/TrustCenterScreen')),
+    TrustLeaderboard: lazy(() => import('../screens/trust/TrustLeaderboardScreen')),
+    TrustRewards: lazy(() => import('../screens/trust/TrustRewardsScreen')),
+    TrustRules: lazy(() => import('../screens/trust/TrustRulesScreen')),
+    AboutTrust: lazy(() => import('../screens/trust/TrustAboutScreen')),
+    TrustFAQ: lazy(() => import('../screens/trust/TrustFAQScreen')),
     // User list screens (followers/following)
-    FollowersList: () => require('../screens/FollowersListScreen').default,
-    FollowingList: () => require('../screens/FollowingListScreen').default,
-    CreateAccount: () => require('../screens/CreateAccountScreen').default,
-    AccountMembers: () => require('../screens/AccountMembersScreen').default,
-    AccountSettings: () => require('../screens/AccountSettingsScreen').default,
-    ChangeAvatar: () => require('../screens/ChangeAvatarScreen').default,
-    AvatarCrop: () => require('../screens/AvatarCropScreen').default,
-    Notifications: () => require('../screens/NotificationsScreen').default,
-    ConnectedApps: () => require('../screens/ConnectedAppsScreen').default,
-    Preferences: () => require('../screens/PreferencesScreen').default,
+    FollowersList: lazy(() => import('../screens/FollowersListScreen')),
+    FollowingList: lazy(() => import('../screens/FollowingListScreen')),
+    CreateAccount: lazy(() => import('../screens/CreateAccountScreen')),
+    AccountMembers: lazy(() => import('../screens/AccountMembersScreen')),
+    AccountSettings: lazy(() => import('../screens/AccountSettingsScreen')),
+    ChangeAvatar: lazy(() => import('../screens/ChangeAvatarScreen')),
+    AvatarCrop: lazy(() => import('../screens/AvatarCropScreen')),
+    Notifications: lazy(() => import('../screens/NotificationsScreen')),
+    ConnectedApps: lazy(() => import('../screens/ConnectedAppsScreen')),
+    Preferences: lazy(() => import('../screens/PreferencesScreen')),
     // Unified account switcher + sign-in surface. Its body lives in the
     // `OxyAccountDialogScreen` component (folded from the standalone dialog); the
     // surface stack provides the Dialog chrome around it.
-    AccountDialog: () => require('../components/OxyAccountDialogScreen').default,
+    AccountDialog: lazy(() => import('../components/OxyAccountDialogScreen')),
 };
 
-// Cache loaded components to avoid re-requiring
-const screenCache = new Map<RouteName, ComponentType<BaseScreenProps>>();
-
-// Helper function to get a screen component by route name (lazy loaded)
-export const getScreenComponent = (routeName: RouteName): ComponentType<BaseScreenProps> | undefined => {
-    // Return cached component if available
-    if (screenCache.has(routeName)) {
-        return screenCache.get(routeName);
-    }
-
-    // Lazy load the component
-    const loader = screenLoaders[routeName];
-    if (loader) {
-        try {
-            const component = loader();
-            screenCache.set(routeName, component);
-            return component;
-        } catch (error) {
-            if (__DEV__) {
-                console.error(`[Routes] Failed to load screen: ${routeName}`, error);
-            }
-            return undefined;
-        }
-    }
-
-    return undefined;
-};
+/**
+ * Resolve the component for a route.
+ *
+ * The map is total over {@link RouteName} — the compiler enforces that at its
+ * declaration — so this returns `undefined` only for a caller that reached here
+ * with an unchecked string; {@link isValidRoute} is how such a caller narrows.
+ *
+ * The surface host renders the result with {@link BaseScreenProps} merged with
+ * the route's own props bag, so that is the type it is handed back as. This one
+ * widening is where the gap documented on {@link screenComponents} lives: the map
+ * dispatches on a string key, so a screen's extra prop requirements are met at
+ * `present(route, props)` call sites, not provable here. No caching is needed —
+ * React memoizes each `lazy()` component's module after its first load.
+ */
+export const getScreenComponent = (routeName: RouteName): ComponentType<BaseScreenProps> | undefined =>
+    screenComponents[routeName] as ComponentType<BaseScreenProps>;
 
 // Helper function to check if a route exists
-// Uses the screenLoaders object to check existence without loading the screen
+// Uses the screenComponents map to check existence without loading the screen
 export const isValidRoute = (routeName: string): routeName is RouteName => {
-    return routeName in screenLoaders;
+    return routeName in screenComponents;
 };

package/src/ui/navigation/surfaces.ts

@@ -13,6 +13,7 @@ import {
   type SurfaceRouteConfig,
 } from './surfaceRegistry';
 import { createSurfaceNavStack, type SurfaceNavStack } from './surfaceNavStack';
+import SurfaceScreen from '../components/SurfaceScreen';
 
 /**
  * The SDK's typed surface API — a route registry layered on top of Bloom's
@@ -153,15 +154,11 @@ function presentInternal<K extends RouteName>(
   const config = getSurfaceConfig(route, props);
   const bloomOpts: PresentOptions = { label: route, ...bloomOptionsFor(config), ...opts };
 
-  // Lazy-resolved to break the surfaces.ts <-> SurfaceScreen module cycle: a
-  // mounted SurfaceScreen presents further surfaces (it imports these presenters),
-  // while presenting one renders a SurfaceScreen. Deferring the component to call
-  // time (both modules are initialized by then) makes the import graph one-way —
-  // the same idiom `routes.ts` uses to lazy-load screen components.
-  const SurfaceScreen = (
-    require('../components/SurfaceScreen') as typeof import('../components/SurfaceScreen')
-  ).default;
-
+  // `SurfaceScreen` is statically imported but only READ here, at presentation
+  // time. That keeps the surfaces.ts <-> SurfaceScreen cycle safe (a mounted
+  // SurfaceScreen imports these presenters, while presenting one renders a
+  // SurfaceScreen) without a `require()` — which ESM output must never contain,
+  // see the note on `screenComponents` in `./routes`.
   const result = bloomSurfaces.present<SurfaceResult<K>>((surface: SurfaceControls) =>
     createElement(SurfaceScreen, {
       navStack,