3 files changed, 76 insertions, 13 deletions

diff --git a/src/components/PolicyUpdateOverlay/context.tsx b/src/components/PolicyUpdateOverlay/context.tsx
index 68ae7bbd8..4f6e56e21 100644
--- a/src/components/PolicyUpdateOverlay/context.tsx
+++ b/src/components/PolicyUpdateOverlay/context.tsx
@@ -1,32 +1,67 @@
-import {createContext, type ReactNode, useContext} from 'react'
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useMemo,
+  useState,
+} from 'react'
 
+import {useSession} from '#/state/session'
 import {Provider as PortalProvider} from '#/components/PolicyUpdateOverlay/Portal'
 import {
   type PolicyUpdateState,
   usePolicyUpdateState,
 } from '#/components/PolicyUpdateOverlay/usePolicyUpdateState'
 
-const Context = createContext<PolicyUpdateState>({
-  completed: true,
-  complete: () => {},
+const Context = createContext<{
+  state: PolicyUpdateState
+  setIsReadyToShowOverlay: () => void
+}>({
+  state: {
+    completed: true,
+    complete: () => {},
+  },
+  /**
+   * Although our data will be ready to go when the app shell mounts, we don't
+   * want to show the overlay until we actually render it, which happens after
+   * sigin/signup/onboarding in `createNativeStackNavigatorWithAuth`.
+   */
+  setIsReadyToShowOverlay: () => {},
 })
 
-export function usePolicyUpdateStateContext() {
+export function usePolicyUpdateContext() {
   const context = useContext(Context)
   if (!context) {
     throw new Error(
-      'usePolicyUpdateStateContext must be used within a PolicyUpdateProvider',
+      'usePolicyUpdateContext must be used within a PolicyUpdateProvider',
     )
   }
   return context
 }
 
 export function Provider({children}: {children?: ReactNode}) {
-  const state = usePolicyUpdateState()
+  const {hasSession} = useSession()
+  const [isReadyToShowOverlay, setIsReadyToShowOverlay] = useState(false)
+  const state = usePolicyUpdateState({
+    // only enable the policy update overlay in non-test environments
+    enabled:
+      isReadyToShowOverlay && hasSession && process.env.NODE_ENV !== 'test',
+  })
+
+  const ctx = useMemo(
+    () => ({
+      state,
+      setIsReadyToShowOverlay() {
+        if (isReadyToShowOverlay) return
+        setIsReadyToShowOverlay(true)
+      },
+    }),
+    [state, isReadyToShowOverlay, setIsReadyToShowOverlay],
+  )
 
   return (
     <PortalProvider>
-      <Context.Provider value={state}>{children}</Context.Provider>
+      <Context.Provider value={ctx}>{children}</Context.Provider>
     </PortalProvider>
   )
 }
diff --git a/src/components/PolicyUpdateOverlay/index.tsx b/src/components/PolicyUpdateOverlay/index.tsx
index 1900dc27f..f30da4334 100644
--- a/src/components/PolicyUpdateOverlay/index.tsx
+++ b/src/components/PolicyUpdateOverlay/index.tsx
@@ -1,18 +1,26 @@
+import {useEffect} from 'react'
 import {View} from 'react-native'
 
 import {isIOS} from '#/platform/detection'
 import {atoms as a} from '#/alf'
 import {FullWindowOverlay} from '#/components/FullWindowOverlay'
-import {usePolicyUpdateStateContext} from '#/components/PolicyUpdateOverlay/context'
+import {usePolicyUpdateContext} from '#/components/PolicyUpdateOverlay/context'
 import {Portal} from '#/components/PolicyUpdateOverlay/Portal'
 import {Content} from '#/components/PolicyUpdateOverlay/updates/202508'
 
 export {Provider} from '#/components/PolicyUpdateOverlay/context'
-export {usePolicyUpdateStateContext} from '#/components/PolicyUpdateOverlay/context'
+export {usePolicyUpdateContext} from '#/components/PolicyUpdateOverlay/context'
 export {Outlet} from '#/components/PolicyUpdateOverlay/Portal'
 
 export function PolicyUpdateOverlay() {
-  const state = usePolicyUpdateStateContext()
+  const {state, setIsReadyToShowOverlay} = usePolicyUpdateContext()
+
+  useEffect(() => {
+    /**
+     * Tell the context that we are ready to show the overlay.
+     */
+    setIsReadyToShowOverlay()
+  }, [setIsReadyToShowOverlay])
 
   /*
    * See `window.clearNux` example in `/state/queries/nuxs` for a way to clear
diff --git a/src/components/PolicyUpdateOverlay/usePolicyUpdateState.ts b/src/components/PolicyUpdateOverlay/usePolicyUpdateState.ts
index 29d8afe06..32b948af9 100644
--- a/src/components/PolicyUpdateOverlay/usePolicyUpdateState.ts
+++ b/src/components/PolicyUpdateOverlay/usePolicyUpdateState.ts
@@ -11,13 +11,33 @@ export type PolicyUpdateState = {
   complete: () => void
 }
 
-export function usePolicyUpdateState() {
+export function usePolicyUpdateState({
+  enabled,
+}: {
+  /**
+   * Used to skip the policy update overlay until we're actually ready to
+   * show it.
+   */
+  enabled: boolean
+}) {
   const nux = useNux(ACTIVE_UPDATE_ID)
   const {mutate: save, variables} = useSaveNux()
   const deviceStorage = useStorage(device, [ACTIVE_UPDATE_ID])
   const debugOverride =
     !!useStorage(device, ['policyUpdateDebugOverride'])[0] && IS_DEV
+
   return useMemo(() => {
+    /**
+     * If not enabled, then just return a completed state so the app functions
+     * as normal.
+     */
+    if (!enabled) {
+      return {
+        completed: true,
+        complete() {},
+      }
+    }
+
     const nuxIsReady = nux.status === 'ready'
     const nuxIsCompleted = nux.nux?.completed === true
     const nuxIsOptimisticallyCompleted = !!variables?.completed
@@ -59,7 +79,7 @@ export function usePolicyUpdateState() {
         setCompletedForDevice(true)
       },
     }
-  }, [nux, save, variables, deviceStorage, debugOverride])
+  }, [enabled, nux, save, variables, deviceStorage, debugOverride])
 }
 
 export function computeCompletedState({