@micha.bigler/ui-core-micha 2.8.1 → 2.9.0

package/dist/i18n/onboardingTranslations.js

@@ -22,4 +22,8 @@ export const onboardingTranslations = {
     'Onboarding.PUSH_NOTIFICATIONS_HINT': { de: 'Aktiviere Benachrichtigungen für dieses Gerät.', fr: 'Activez les notifications pour cet appareil.', en: 'Enable notifications for this device.', sw: 'Washa arifa kwa kifaa hiki.' },
     'Onboarding.PUSH_ENABLED': { de: 'Push-Benachrichtigungen sind auf diesem Gerät aktiviert.', fr: 'Les notifications push sont activées sur cet appareil.', en: 'Push notifications are enabled on this device.', sw: 'Arifa za push zimewashwa kwenye kifaa hiki.' },
     'Onboarding.SKIP': { de: 'Überspringen', fr: 'Passer', en: 'Skip', sw: 'Ruka' },
+    'Onboarding.PWA_INSTALL_TITLE': { de: 'App installieren', fr: 'Installer l’app', en: 'Install app', sw: 'Sakinisha programu' },
+    'Onboarding.PWA_INSTALL_BODY': { de: 'Installiere die App auf deinem Gerät für schnelleren Zugriff und ein App-ähnliches Erlebnis.', fr: 'Installez l’application sur votre appareil pour un accès plus rapide et une expérience similaire à une app native.', en: 'Install the app on your device for faster access and an app-like experience.', sw: 'Sakinisha programu kwenye kifaa chako kwa ufikiaji wa haraka na hali ya matumizi kama programu.' },
+    'Onboarding.PWA_INSTALL_IOS_BODY': { de: 'Zum Installieren: Teilen-Symbol antippen und „Zum Home-Bildschirm“ wählen.', fr: 'Pour installer : appuyez sur Partager, puis « Sur l’écran d’accueil ».', en: 'To install: tap Share, then “Add to Home Screen”.', sw: 'Kusakinisha: gusa Shiriki, kisha chagua “Ongeza kwenye Skrini ya Kwanza”.' },
+    'Onboarding.PWA_INSTALL_ACTION': { de: 'Installieren', fr: 'Installer', en: 'Install', sw: 'Sakinisha' },
 };

package/dist/index.js

@@ -40,6 +40,7 @@ export { OnboardingWizard } from './onboarding/OnboardingWizard';
 export { CookieConsentStep } from './onboarding/steps/CookieConsentStep';
 export { CompleteNameStep } from './onboarding/steps/CompleteNameStep';
 export { BrowserPushStep } from './onboarding/steps/BrowserPushStep';
+export { PwaInstallStep } from './onboarding/steps/PwaInstallStep';
 // --- 9. Translations ---
 export { notificationsTranslations } from './i18n/notificationsTranslations';
 export { onboardingTranslations } from './i18n/onboardingTranslations';

package/dist/onboarding/OnboardingProvider.js

@@ -7,6 +7,7 @@ import { selectActiveSteps } from './stepSelection';
 import CookieConsentStep from './steps/CookieConsentStep';
 import CompleteNameStep from './steps/CompleteNameStep';
 import BrowserPushStep from './steps/BrowserPushStep';
