@oxyhq/services 11.1.0 → 12.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/services",
-  "version": "11.1.0",
+  "version": "12.0.0",
   "description": "OxyHQ Expo/React Native SDK — UI components, screens, and native features",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -106,7 +106,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.3.0"
+    "@oxyhq/contracts": "0.4.0"
   },
   "devDependencies": {
     "nativewind": "5.0.0-preview.3",
@@ -152,7 +152,7 @@
   "peerDependencies": {
     "@expo/vector-icons": "^15.0.3",
     "@oxyhq/bloom": ">=0.16.0",
-    "@oxyhq/core": "^3.11.0",
+    "@oxyhq/core": "^3.15.0",
     "@react-native-async-storage/async-storage": "^2.0.0",
     "@react-native-community/netinfo": "^11.4.1",
     "@tanstack/query-async-storage-persister": "^5.100",

package/src/index.ts

@@ -21,6 +21,8 @@
  * ```
  */
 
+/// <reference path="./types/react-native-classname.d.ts" />
+
 import { setPlatformOS, type PlatformOS } from '@oxyhq/core';
 import { Platform } from 'react-native';
 setPlatformOS(Platform.OS as PlatformOS);
@@ -166,6 +168,7 @@ export {
 // Mutation status aggregator (for "Syncing..." indicators)
 export { useMutationStatus } from './ui/hooks/useMutationStatus';
 export type { MutationStatus } from './ui/hooks/useMutationStatus';
+export { useOnlineStatus } from './ui/hooks/useOnlineStatus';
 
 // ---------------------------------------------------------------------------
 // Error handlers

package/src/types/react-native-classname.d.ts

@@ -0,0 +1,39 @@
+// Robust NativeWind className typings for React Native's `ScrollView` & `FlatList`.
+//
+// NativeWind 5's engine (`react-native-css`) augments `ScrollViewProps` and
+// `FlatListProps` with className props, but its declarations carry heritage
+// clauses (`interface ScrollViewProps extends ViewProps, ScrollViewPropsIOS, …`)
+// and route `FlatList`'s `contentContainerClassName` through a deep
+// `@react-native/virtualized-lists` → `ScrollViewProps` augmentation. Under
+// React Native 0.85 that heritage no longer matches, and the nested
+// `@react-native/virtualized-lists` copy does not resolve from a CONSUMER's
+// `node_modules` — so when this package's source is type-checked through the
+// `react-native` export condition (which resolves `@oxyhq/services` to raw
+// `src/`), those className members silently drop and consumer `tsc` fails with
+// TS2769 on screens that use `contentContainerClassName` (e.g.
+// ManageAccountScreen, ConnectedAppsScreen).
+//
+// These heritage-free augmentations add the className props directly to the two
+// interfaces, so resolution never depends on the deep virtualized-lists copy or
+// on react-native-css's heritage clauses. The plain `import 'react-native'`
+// makes this a module so the `declare module` is treated as an augmentation
+// (merge) rather than a redeclaration. Consumers load it via the
+// `/// <reference path>` directives in `src/index.ts` and `src/ui/index.ts`.
+
+import 'react-native';
+
+declare module 'react-native' {
+  interface ScrollViewProps {
+    className?: string;
+    contentContainerClassName?: string;
+    indicatorClassName?: string;
+  }
+
+  interface FlatListProps<ItemT> {
+    className?: string;
+    contentContainerClassName?: string;
+    columnWrapperClassName?: string;
+    ListHeaderComponentClassName?: string;
+    ListFooterComponentClassName?: string;
+  }
+}

package/src/ui/components/OxyLogo.tsx

@@ -52,7 +52,7 @@ const IconLogo: React.FC<{ size: number; style?: ViewStyle; primary: string; inn
                 />
                 <Path
                     d="M342.19 891.70425c-34.34375 2.53125-64.8125-3.85547-91.40625-19.15625-26.59375-15.3125-49.26172-36.85156-68-64.625-18.73047-27.78125-33.58594-60.5039-44.5625-98.17188-10.96875-37.67578-18.0039-77.625-21.10938-119.84375-2.89453-39.40625-1.46874-79.6953 4.28126-120.875 5.75-41.17578 16.42578-78.75 32.03124-112.71875 15.61329-33.97656 36.44532-62.39453 62.5-85.25 26.05079-22.85156 58.21875-35.6875 96.5-38.5 37.14454-2.72656 68.97657 4.98047 95.5 23.125 26.51954 18.13672 48.40625 42.5625 65.65625 73.28126 17.25782 30.71093 30.57032 65.53125 39.9375 104.46875 9.375 38.92968 15.50782 78.09375 18.40626 117.5 3.22656 43.90625 1.91406 85.74609-3.9375 125.51562-5.84375 39.76172-16.53907 75.21094-32.07813 106.34375-15.54297 31.13672-36.04297 56.41406-61.5 75.82813-25.44922 19.40625-56.1875 30.42968-92.21875 33.07812zm-24.5-471.89063c-10.69922.78125-19.53906 5.67188-26.51563 14.67188-6.98046 8.99219-12.49609 20.57031-16.54687 34.73438-4.04297 14.16796-6.5625 29.92187-7.5625 47.26562-.99219 17.33594-.84375 34.73047.4375 52.1875 1.44531 19.69922 4.16016 39.30469 8.14063 58.8125 3.98828 19.51172 9.09375 36.96484 15.3125 52.35938 6.22656 15.39843 13.49218 27.60156 21.79687 36.60937 8.30078 9 17.80078 13.10938 28.5 12.32813 12.38281-.91407 21.78125-7.83204 28.1875-20.75 6.40625-12.91407 11.07813-28.25391 14.01563-46.01563 2.9453-17.75781 4.4414-35.97656 4.48437-54.65625.03906-18.6875-.39844-34.21875-1.3125-46.59375-1.11719-15.19531-3.28125-31.17188-6.5-47.92188-3.21094-16.75-7.59375-32.1328-13.15625-46.15625-5.55469-14.01953-12.33984-25.54687-20.35938-34.57812-8.02343-9.03125-17.66406-13.1289-28.92187-12.29688z"
-                    fill="#ffffff"
+                    fill={inner}
                 />
             </G>
         </G>

package/src/ui/components/OxyProvider.tsx

@@ -113,7 +113,6 @@ const OxyProvider: FC<OxyProviderProps> = ({
     baseURL,
     authWebUrl,
     authRedirectUri,
-    disableAutoSso,
     queryClient: providedQueryClient,
 }) => {
 
@@ -309,7 +308,6 @@ const OxyProvider: FC<OxyProviderProps> = ({
                     authRedirectUri={authRedirectUri}
                     storageKeyPrefix={storageKeyPrefix}
                     clientId={clientId}
-                    disableAutoSso={disableAutoSso}
                     onAuthStateChange={onAuthStateChange as OxyContextProviderProps['onAuthStateChange']}
                 >
                     {children}

package/src/ui/context/OxyContext.tsx

@@ -28,6 +28,7 @@ import {
   ssoAttemptedKey,
   isCentralIdPOrigin,
   guardActive,
+  allowSsoBounce,
   ssoNavigate,
   buildSsoBounceUrl,
   consumeSsoReturn,
@@ -196,16 +197,6 @@ export interface OxyContextProviderProps {
    * for the cross-app device sign-in flow. See {@link OxyContextState.clientId}.
    */
   clientId?: string;
-  /**
-   * When `true`, skips ONLY the terminal `sso-bounce` cold-boot step — the
-   * force-redirect to `auth.<apex>/sso?prompt=none` that fires for a visitor
-   * with no recoverable local session. Every other cold-boot step still runs
-   * (callback consume, FedCM silent, `/auth/silent` iframe, stored-session,
-   * cookie-restore), so a returning signed-in user is still silently
-   * restored; only the bounce for a truly anonymous visitor is suppressed.
-   * Default `false`.
-   */
-  disableAutoSso?: boolean;
   onAuthStateChange?: (user: User | null) => void;
   onError?: (error: ApiError) => void;
 }
@@ -462,7 +453,6 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   authRedirectUri,
   storageKeyPrefix = 'oxy_session',
   clientId: clientIdProp,
-  disableAutoSso = false,
   onAuthStateChange,
   onError,
 }) => {
@@ -631,6 +621,25 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     return storageReady.promise;
   }, [storageReady]);
 
+  // Clear the durable "had a signed-in Oxy session before" hint.
+  //
+  // The hint (`storageKeys.priorSession`) is WRITTEN whenever a session is
+  // established/restored — every commit funnels through `persistSessionDurably`,
+  // and the stored-session reload winner sets it directly to backfill
+  // pre-existing installs. It lives in the SAME `storageKeyPrefix`-scoped
+  // durable store as the session ids, so it SURVIVES a session expiring; it is
+  // cleared ONLY here, on EXPLICIT full sign-out (wired into `clearAllAccountData`
+  // and the `useAuthOperations` logout paths — never the passive token-expiry
+  // path). At cold boot the hint is read into `hadPriorSession` and feeds
+  // `allowSsoBounce`: a RETURNING visitor (hint present) whose local session has
+  // lapsed still gets ONE terminal `/sso` establish bounce so a central-only
+  // cross-domain session recovers, while a truly first-time anonymous visitor is
+  // never force-redirected.
+  const clearPriorSessionHint = useCallback(async (): Promise<void> => {
+    const readyStorage = await getReadyStorage();
+    await readyStorage.removeItem(storageKeys.priorSession);
+  }, [getReadyStorage, storageKeys.priorSession]);
+
   useEffect(() => {
     let mounted = true;
     createPlatformStorage()
@@ -717,6 +726,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     updateSessions,
     saveActiveSessionId,
     clearSessionState,
+    clearPriorSessionHint,
     switchSession,
     applyLanguagePreference,
     onAuthStateChange,
@@ -745,12 +755,18 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     // Clear session state (sessions, activeSessionId, storage)
     await clearSessionState();
 
+    // Explicit FULL sign-out: drop the durable returning-user hint so the next
+    // cold boot treats this device as a first-time anonymous visitor (no forced
+    // `/sso` bounce). NOT done on the passive token-expiry path, so an expired
+    // session still recovers via a returning-user bounce.
+    await clearPriorSessionHint();
+
     // Reset account store
     useAccountStore.getState().reset();
 
     // Clear HTTP service cache
     oxyServices.clearCache();
-  }, [queryClient, storage, clearSessionState, logger, oxyServices]);
+  }, [queryClient, storage, clearSessionState, clearPriorSessionHint, logger, oxyServices]);
 
   const { getDeviceSessions, logoutAllDeviceSessions, updateDeviceName } = useDeviceManagement({
     oxyServices,
@@ -831,7 +847,13 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       sessionIds.push(sessionId);
       await readyStorage.setItem(storageKeys.sessionIds, JSON.stringify(sessionIds));
     }
-  }, [getReadyStorage, logger, storageKeys.activeSessionId, storageKeys.sessionIds]);
+    // A session is now durably committed — set the returning-user hint so a
+    // future cold boot whose local session has lapsed still gets ONE `/sso`
+    // establish bounce (see `markPriorSessionHint`). Every web commit path
+    // (FedCM / silent iframe / SSO return / password / cookie restore) funnels
+    // through here, so this is the single chokepoint for the hint.
+    await readyStorage.setItem(storageKeys.priorSession, '1');
+  }, [getReadyStorage, logger, storageKeys.activeSessionId, storageKeys.sessionIds, storageKeys.priorSession]);
 
   // Refs so the cold-boot restore can plant session state without widening its
   // dependency array (mirrors the existing ref pattern above).
