useInstallPrompt

Remarks

Chromium fires beforeinstallprompt when it considers a site installable, and a page that prevents the event's default keeps the right to open the install dialog later, from a gesture of the learner's own. That is the whole mechanism, and this hook is the only place in the app that knows about it.

Preventing the default is not optional: left alone the browser shows its own promotion, and the learner would be asked twice by two different surfaces.

The event usually arrives before this hook exists. Chromium fires it as soon as it judges the site installable, which is routinely before hydration, and it does not fire again — so subscribing alone loses it. captureInstallOffer, run from the client instrumentation entry point before the application starts, catches it first; this hook adopts whatever is waiting there and subscribes as well, so it is right whichever side of hydration the event lands on.

The offer is withdrawn on three occasions — the learner accepted it, the browser reported the install, or the app is already running from the home screen — because in all three the question has been settled and asking again would be asking someone to repeat themselves.

It reports no offer until hydration commits. The event is a browser fact and cannot be known while rendering on the server, so adopting it earlier would make the server and client markup disagree.

Browsers that fire nothing — Firefox, and Safari on every platform — simply never leave the no-offer state. On an iPhone that is the whole reason useCanInstallToHomeScreen and its guide exist.