+import PwaInstallStep from './steps/PwaInstallStep';
 export const UNIVERSAL_STEP_DESCRIPTORS = [
     {
         id: 'cookie_consent',
@@ -39,6 +40,26 @@ export const UNIVERSAL_STEP_DESCRIPTORS = [
         titleKey: 'Onboarding.NOTIFICATIONS_TITLE',
         Component: BrowserPushStep,
     },
+    {
+        id: 'pwa_install',
+        // App-level opt-in (ctx.pwaInstallEnabled) gates this on top of device
+        // capability — a step being "universal" in the library means available
+        // to every app, not automatically shown by every app. Apps that haven't
+        // verified their PWA manifest/icons are actually installable must not
+        // pass pwaInstallEnabled, or this would show an iOS "Add to Home Screen"
+        // hint for an app that isn't really installable.
+        condition: (ctx) => {
+            var _a, _b, _c;
+            return Boolean(ctx.pwaInstallEnabled
+                && !((_a = ctx.pwaInstall) === null || _a === void 0 ? void 0 : _a.isStandalone)
+                && (Boolean((_b = ctx.pwaInstall) === null || _b === void 0 ? void 0 : _b.deferredPrompt) || Boolean((_c = ctx.pwaInstall) === null || _c === void 0 ? void 0 : _c.isIos)));
+        },
+        blocking: false,
+        skipable: true,
+        persistDismissed: true,
+        titleKey: 'Onboarding.PWA_INSTALL_TITLE',
+        Component: PwaInstallStep,
+    },
 ];
 export const OnboardingContext = createContext(null);
 export function useOnboarding() {
@@ -61,12 +82,31 @@ function getInitialPushState() {
         && 'PushManager' in window;
     return supported ? null : { supported: false, subscribed: false };
 }
-export function OnboardingProvider({ children, extraSteps = [] }) {
+function getInitialPwaInstallState() {
+    var _a;
+    if (typeof window === 'undefined' || typeof navigator === 'undefined') {
+        return { isStandalone: false, isIos: false, deferredPrompt: null };
+    }
+    const isStandalone = Boolean(((_a = window.matchMedia) === null || _a === void 0 ? void 0 : _a.call(window, '(display-mode: standalone)').matches) || navigator.standalone);
+    // iPadOS 13+ reports a desktop Safari/Mac user agent by default, so the
+    // classic /ipad/i UA sniff misses it — the standard workaround is
+    // detecting touch support on a reported Mac platform (real Macs report
+    // maxTouchPoints 0).
+    const isIos = /iphone|ipad|ipod/i.test(navigator.userAgent || '')
+        || (navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1);
+    return { isStandalone, isIos, deferredPrompt: null };
+}
+// Stable empty-object default — an inline `{}` default would create a new
+// reference every render, invalidating the `ctx` memo below for every
+// consumer even when no extraContext is passed.
+const EMPTY_EXTRA_CONTEXT = {};
+export function OnboardingProvider({ children, extraSteps = [], extraContext = EMPTY_EXTRA_CONTEXT, pwaInstallEnabled = false, }) {
     const { user } = useContext(AuthContext);
     const [configMap, setConfigMap] = useState({});
     const [configLoaded, setConfigLoaded] = useState(false);
     const [pushState, setPushState] = useState(getInitialPushState);
     const [emailOptedIn, setEmailOptedIn] = useState(false);
+    const [pwaInstall, setPwaInstall] = useState(getInitialPwaInstallState);
     const [dismissedSet, setDismissedSet] = useState(loadDismissedSteps);
     const descriptors = useMemo(() => [...UNIVERSAL_STEP_DESCRIPTORS, ...extraSteps], [extraSteps]);
     useEffect(() => {
@@ -113,6 +153,48 @@ export function OnboardingProvider({ children, extraSteps = [] }) {
         });
         return () => { cancelled = true; };
     }, []);
+    // Capture beforeinstallprompt as early as possible (at provider mount, not
+    // when the wizard step happens to render) — Chrome fires it once, early,
+    // and calling preventDefault() late means losing the deferred prompt
+    // reference for good. Gated behind pwaInstallEnabled: calling
+    // preventDefault() unconditionally would suppress the browser's own native
+    // install UI for every app using this library, even ones that never opted
+    // in and have no replacement UI to show instead.
+    useEffect(() => {
+        var _a;
+        if (typeof window === 'undefined' || !pwaInstallEnabled)
+            return undefined;
+        const mediaQuery = (_a = window.matchMedia) === null || _a === void 0 ? void 0 : _a.call(window, '(display-mode: standalone)');
+        const handleDisplayModeChange = (event) => {
+            if (event.matches)
+                setPwaInstall((prev) => (Object.assign(Object.assign({}, prev), { isStandalone: true })));
+        };
+        const handleBeforeInstallPrompt = (event) => {
+            event.preventDefault();
+            setPwaInstall((prev) => (Object.assign(Object.assign({}, prev), { deferredPrompt: event })));
+        };
+        const handleAppInstalled = () => {
+            setPwaInstall((prev) => (Object.assign(Object.assign({}, prev), { isStandalone: true, deferredPrompt: null })));
+        };
+        if (mediaQuery === null || mediaQuery === void 0 ? void 0 : mediaQuery.addEventListener) {
+            mediaQuery.addEventListener('change', handleDisplayModeChange);
+        }
+        else if (mediaQuery === null || mediaQuery === void 0 ? void 0 : mediaQuery.addListener) {
+            mediaQuery.addListener(handleDisplayModeChange);
+        }
+        window.addEventListener('beforeinstallprompt', handleBeforeInstallPrompt);
+        window.addEventListener('appinstalled', handleAppInstalled);
+        return () => {
+            if (mediaQuery === null || mediaQuery === void 0 ? void 0 : mediaQuery.removeEventListener) {
+                mediaQuery.removeEventListener('change', handleDisplayModeChange);
+            }
+            else if (mediaQuery === null || mediaQuery === void 0 ? void 0 : mediaQuery.removeListener) {
+                mediaQuery.removeListener(handleDisplayModeChange);
+            }
+            window.removeEventListener('beforeinstallprompt', handleBeforeInstallPrompt);
+            window.removeEventListener('appinstalled', handleAppInstalled);
+        };
+    }, [pwaInstallEnabled]);
     useEffect(() => {
         let cancelled = false;
         if (!user) {
@@ -146,7 +228,8 @@ export function OnboardingProvider({ children, extraSteps = [] }) {
             return next;
         });
     }, []);
-    const ctx = useMemo(() => ({ user, pushState, emailOptedIn }), [user, pushState, emailOptedIn]);
+    // extraContext is spread last: duplicate core keys intentionally override core values, so apps should use distinct names.
+    const ctx = useMemo(() => (Object.assign({ user, pushState, emailOptedIn, pwaInstall, pwaInstallEnabled }, extraContext)), [user, pushState, emailOptedIn, pwaInstall, pwaInstallEnabled, extraContext]);
     const activeSteps = useMemo(() => {
         if (!configLoaded || !user)
             return [];

package/dist/onboarding/steps/PwaInstallStep.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import Typography from '@mui/material/Typography';
+import InstallMobileIcon from '@mui/icons-material/InstallMobile';
+export function PwaInstallStep({ onComplete, onDismiss, ctx }) {
+    var _a, _b;
+    const { t } = useTranslation();
+    const isIos = Boolean((_a = ctx === null || ctx === void 0 ? void 0 : ctx.pwaInstall) === null || _a === void 0 ? void 0 : _a.isIos);
+    const deferredPrompt = (_b = ctx === null || ctx === void 0 ? void 0 : ctx.pwaInstall) === null || _b === void 0 ? void 0 : _b.deferredPrompt;
+    const handleInstall = async () => {
+        if (!deferredPrompt) {
+            onComplete();
+            return;
+        }
+        deferredPrompt.prompt();
+        try {
+            await deferredPrompt.userChoice;
+        }
+        finally {
+            onComplete();
+        }
+    };
+    return (_jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 2 }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1 }, children: [_jsx(InstallMobileIcon, { color: "primary" }), _jsx(Typography, { variant: "h6", children: t('Onboarding.PWA_INSTALL_TITLE') })] }), _jsx(Typography, { variant: "body2", color: "text.secondary", children: t(isIos ? 'Onboarding.PWA_INSTALL_IOS_BODY' : 'Onboarding.PWA_INSTALL_BODY') }), _jsxs(Box, { sx: { display: 'flex', justifyContent: 'flex-end', gap: 1 }, children: [_jsx(Button, { variant: "text", onClick: onDismiss, children: t('Onboarding.SKIP') }), isIos ? (_jsx(Button, { variant: "contained", onClick: onComplete, children: t('Onboarding.CONTINUE') })) : (_jsx(Button, { variant: "contained", onClick: handleInstall, children: t('Onboarding.PWA_INSTALL_ACTION') }))] })] }));
+}
+export default PwaInstallStep;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@micha.bigler/ui-core-micha",
-  "version": "2.8.1",
+  "version": "2.9.0",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "repository": {

package/src/i18n/onboardingTranslations.ts

@@ -22,4 +22,8 @@ export const onboardingTranslations = {
   'Onboarding.PUSH_NOTIFICATIONS_HINT': { de: 'Aktiviere Benachrichtigungen für dieses Gerät.', fr: 'Activez les notifications pour cet appareil.', en: 'Enable notifications for this device.', sw: 'Washa arifa kwa kifaa hiki.' },
   'Onboarding.PUSH_ENABLED': { de: 'Push-Benachrichtigungen sind auf diesem Gerät aktiviert.', fr: 'Les notifications push sont activées sur cet appareil.', en: 'Push notifications are enabled on this device.', sw: 'Arifa za push zimewashwa kwenye kifaa hiki.' },
   'Onboarding.SKIP': { de: 'Überspringen', fr: 'Passer', en: 'Skip', sw: 'Ruka' },
+  'Onboarding.PWA_INSTALL_TITLE': { de: 'App installieren', fr: 'Installer l’app', en: 'Install app', sw: 'Sakinisha programu' },
+  'Onboarding.PWA_INSTALL_BODY': { de: 'Installiere die App auf deinem Gerät für schnelleren Zugriff und ein App-ähnliches Erlebnis.', fr: 'Installez l’application sur votre appareil pour un accès plus rapide et une expérience similaire à une app native.', en: 'Install the app on your device for faster access and an app-like experience.', sw: 'Sakinisha programu kwenye kifaa chako kwa ufikiaji wa haraka na hali ya matumizi kama programu.' },
+  'Onboarding.PWA_INSTALL_IOS_BODY': { de: 'Zum Installieren: Teilen-Symbol antippen und „Zum Home-Bildschirm“ wählen.', fr: 'Pour installer : appuyez sur Partager, puis « Sur l’écran d’accueil ».', en: 'To install: tap Share, then “Add to Home Screen”.', sw: 'Kusakinisha: gusa Shiriki, kisha chagua “Ongeza kwenye Skrini ya Kwanza”.' },
+  'Onboarding.PWA_INSTALL_ACTION': { de: 'Installieren', fr: 'Installer', en: 'Install', sw: 'Sakinisha' },
 };

package/src/index.js

@@ -59,6 +59,7 @@ export { OnboardingWizard } from './onboarding/OnboardingWizard';
 export { CookieConsentStep } from './onboarding/steps/CookieConsentStep';
 export { CompleteNameStep } from './onboarding/steps/CompleteNameStep';
 export { BrowserPushStep } from './onboarding/steps/BrowserPushStep';
+export { PwaInstallStep } from './onboarding/steps/PwaInstallStep';
 
 // --- 9. Translations ---
 export { notificationsTranslations } from './i18n/notificationsTranslations';

package/src/onboarding/OnboardingProvider.jsx

@@ -13,6 +13,7 @@ import { selectActiveSteps } from './stepSelection';
 import CookieConsentStep from './steps/CookieConsentStep';
 import CompleteNameStep from './steps/CompleteNameStep';
 import BrowserPushStep from './steps/BrowserPushStep';
+import PwaInstallStep from './steps/PwaInstallStep';
 
 export const UNIVERSAL_STEP_DESCRIPTORS = [
   {
@@ -45,6 +46,25 @@ export const UNIVERSAL_STEP_DESCRIPTORS = [
     titleKey: 'Onboarding.NOTIFICATIONS_TITLE',
     Component: BrowserPushStep,
   },
+  {
+    id: 'pwa_install',
+    // App-level opt-in (ctx.pwaInstallEnabled) gates this on top of device
+    // capability — a step being "universal" in the library means available
+    // to every app, not automatically shown by every app. Apps that haven't
+    // verified their PWA manifest/icons are actually installable must not
+    // pass pwaInstallEnabled, or this would show an iOS "Add to Home Screen"
+    // hint for an app that isn't really installable.
+    condition: (ctx) => Boolean(
+      ctx.pwaInstallEnabled
+      && !ctx.pwaInstall?.isStandalone
+      && (Boolean(ctx.pwaInstall?.deferredPrompt) || Boolean(ctx.pwaInstall?.isIos)),
+    ),
+    blocking: false,
+    skipable: true,
+    persistDismissed: true,
+    titleKey: 'Onboarding.PWA_INSTALL_TITLE',
+    Component: PwaInstallStep,
+  },
 ];
 
 export const OnboardingContext = createContext(null);
@@ -70,12 +90,36 @@ function getInitialPushState() {
   return supported ? null : { supported: false, subscribed: false };
 }
 
-export function OnboardingProvider({ children, extraSteps = [] }) {
+function getInitialPwaInstallState() {
+  if (typeof window === 'undefined' || typeof navigator === 'undefined') {
+    return { isStandalone: false, isIos: false, deferredPrompt: null };
+  }
+  const isStandalone = Boolean(
+    window.matchMedia?.('(display-mode: standalone)').matches || navigator.standalone,
+  );
+  // iPadOS 13+ reports a desktop Safari/Mac user agent by default, so the
+  // classic /ipad/i UA sniff misses it — the standard workaround is
+  // detecting touch support on a reported Mac platform (real Macs report
+  // maxTouchPoints 0).
+  const isIos = /iphone|ipad|ipod/i.test(navigator.userAgent || '')
+    || (navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1);
+  return { isStandalone, isIos, deferredPrompt: null };
+}
+
+// Stable empty-object default — an inline `{}` default would create a new
+// reference every render, invalidating the `ctx` memo below for every
+// consumer even when no extraContext is passed.
+const EMPTY_EXTRA_CONTEXT = {};
+
+export function OnboardingProvider({
+  children, extraSteps = [], extraContext = EMPTY_EXTRA_CONTEXT, pwaInstallEnabled = false,
+}) {
   const { user } = useContext(AuthContext);
   const [configMap, setConfigMap] = useState({});
   const [configLoaded, setConfigLoaded] = useState(false);
   const [pushState, setPushState] = useState(getInitialPushState);
   const [emailOptedIn, setEmailOptedIn] = useState(false);
+  const [pwaInstall, setPwaInstall] = useState(getInitialPwaInstallState);
   const [dismissedSet, setDismissedSet] = useState(loadDismissedSteps);
 
   const descriptors = useMemo(
@@ -128,6 +172,48 @@ export function OnboardingProvider({ children, extraSteps = [] }) {
     return () => { cancelled = true; };
   }, []);
 
+  // Capture beforeinstallprompt as early as possible (at provider mount, not
+  // when the wizard step happens to render) — Chrome fires it once, early,
+  // and calling preventDefault() late means losing the deferred prompt
+  // reference for good. Gated behind pwaInstallEnabled: calling
+  // preventDefault() unconditionally would suppress the browser's own native
+  // install UI for every app using this library, even ones that never opted
+  // in and have no replacement UI to show instead.
+  useEffect(() => {
+    if (typeof window === 'undefined' || !pwaInstallEnabled) return undefined;
+
+    const mediaQuery = window.matchMedia?.('(display-mode: standalone)');
+
+    const handleDisplayModeChange = (event) => {
+      if (event.matches) setPwaInstall((prev) => ({ ...prev, isStandalone: true }));
+    };
+    const handleBeforeInstallPrompt = (event) => {
+      event.preventDefault();
+      setPwaInstall((prev) => ({ ...prev, deferredPrompt: event }));
+    };
+    const handleAppInstalled = () => {
+      setPwaInstall((prev) => ({ ...prev, isStandalone: true, deferredPrompt: null }));
+    };
+
+    if (mediaQuery?.addEventListener) {
+      mediaQuery.addEventListener('change', handleDisplayModeChange);
+    } else if (mediaQuery?.addListener) {
+      mediaQuery.addListener(handleDisplayModeChange);
+    }
+    window.addEventListener('beforeinstallprompt', handleBeforeInstallPrompt);
+    window.addEventListener('appinstalled', handleAppInstalled);
+
+    return () => {
+      if (mediaQuery?.removeEventListener) {
+        mediaQuery.removeEventListener('change', handleDisplayModeChange);
+      } else if (mediaQuery?.removeListener) {
+        mediaQuery.removeListener(handleDisplayModeChange);
+      }
+      window.removeEventListener('beforeinstallprompt', handleBeforeInstallPrompt);
+      window.removeEventListener('appinstalled', handleAppInstalled);
+    };
+  }, [pwaInstallEnabled]);
+
   useEffect(() => {
     let cancelled = false;
     if (!user) {
@@ -162,7 +248,13 @@ export function OnboardingProvider({ children, extraSteps = [] }) {
     });
   }, []);
 
-  const ctx = useMemo(() => ({ user, pushState, emailOptedIn }), [user, pushState, emailOptedIn]);
+  // extraContext is spread last: duplicate core keys intentionally override core values, so apps should use distinct names.
+  const ctx = useMemo(
+    () => ({
+      user, pushState, emailOptedIn, pwaInstall, pwaInstallEnabled, ...extraContext,
+    }),
+    [user, pushState, emailOptedIn, pwaInstall, pwaInstallEnabled, extraContext],
+  );
   const activeSteps = useMemo(() => {
     if (!configLoaded || !user) return [];
     return selectActiveSteps(descriptors, configMap, ctx, dismissedSet);

package/src/onboarding/steps/PwaInstallStep.jsx

@@ -0,0 +1,47 @@
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import Typography from '@mui/material/Typography';
+import InstallMobileIcon from '@mui/icons-material/InstallMobile';
+
+export function PwaInstallStep({ onComplete, onDismiss, ctx }) {
+  const { t } = useTranslation();
+  const isIos = Boolean(ctx?.pwaInstall?.isIos);
+  const deferredPrompt = ctx?.pwaInstall?.deferredPrompt;
+
+  const handleInstall = async () => {
+    if (!deferredPrompt) {
+      onComplete();
+      return;
+    }
+    deferredPrompt.prompt();
+    try {
+      await deferredPrompt.userChoice;
+    } finally {
+      onComplete();
+    }
+  };
+
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+      <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+        <InstallMobileIcon color="primary" />
+        <Typography variant="h6">{t('Onboarding.PWA_INSTALL_TITLE')}</Typography>
+      </Box>
+      <Typography variant="body2" color="text.secondary">
+        {t(isIos ? 'Onboarding.PWA_INSTALL_IOS_BODY' : 'Onboarding.PWA_INSTALL_BODY')}
+      </Typography>
+      <Box sx={{ display: 'flex', justifyContent: 'flex-end', gap: 1 }}>
+        <Button variant="text" onClick={onDismiss}>{t('Onboarding.SKIP')}</Button>
+        {isIos ? (
+          <Button variant="contained" onClick={onComplete}>{t('Onboarding.CONTINUE')}</Button>
+        ) : (
+          <Button variant="contained" onClick={handleInstall}>{t('Onboarding.PWA_INSTALL_ACTION')}</Button>
+        )}
+      </Box>
+    </Box>
+  );
+}
+
+export default PwaInstallStep;

package/tests/OnboardingProvider.test.jsx

@@ -21,10 +21,28 @@ function Probe() {
   return <span data-testid="email-opted-in">{String(onboarding?.ctx.emailOptedIn)}</span>;
 }
 
-function renderProvider() {
+function ActiveStepsProbe() {
+  const onboarding = useOnboarding();
+  return <span data-testid="active-steps">{onboarding?.activeSteps.map((step) => step.id).join(',')}</span>;
+}
+
+function renderProvider({ extraContext, extraSteps, pwaInstallEnabled, children = <Probe /> } = {}) {
   return render(
-    <AuthContext.Provider value={{ user: { id: 1 } }}>
-      <OnboardingProvider><Probe /></OnboardingProvider>
+    <AuthContext.Provider value={{
+      user: {
+        id: 1,
+        accepted_privacy_statement: true,
+        first_name: 'Ada',
+        last_name: 'Lovelace',
+      },
+    }}>
+      <OnboardingProvider
+        extraContext={extraContext}
+        extraSteps={extraSteps}
+        pwaInstallEnabled={pwaInstallEnabled}
+      >
+        {children}
+      </OnboardingProvider>
     </AuthContext.Provider>,
   );
 }
@@ -54,3 +72,89 @@ describe('OnboardingProvider notification preferences', () => {
     expect(screen.getByTestId('email-opted-in').textContent).toBe('false');
   });
 });
+
+describe('OnboardingProvider extra context', () => {
+  const unreadMessagesCondition = vi.fn((ctx) => (ctx.unreadCount || 0) > 0);
+  const unreadMessagesStep = {
+    id: 'unread_messages',
+    condition: unreadMessagesCondition,
+    persistDismissed: false,
+  };
+
+  beforeEach(() => {
+    cleanup();
+    vi.clearAllMocks();
+    onboardingApi.getOnboardingStepConfig.mockResolvedValue([]);
+    notificationsApi.getNotificationPreferences.mockResolvedValue({ email_opt_in: true });
+  });
+
+  it('shows an app step when its extra context condition is met', async () => {
+    renderProvider({
+      extraContext: { unreadCount: 2 },
+      extraSteps: [unreadMessagesStep],
+      children: <ActiveStepsProbe />,
+    });
+
+    await waitFor(() => expect(screen.getByTestId('active-steps').textContent).toContain('unread_messages'));
+  });
+
+  it.each([
+    ['zero', { unreadCount: 0 }],
+    ['omitted', undefined],
+  ])('does not show an app step when unreadCount is %s', async (_label, extraContext) => {
+    renderProvider({
+      extraContext,
+      extraSteps: [unreadMessagesStep],
+      children: <ActiveStepsProbe />,
+    });
+
+    await waitFor(() => expect(unreadMessagesCondition).toHaveBeenCalled());
+    expect(screen.getByTestId('active-steps').textContent).not.toContain('unread_messages');
+  });
+});
+
+describe('OnboardingProvider pwa_install capture', () => {
+  beforeEach(() => {
+    cleanup();
+    vi.clearAllMocks();
+    onboardingApi.getOnboardingStepConfig.mockResolvedValue([]);
+    notificationsApi.getNotificationPreferences.mockResolvedValue({ email_opt_in: true });
+  });
+
+  function dispatchBeforeInstallPrompt() {
+    const event = new Event('beforeinstallprompt', { cancelable: true });
+    event.prompt = vi.fn();
+    event.userChoice = Promise.resolve({ outcome: 'accepted' });
+    window.dispatchEvent(event);
+    return event;
+  }
+
+  it('does not show pwa_install without the app opt-in prop, and does not suppress the browser default install UI', async () => {
+    renderProvider({ pwaInstallEnabled: false, children: <ActiveStepsProbe /> });
+    await waitFor(() => expect(onboardingApi.getOnboardingStepConfig).toHaveBeenCalled());
+
+    const event = dispatchBeforeInstallPrompt();
+
+    await waitFor(() => expect(screen.getByTestId('active-steps').textContent).not.toContain('pwa_install'));
+    // Regression guard: a non-opted-in app must keep the browser's own
+    // native install UI, since it has no replacement to show instead.
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it('shows pwa_install once opted in and a beforeinstallprompt event is captured', async () => {
+    renderProvider({ pwaInstallEnabled: true, children: <ActiveStepsProbe /> });
+    await waitFor(() => expect(onboardingApi.getOnboardingStepConfig).toHaveBeenCalled());
+
+    const event = dispatchBeforeInstallPrompt();
+
+    await waitFor(() => expect(screen.getByTestId('active-steps').textContent).toContain('pwa_install'));
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it('does not show pwa_install when opted in but no prompt was ever captured (non-iOS)', async () => {
+    renderProvider({ pwaInstallEnabled: true, children: <ActiveStepsProbe /> });
+    await waitFor(() => expect(onboardingApi.getOnboardingStepConfig).toHaveBeenCalled());
+
+    expect(screen.getByTestId('active-steps').textContent).not.toContain('pwa_install');
+  });
+});

package/tests/onboardingDescriptors.test.js

@@ -4,6 +4,7 @@ import { selectActiveSteps } from '../src/onboarding/stepSelection';
 
 const cookieConsentDescriptor = UNIVERSAL_STEP_DESCRIPTORS.find((step) => step.id === 'cookie_consent');
 const browserPushDescriptor = UNIVERSAL_STEP_DESCRIPTORS.find((step) => step.id === 'browser_push');
+const pwaInstallDescriptor = UNIVERSAL_STEP_DESCRIPTORS.find((step) => step.id === 'pwa_install');
 
 describe('cookie_consent descriptor condition', () => {
   it('is active when the user has not accepted the privacy statement, regardless of cookies', () => {
@@ -67,3 +68,48 @@ describe('browser_push descriptor condition', () => {
     expect(activeSteps).toEqual([]);
   });
 });
+
+describe('pwa_install descriptor condition', () => {
+  it('is inactive when the app has not opted in, even if the device could install', () => {
+    expect(pwaInstallDescriptor.condition({
+      pwaInstallEnabled: false,
+      pwaInstall: { deferredPrompt: {}, isStandalone: false, isIos: false },
+    })).toBe(false);
+  });
+
+  it('is active when opted in and Android/Chrome captured a deferred install prompt', () => {
+    expect(pwaInstallDescriptor.condition({
+      pwaInstallEnabled: true,
+      pwaInstall: { deferredPrompt: {}, isStandalone: false, isIos: false },
+    })).toBe(true);
+  });
+
+  it('is active when opted in on iOS (no deferred prompt exists there, only the hint)', () => {
+    expect(pwaInstallDescriptor.condition({
+      pwaInstallEnabled: true,
+      pwaInstall: { deferredPrompt: null, isStandalone: false, isIos: true },
+    })).toBe(true);
+  });
+
+  it('is inactive when opted in but neither a deferred prompt nor iOS applies', () => {
+    expect(pwaInstallDescriptor.condition({
+      pwaInstallEnabled: true,
+      pwaInstall: { deferredPrompt: null, isStandalone: false, isIos: false },
+    })).toBe(false);
+  });
+
+  it('is inactive once already running standalone, regardless of opt-in or device capability', () => {
+    expect(pwaInstallDescriptor.condition({
+      pwaInstallEnabled: true,
+      pwaInstall: { deferredPrompt: {}, isStandalone: true, isIos: false },
+    })).toBe(false);
+    expect(pwaInstallDescriptor.condition({
+      pwaInstallEnabled: true,
+      pwaInstall: { deferredPrompt: null, isStandalone: true, isIos: true },
+    })).toBe(false);
+  });
+
+  it('is inactive with no pwaInstall context at all', () => {
+    expect(pwaInstallDescriptor.condition({ pwaInstallEnabled: true })).toBe(false);
+  });
+});