@@ -1073,6 +1095,12 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
         // immediately so the loading screen clears without waiting for the
         // remaining cold-boot steps to be evaluated/short-circuited (idempotent).
         markAuthResolvedRef.current();
+        // Backfill the returning-user hint. A reload winner already had the hint
+        // set at original sign-in, but pre-existing installs (signed in before
+        // this hint shipped) get it set here so their NEXT lapse-and-return still
+        // earns one `/sso` establish bounce. `storage` is non-null (guarded at
+        // the top of this callback); best-effort, never blocks restore.
+        await storage.setItem(storageKeys.priorSession, '1');
         return true;
       } catch (switchError) {
         // Silently handle expected errors (invalid sessions, timeouts, network issues)
@@ -1102,6 +1130,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     storage,
     storageKeys.activeSessionId,
     storageKeys.sessionIds,
+    storageKeys.priorSession,
   ]);
 
   // Shared in-flight `runSsoReturn` promise — see the CONCURRENCY note on
@@ -1213,6 +1242,27 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     // `stored-session` skips, this stays false, and the probes run as before.
     let storedSessionRestored = false;
 
+    // FIX-B smart-gate input: has this device/app EVER had a signed-in Oxy
+    // session (the durable `priorSession` hint, set on every commit, cleared
+    // only on explicit full sign-out)? Read ONCE here — synchronously usable by
+    // the terminal `sso-bounce` `enabled` gate below — so a RETURNING visitor
+    // whose local session has lapsed still earns one `/sso` establish bounce,
+    // while a truly first-time anonymous visitor is never force-redirected.
+    // `storage` is non-null (guarded above); a read failure is treated as "no
+    // prior session" (fail safe toward anonymous-browse).
+    let hadPriorSession = false;
+    try {
+      hadPriorSession = (await storage.getItem(storageKeys.priorSession)) === '1';
+    } catch (priorSessionReadError) {
+      if (__DEV__) {
+        loggerUtil.debug(
+          'Failed to read prior-session hint (treating as first-time visitor)',
+          { component: 'OxyContext', method: 'restoreSessionsFromStorage' },
+          priorSessionReadError as unknown,
+        );
+      }
+    }
+
     try {
       const outcome = await runColdBoot<true>({
         steps: [
@@ -1400,11 +1450,23 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
             // still active (loop + self-heal protection).
             id: 'sso-bounce',
             enabled: () => {
-              // Opt-out: when the consumer disabled auto-SSO, never bounce a
-              // truly-anonymous visitor to the central IdP. All other restore
-              // steps already ran above, so a signed-in user is still
-              // recovered; only this terminal force-bounce is suppressed.
-              if (disableAutoSso) {
+              // Smart gate (SDK-owned, shared with `WebOxyProvider` via core's
+              // `allowSsoBounce`). The terminal `/sso` establish-bounce is the
+              // ONLY cold-boot step that can recover a session living SOLELY at
+              // the central IdP (a cross-apex RP whose local session expired),
+              // and it is what plants the per-apex `fedcm_session` cookie the
+              // earlier silent-iframe step relies on. So it is allowed iff a
+              // prior-signed-in hint exists OR a local session was recovered this
+              // boot (`storedSessionRestored`, always false here — an earlier step
+              // would have won — but passed for spec fidelity): a RETURNING user
+              // still gets ONE bounce, while a truly first-time anonymous visitor
+              // does NOT (anonymous browse). The per-tab loop guards below
+              // (`ssoNoSessionKey`, `ssoAttemptedKey`, `guardActive`) still cap an
+              // allowed bounce at one per cold boot.
+              if (!allowSsoBounce({
+                hasPriorSession: hadPriorSession,
+                hasLocalSession: storedSessionRestored,
+              })) {
                 return false;
               }
               if (!isWebBrowser() || window.top !== window.self) {
@@ -1497,11 +1559,11 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   }, [
     oxyServices,
     storage,
+    storageKeys.priorSession,
     restoreViaRefreshCookie,
     restoreStoredSession,
     runSsoReturn,
     markAuthResolved,
-    disableAutoSso,
   ]);
 
   useEffect(() => {

package/src/ui/context/hooks/useAuthOperations.ts

@@ -20,6 +20,14 @@ export interface UseAuthOperationsOptions {
   updateSessions: (sessions: ClientSession[], options?: { merge?: boolean }) => void;
   saveActiveSessionId: (sessionId: string) => Promise<void>;
   clearSessionState: () => Promise<void>;
+  /**
+   * Clear the durable returning-user hint (`storageKeys.priorSession`). Called
+   * ONLY on EXPLICIT full sign-out — alongside `clearSsoBounceState()` — so the
+   * next cold boot treats this device as a first-time anonymous visitor (no
+   * forced `/sso` bounce). NEVER called on the passive token-expiry path, so an
+   * expired session still recovers via a returning-user bounce. Best-effort.
+   */
+  clearPriorSessionHint: () => Promise<void>;
   switchSession: (sessionId: string) => Promise<User>;
   applyLanguagePreference: (user: User) => Promise<void>;
   onAuthStateChange?: (user: User | null) => void;
@@ -44,6 +52,24 @@ const LOGIN_ERROR_CODE = 'LOGIN_ERROR';
 const LOGOUT_ERROR_CODE = 'LOGOUT_ERROR';
 const LOGOUT_ALL_ERROR_CODE = 'LOGOUT_ALL_ERROR';
 
+/**
+ * Fire-and-forget the durable returning-user hint clear on explicit sign-out.
+ *
+ * Mirrors the synchronous, non-blocking nature of the sibling
+ * `clearSsoBounceState()`: sign-out must NEVER block on (or fail because of) a
+ * best-effort storage write. The clear is invoked synchronously (so unit tests
+ * can assert it ran) but its async settle is detached; any rejection is logged,
+ * never thrown.
+ */
+function clearPriorSessionHintSafe(
+  clearPriorSessionHint: () => Promise<void>,
+  logger?: (message: string, error?: unknown) => void,
+): void {
+  clearPriorSessionHint().catch((hintError) => {
+    logger?.('Failed to clear prior-session hint on sign-out', hintError);
+  });
+}
+
 /**
  * Authentication operations using public key cryptography.
  * Accepts public key as parameter - identity management is handled by the app layer.
@@ -56,6 +82,7 @@ export const useAuthOperations = ({
   updateSessions,
   saveActiveSessionId,
   clearSessionState,
+  clearPriorSessionHint,
   switchSession,
   applyLanguagePreference,
   onAuthStateChange,
@@ -227,6 +254,7 @@ export const useAuthOperations = ({
             // Genuine FULL sign-out (no sessions remain): clear the per-origin
             // SSO bounce state so a fresh deliberate sign-in can re-probe.
             clearSsoBounceState();
+            clearPriorSessionHintSafe(clearPriorSessionHint, logger);
             await clearSessionState();
             return;
           }
@@ -237,6 +265,7 @@ export const useAuthOperations = ({
         if (isInvalid && targetSessionId === activeSessionId) {
           // The active session is invalid → full sign-out; clear SSO state too.
           clearSsoBounceState();
+          clearPriorSessionHintSafe(clearPriorSessionHint, logger);
           await clearSessionState();
           return;
         }
@@ -254,6 +283,7 @@ export const useAuthOperations = ({
     [
       activeSessionId,
       clearSessionState,
+      clearPriorSessionHint,
       logger,
       onError,
       oxyServices,
@@ -286,8 +316,11 @@ export const useAuthOperations = ({
         clearActiveAuthuser();
       }
       // logoutAll is ALWAYS a full sign-out: clear the per-origin SSO bounce
-      // state (web-guarded internally) so a fresh sign-in can re-probe.
+      // state (web-guarded internally) so a fresh sign-in can re-probe, and drop
+      // the durable returning-user hint so the next cold boot is treated as a
+      // first-time anonymous visitor (no forced `/sso` bounce after sign-out).
       clearSsoBounceState();
+      clearPriorSessionHintSafe(clearPriorSessionHint, logger);
       await clearSessionState();
     } catch (error) {
       handleAuthError(error, {
@@ -299,7 +332,7 @@ export const useAuthOperations = ({
       });
       throw error instanceof Error ? error : new Error('Logout all failed');
     }
-  }, [activeSessionId, clearSessionState, logger, onError, oxyServices, setAuthState]);
+  }, [activeSessionId, clearSessionState, clearPriorSessionHint, logger, onError, oxyServices, setAuthState]);
 
   return {
     signIn,

package/src/ui/index.ts

@@ -12,6 +12,8 @@
  * cannot contain `require()` per CLAUDE.md) and (b) defeated tree-shaking.
  */
 
+/// <reference path="../types/react-native-classname.d.ts" />
+
 // Components
 export { default as OxyProvider } from './components/OxyProvider';
 export { default as OxySignInButton } from './components/OxySignInButton';

package/src/ui/screens/ProfileScreen.tsx

@@ -12,8 +12,8 @@ import { useFollow } from '../hooks/useFollow';
 import { Ionicons } from '@expo/vector-icons';
 import { useI18n } from '../hooks/useI18n';
 import { useOxy } from '../context/OxyContext';
-import { getAccountDisplayName, logger } from '@oxyhq/core';
-import type { User } from '@oxyhq/core';
+import { getAccountDisplayName, logger, normalizeProfileLinks } from '@oxyhq/core';
+import type { User, ProfileLink } from '@oxyhq/core';
 import { extractErrorMessage } from '../utils/errorHandlers';
 
 interface ProfileScreenProps extends BaseScreenProps {
@@ -21,16 +21,6 @@ interface ProfileScreenProps extends BaseScreenProps {
     username?: string;
 }
 
-interface LinkMetadata {
-    id?: string;
-    url: string;
-    title?: string;
-    description?: string;
-    image?: string;
-}
-
-type ProfileLink = string | { link: string } | LinkMetadata;
-
 const AVATAR_SIZE = 96;
 const BANNER_HEIGHT = 160;
 const AVATAR_OVERLAP = -56;
@@ -45,13 +35,7 @@ const ProfileScreen: React.FC<ProfileScreenProps> = ({ userId, username, theme,
     const [commentsCount, setCommentsCount] = useState<number | null>(null);
     const [isLoading, setIsLoading] = useState(true);
     const [error, setError] = useState<string | null>(null);
-    const [links, setLinks] = useState<Array<{
-        url: string;
-        title?: string;
-        description?: string;
-        image?: string;
-        id: string;
-    }>>([]);
+    const [links, setLinks] = useState<ProfileLink[]>([]);
 
     // Use the follow hook for real follower data
     const {
@@ -114,34 +98,8 @@ const ProfileScreen: React.FC<ProfileScreenProps> = ({ userId, username, theme,
                 setProfile(profileRes);
                 setReputationTotal(typeof reputationRes.total === 'number' ? reputationRes.total : null);
 
-                // Extract links from profile data
-                if (profileRes.linksMetadata && Array.isArray(profileRes.linksMetadata)) {
-                    const linksWithIds = profileRes.linksMetadata.map((link: LinkMetadata, index: number) => ({
-                        ...link,
-                        id: link.id || `existing-${index}`
-                    }));
-                    setLinks(linksWithIds);
-                } else if (Array.isArray(profileRes.links)) {
-                    const simpleLinks = profileRes.links.map((l: ProfileLink) => typeof l === 'string' ? l : (typeof l === 'object' && 'link' in l ? l.link : '')).filter(Boolean);
-                    const linksWithMetadata = simpleLinks.map((url: string, index: number) => ({
-                        url,
-                        title: url.replace(/^https?:\/\//, '').replace(/\/$/, ''),
-                        description: `Link to ${url}`,
-                        image: undefined,
-                        id: `existing-${index}`
-                    }));
-                    setLinks(linksWithMetadata);
-                } else if (profileRes.website) {
-                    setLinks([{
-                        url: profileRes.website,
-                        title: profileRes.website.replace(/^https?:\/\//, '').replace(/\/$/, ''),
-                        description: `Link to ${profileRes.website}`,
-                        image: undefined,
-                        id: 'existing-0'
-                    }]);
-                } else {
-                    setLinks([]);
-                }
+                // Normalize profile links via the shared @oxyhq/core helper.
+                setLinks(normalizeProfileLinks(profileRes.linksMetadata, profileRes.links));
 
                 // Follower/following counts are managed by the `useFollow` hook.
 

package/src/ui/types/navigation.ts

@@ -63,21 +63,4 @@ export interface OxyProviderProps {
     authWebUrl?: string;
     authRedirectUri?: string;
     queryClient?: QueryClient;
-    /**
-     * When `true`, skips ONLY the terminal SSO bounce in the web cold-boot
-     * chain — the force-redirect to `auth.<apex>/sso?prompt=none` that fires
-     * for a visitor with no recoverable local session. This lets a truly
-     * anonymous user keep browsing instead of being bounced to the central
-     * IdP (e.g. a marketplace that allows anonymous browsing like eBay /
-     * Shop.app).
-     *
-     * Session restore still runs in full: the callback consume, FedCM silent,
-     * first-party `/auth/silent` iframe, stored-session bearer, and
-     * cookie-restore steps all execute — so a returning signed-in user is
-     * still silently restored. Only the force-bounce for a genuinely
-     * anonymous visitor is suppressed.
-     *
-     * Default `false` (current behavior: the bounce fires).
-     */
-    disableAutoSso?: boolean;
 }

package/src/ui/utils/storageHelpers.ts

@@ -9,6 +9,17 @@ export interface SessionStorageKeys {
   activeSessionId: string;
   sessionIds: string;
   language: string;
+  /**
+   * DURABLE "this device/app has had a signed-in Oxy session before" hint.
+   *
+   * Lives in the SAME `storageKeyPrefix`-scoped durable store as the stored
+   * session ids, so it survives a session expiring (cleared only on explicit
+   * full sign-out). Read at cold boot to drive the smart `sso-bounce` gate:
+   * a returning visitor still gets ONE establish bounce so a central-only
+   * cross-domain session recovers, while a first-time anonymous visitor is
+   * never force-redirected. See `allowSsoBounce` in `@oxyhq/core`.
+   */
+  priorSession: string;
 }
 
 /**
@@ -125,6 +136,7 @@ export const getStorageKeys = (prefix: string = STORAGE_KEY_PREFIX): SessionStor
   activeSessionId: `${prefix}_active_session_id`,
   sessionIds: `${prefix}_session_ids`,
   language: `${prefix}_language`,
+  priorSession: `${prefix}_prior_session`,
 });