@micha.bigler/ui-core-micha 2.8.2 → 2.10.0

package/WORK_ORDERS.md

@@ -0,0 +1,20 @@
+# WORK_ORDERS.md — ui-core-micha
+
+Work-order register for this repo. Lightweight directory (not the full orders):
+one row per WO with its implementation status. Convention, schema, and maintenance
+rules are defined centrally in `webapps/AGENTS.md` → "Work-Order Register".
+
+## Workstream prefixes
+
+| Prefix | Workstream |
+|---|---|
+| `ONB-*` | Onboarding wizard (steps, conditions, persistence) |
+
+Introduce a new prefix when none fits and add it here. New WOs always get a
+prefixed ID; never reuse a bare flat number across workstreams.
+
+## Register
+
+| ID | Titel | Beschreibung | Datum | Status | Commit(s) | Notiz |
+|---|---|---|---|---|---|---|
+| ONB-1 | Per-app configurable notifications onboarding step | New `browserPush` prop `{nagUntil, showOnce}` on `OnboardingProvider`; parameterizes the `browser_push` descriptor's condition (default changes from implicit "all-channels" to "any-channel", stopping the over-nag); `showOnce` via a persisted `onboarding_seen` set (frozen-at-mount ref, no mid-session flicker) | 2026-07-17 | done | 1ae7c20 | Default behavior change affects cockpit and all consumers on their next ucm bump. jg-ferien companion WO pins the new version with `browserPush={{nagUntil: 'any-channel'}}` explicit (matches new default, but pinned explicitly per the WO). |

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

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import React, { createContext, useCallback, useContext, useEffect, useMemo, useState, } from 'react';
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
 import { AuthContext } from '../auth/AuthContext';
 import { getNotificationPreferences } from '../notifications/api';
 import { getOnboardingStepConfig } from './api';
@@ -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',
@@ -30,8 +31,17 @@ export const UNIVERSAL_STEP_DESCRIPTORS = [
         id: 'browser_push',
         condition: (ctx) => {
             var _a, _b;
-            return Boolean((((_a = ctx.pushState) === null || _a === void 0 ? void 0 : _a.supported) && (!ctx.pushState.subscribed || !ctx.emailOptedIn))
-                || (!((_b = ctx.pushState) === null || _b === void 0 ? void 0 : _b.supported) && !ctx.emailOptedIn));
+            const { nagUntil = 'any-channel', showOnce = false } = ctx.browserPush || {};
+            if (showOnce && ((_a = ctx.seenSteps) === null || _a === void 0 ? void 0 : _a.has('browser_push')))
+                return false;
+            if (nagUntil === 'off')
+                return false;
+            const supported = (_b = ctx.pushState) === null || _b === void 0 ? void 0 : _b.supported;
+            if (!supported)
+                return !ctx.emailOptedIn;
+            if (nagUntil === 'all-channels')
+                return !ctx.pushState.subscribed || !ctx.emailOptedIn;
+            return !ctx.pushState.subscribed && !ctx.emailOptedIn; // 'any-channel' (default)
         },
         blocking: false,
         skipable: true,
@@ -39,6 +49,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() {
@@ -54,6 +84,28 @@ function loadDismissedSteps() {
         return new Set();
     }
 }
+function loadSeenSteps() {
+    if (typeof window === 'undefined')
+        return new Set();
+    try {
+        return new Set(JSON.parse(window.localStorage.getItem('onboarding_seen')) || []);
+    }
+    catch (_a) {
+        return new Set();
+    }
+}
+function persistSeenStep(id) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        const seenSteps = loadSeenSteps();
+        seenSteps.add(id);
+        window.localStorage.setItem('onboarding_seen', JSON.stringify([...seenSteps]));
+    }
+    catch (_a) {
+        // Persistence is optional; the current session remains unaffected.
+    }
+}
 function getInitialPushState() {
     const supported = typeof navigator !== 'undefined'
         && typeof window !== 'undefined'
@@ -61,17 +113,35 @@ function getInitialPushState() {
         && 'PushManager' in window;
     return supported ? null : { supported: false, subscribed: false };
 }
+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 }) {
+const EMPTY_BROWSER_PUSH = {};
+export function OnboardingProvider({ children, extraSteps = [], extraContext = EMPTY_EXTRA_CONTEXT, pwaInstallEnabled = false, browserPush = EMPTY_BROWSER_PUSH, }) {
     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 seenAtMountRef = useRef(loadSeenSteps());
+    const resolvedBrowserPush = useMemo(() => (Object.assign({ nagUntil: 'any-channel', showOnce: false }, browserPush)), [browserPush]);
     const descriptors = useMemo(() => [...UNIVERSAL_STEP_DESCRIPTORS, ...extraSteps], [extraSteps]);
     useEffect(() => {
         let cancelled = false;
@@ -117,6 +187,48 @@ export function OnboardingProvider({ children, extraSteps = [], extraContext = E
         });
         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) {
@@ -150,13 +262,29 @@ export function OnboardingProvider({ children, extraSteps = [], extraContext = E
             return next;
         });
     }, []);
+    const markStepSeen = useCallback((id) => {
+        persistSeenStep(id);
+    }, []);
     // 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 }, extraContext)), [user, pushState, emailOptedIn, extraContext]);
+    const ctx = useMemo(() => (Object.assign({ user,
+        pushState,
+        emailOptedIn,
+        pwaInstall,
+        pwaInstallEnabled, browserPush: resolvedBrowserPush, seenSteps: seenAtMountRef.current }, extraContext)), [
+        user,
+        pushState,
+        emailOptedIn,
+        pwaInstall,
+        pwaInstallEnabled,
+        resolvedBrowserPush,
+        seenAtMountRef.current,
+        extraContext,
+    ]);
     const activeSteps = useMemo(() => {
         if (!configLoaded || !user)
             return [];
         return selectActiveSteps(descriptors, configMap, ctx, dismissedSet);
     }, [configLoaded, user, descriptors, configMap, ctx, dismissedSet]);
-    const value = useMemo(() => ({ activeSteps, dismissStep, ctx, configMap, setConfigMap }), [activeSteps, dismissStep, ctx, configMap]);
+    const value = useMemo(() => ({ activeSteps, dismissStep, markStepSeen, ctx, configMap, setConfigMap }), [activeSteps, dismissStep, markStepSeen, ctx, configMap]);
     return _jsx(OnboardingContext.Provider, { value: value, children: children });
 }

package/dist/onboarding/OnboardingWizard.js

@@ -18,6 +18,7 @@ export function OnboardingWizard() {
     const [completed, setCompleted] = useState(0);
     const activeSteps = (onboarding === null || onboarding === void 0 ? void 0 : onboarding.activeSteps) || [];
     const visibleSteps = activeSteps.filter((step) => !sessionDismissed.has(step.id));
+    const currentStep = visibleSteps[0];
     useEffect(() => {
         if (visibleSteps.length > 0 && totalRef.current === null) {
             totalRef.current = visibleSteps.length;
@@ -28,10 +29,13 @@ export function OnboardingWizard() {
             setCompleted(0);
         }
     }, [visibleSteps.length]);
+    useEffect(() => {
+        if (onboarding && currentStep)
+            onboarding.markStepSeen(currentStep.id);
+    }, [onboarding, currentStep === null || currentStep === void 0 ? void 0 : currentStep.id]);
     if (!onboarding || visibleSteps.length === 0)
         return null;
     const { dismissStep, ctx } = onboarding;
-    const currentStep = visibleSteps[0];
     const total = totalRef.current || visibleSteps.length;
     const progress = total > 1 ? Math.round((completed / total) * 100) : 0;
     const StepComponent = currentStep.Component;

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.2",
+  "version": "2.10.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

@@ -4,6 +4,7 @@ import React, {
   useContext,
   useEffect,
   useMemo,
+  useRef,
   useState,
 } from 'react';
 import { AuthContext } from '../auth/AuthContext';
@@ -13,6 +14,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 = [
   {
@@ -35,16 +37,40 @@ export const UNIVERSAL_STEP_DESCRIPTORS = [
   },
   {
     id: 'browser_push',
-    condition: (ctx) => Boolean(
-      (ctx.pushState?.supported && (!ctx.pushState.subscribed || !ctx.emailOptedIn))
-      || (!ctx.pushState?.supported && !ctx.emailOptedIn),
-    ),
+    condition: (ctx) => {
+      const { nagUntil = 'any-channel', showOnce = false } = ctx.browserPush || {};
+      if (showOnce && ctx.seenSteps?.has('browser_push')) return false;
+      if (nagUntil === 'off') return false;
+      const supported = ctx.pushState?.supported;
+      if (!supported) return !ctx.emailOptedIn;
+      if (nagUntil === 'all-channels') return !ctx.pushState.subscribed || !ctx.emailOptedIn;
+      return !ctx.pushState.subscribed && !ctx.emailOptedIn; // 'any-channel' (default)
+    },
     blocking: false,
     skipable: true,
     persistDismissed: true,
     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);
@@ -62,6 +88,26 @@ function loadDismissedSteps() {
   }
 }
 
+function loadSeenSteps() {
+  if (typeof window === 'undefined') return new Set();
+  try {
+    return new Set(JSON.parse(window.localStorage.getItem('onboarding_seen')) || []);
+  } catch {
+    return new Set();
+  }
+}
+
+function persistSeenStep(id) {
+  if (typeof window === 'undefined') return;
+  try {
+    const seenSteps = loadSeenSteps();
+    seenSteps.add(id);
+    window.localStorage.setItem('onboarding_seen', JSON.stringify([...seenSteps]));
+  } catch {
+    // Persistence is optional; the current session remains unaffected.
+  }
+}
+
 function getInitialPushState() {
   const supported = typeof navigator !== 'undefined'
     && typeof window !== 'undefined'
@@ -70,18 +116,48 @@ function getInitialPushState() {
   return supported ? null : { supported: false, subscribed: false };
 }
 
+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 = {};
+const EMPTY_BROWSER_PUSH = {};
 
-export function OnboardingProvider({ children, extraSteps = [], extraContext = EMPTY_EXTRA_CONTEXT }) {
+export function OnboardingProvider({
+  children,
+  extraSteps = [],
+  extraContext = EMPTY_EXTRA_CONTEXT,
+  pwaInstallEnabled = false,
+  browserPush = EMPTY_BROWSER_PUSH,
+}) {
   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 seenAtMountRef = useRef(loadSeenSteps());
+
+  const resolvedBrowserPush = useMemo(
+    () => ({ nagUntil: 'any-channel', showOnce: false, ...browserPush }),
+    [browserPush],
+  );
 
   const descriptors = useMemo(
     () => [...UNIVERSAL_STEP_DESCRIPTORS, ...extraSteps],
@@ -133,6 +209,48 @@ export function OnboardingProvider({ children, extraSteps = [], extraContext = E
     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) {
@@ -167,10 +285,32 @@ export function OnboardingProvider({ children, extraSteps = [], extraContext = E
     });
   }, []);
 
+  const markStepSeen = useCallback((id) => {
+    persistSeenStep(id);
+  }, []);
+
   // extraContext is spread last: duplicate core keys intentionally override core values, so apps should use distinct names.
   const ctx = useMemo(
-    () => ({ user, pushState, emailOptedIn, ...extraContext }),
-    [user, pushState, emailOptedIn, extraContext],
+    () => ({
+      user,
+      pushState,
+      emailOptedIn,
+      pwaInstall,
+      pwaInstallEnabled,
+      browserPush: resolvedBrowserPush,
+      seenSteps: seenAtMountRef.current,
+      ...extraContext,
+    }),
+    [
+      user,
+      pushState,
+      emailOptedIn,
+      pwaInstall,
+      pwaInstallEnabled,
+      resolvedBrowserPush,
+      seenAtMountRef.current,
+      extraContext,
+    ],
   );
   const activeSteps = useMemo(() => {
     if (!configLoaded || !user) return [];
@@ -178,8 +318,8 @@ export function OnboardingProvider({ children, extraSteps = [], extraContext = E
   }, [configLoaded, user, descriptors, configMap, ctx, dismissedSet]);
 
   const value = useMemo(
-    () => ({ activeSteps, dismissStep, ctx, configMap, setConfigMap }),
-    [activeSteps, dismissStep, ctx, configMap],
+    () => ({ activeSteps, dismissStep, markStepSeen, ctx, configMap, setConfigMap }),
+    [activeSteps, dismissStep, markStepSeen, ctx, configMap],
   );
 
   return <OnboardingContext.Provider value={value}>{children}</OnboardingContext.Provider>;

package/src/onboarding/OnboardingWizard.jsx

@@ -18,6 +18,7 @@ export function OnboardingWizard() {
   const [completed, setCompleted] = useState(0);
   const activeSteps = onboarding?.activeSteps || [];
   const visibleSteps = activeSteps.filter((step) => !sessionDismissed.has(step.id));
+  const currentStep = visibleSteps[0];
 
   useEffect(() => {
     if (visibleSteps.length > 0 && totalRef.current === null) {
@@ -30,10 +31,13 @@ export function OnboardingWizard() {
     }
   }, [visibleSteps.length]);
 
+  useEffect(() => {
+    if (onboarding && currentStep) onboarding.markStepSeen(currentStep.id);
+  }, [onboarding, currentStep?.id]);
+
   if (!onboarding || visibleSteps.length === 0) return null;
 
   const { dismissStep, ctx } = onboarding;
-  const currentStep = visibleSteps[0];
   const total = totalRef.current || visibleSteps.length;
   const progress = total > 1 ? Math.round((completed / total) * 100) : 0;
   const StepComponent = currentStep.Component;

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

@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 import React from 'react';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { cleanup, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
 
 const onboardingApi = vi.hoisted(() => ({
   getOnboardingStepConfig: vi.fn(),
@@ -23,10 +23,25 @@ function Probe() {
 
 function ActiveStepsProbe() {
   const onboarding = useOnboarding();
-  return <span data-testid="active-steps">{onboarding?.activeSteps.map((step) => step.id).join(',')}</span>;
+  return (
+    <>
+      <span data-testid="active-steps">{onboarding?.activeSteps.map((step) => step.id).join(',')}</span>
+      <span data-testid="push-subscribed">{String(onboarding?.ctx.pushState?.subscribed)}</span>
+    </>
+  );
+}
+
+function MarkStepSeenProbe() {
+  const onboarding = useOnboarding();
+  return (
+    <>
+      <ActiveStepsProbe />
+      <button type="button" onClick={() => onboarding.markStepSeen('browser_push')}>Mark browser push seen</button>
+    </>
+  );
 }
 
-function renderProvider({ extraContext, extraSteps, children = <Probe /> } = {}) {
+function renderProvider({ browserPush, extraContext, extraSteps, pwaInstallEnabled, children = <Probe /> } = {}) {
   return render(
     <AuthContext.Provider value={{
       user: {
@@ -36,7 +51,14 @@ function renderProvider({ extraContext, extraSteps, children = <Probe /> } = {})
         last_name: 'Lovelace',
       },
     }}>
-      <OnboardingProvider extraContext={extraContext} extraSteps={extraSteps}>{children}</OnboardingProvider>
+      <OnboardingProvider
+        extraContext={extraContext}
+        extraSteps={extraSteps}
+        pwaInstallEnabled={pwaInstallEnabled}
+        browserPush={browserPush}
+      >
+        {children}
+      </OnboardingProvider>
     </AuthContext.Provider>,
   );
 }
@@ -106,3 +128,167 @@ describe('OnboardingProvider extra context', () => {
     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');
+  });
+});
+
+describe('OnboardingProvider browser_push configuration', () => {
+  const serviceWorkerDescriptor = Object.getOwnPropertyDescriptor(navigator, 'serviceWorker');
+  const pushManagerDescriptor = Object.getOwnPropertyDescriptor(window, 'PushManager');
+  const localStorageDescriptor = Object.getOwnPropertyDescriptor(window, 'localStorage');
+  const localStorageItems = new Map();
+
+  function installLocalStorage() {
+    Object.defineProperty(window, 'localStorage', {
+      configurable: true,
+      value: {
+        getItem: (key) => localStorageItems.get(key) || null,
+        setItem: (key, value) => localStorageItems.set(key, String(value)),
+        clear: () => localStorageItems.clear(),
+      },
+    });
+  }
+
+  function installPushState(subscribed) {
+    Object.defineProperty(navigator, 'serviceWorker', {
+      configurable: true,
+      value: {
+        ready: Promise.resolve({
+          pushManager: { getSubscription: () => Promise.resolve(subscribed ? {} : null) },
+        }),
+      },
+    });
+    Object.defineProperty(window, 'PushManager', {
+      configurable: true,
+      value: window.PushManager || function PushManager() {},
+    });
+  }
+
+  function restorePushSupport() {
+    if (serviceWorkerDescriptor) {
+      Object.defineProperty(navigator, 'serviceWorker', serviceWorkerDescriptor);
+    } else {
+      delete navigator.serviceWorker;
+    }
+    if (pushManagerDescriptor) {
+      Object.defineProperty(window, 'PushManager', pushManagerDescriptor);
+    } else {
+      delete window.PushManager;
+    }
+  }
+
+  function restoreLocalStorage() {
+    if (localStorageDescriptor) {
+      Object.defineProperty(window, 'localStorage', localStorageDescriptor);
+    } else {
+      delete window.localStorage;
+    }
+  }
+
+  beforeEach(() => {
+    cleanup();
+    vi.clearAllMocks();
+    installLocalStorage();
+    window.localStorage.clear();
+    onboardingApi.getOnboardingStepConfig.mockResolvedValue([]);
+    notificationsApi.getNotificationPreferences.mockResolvedValue({ email_opt_in: false });
+    installPushState(true);
+  });
+
+  afterEach(() => {
+    restorePushSupport();
+    restoreLocalStorage();
+  });
+
+  it('uses any-channel by default and all-channels when explicitly configured', async () => {
+    const defaultRender = renderProvider({ children: <ActiveStepsProbe /> });
+
+    await waitFor(() => expect(screen.getByTestId('push-subscribed').textContent).toBe('true'));
+    expect(screen.getByTestId('active-steps').textContent).not.toContain('browser_push');
+
+    defaultRender.unmount();
+    renderProvider({
+      browserPush: { nagUntil: 'all-channels' },
+      children: <ActiveStepsProbe />,
+    });
+
+    await waitFor(() => expect(screen.getByTestId('push-subscribed').textContent).toBe('true'));
+    expect(screen.getByTestId('active-steps').textContent).toContain('browser_push');
+  });
+
+  it('never shows browser_push when nagUntil is off', async () => {
+    renderProvider({ browserPush: { nagUntil: 'off' }, children: <ActiveStepsProbe /> });
+
+    await waitFor(() => expect(screen.getByTestId('push-subscribed').textContent).toBe('true'));
+    expect(screen.getByTestId('active-steps').textContent).not.toContain('browser_push');
+  });
+
+  it('persists showOnce for the next provider session without hiding the current session step', async () => {
+    installPushState(false);
+    const firstRender = renderProvider({
+      browserPush: { showOnce: true },
+      children: <MarkStepSeenProbe />,
+    });
+
+    await waitFor(() => expect(screen.getByTestId('push-subscribed').textContent).toBe('false'));
+    await waitFor(() => expect(screen.getByTestId('active-steps').textContent).toContain('browser_push'));
+
+    fireEvent.click(screen.getByRole('button', { name: 'Mark browser push seen' }));
+
+    expect(screen.getByTestId('active-steps').textContent).toContain('browser_push');
+    expect(JSON.parse(window.localStorage.getItem('onboarding_seen'))).toContain('browser_push');
+
+    firstRender.unmount();
+    renderProvider({
+      browserPush: { showOnce: true },
+      extraSteps: [{ id: 'provider_loaded', condition: () => true, persistDismissed: false }],
+      children: <ActiveStepsProbe />,
+    });
+
+    await waitFor(() => expect(screen.getByTestId('active-steps').textContent).toContain('provider_loaded'));
+    expect(screen.getByTestId('active-steps').textContent).not.toContain('browser_push');
+  });
+});

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', () => {
@@ -27,12 +28,29 @@ describe('cookie_consent descriptor condition', () => {
 });
 
 describe('browser_push descriptor condition', () => {
-  it('is active when push is supported and either channel remains unconfigured', () => {
+  it('is active by default only when neither supported channel is configured', () => {
+    expect(browserPushDescriptor.condition({
+      pushState: { supported: true, subscribed: false },
+      emailOptedIn: false,
+    })).toBe(true);
     expect(browserPushDescriptor.condition({
       pushState: { supported: true, subscribed: false },
       emailOptedIn: true,
+    })).toBe(false);
+    expect(browserPushDescriptor.condition({
+      pushState: { supported: true, subscribed: true },
+      emailOptedIn: false,
+    })).toBe(false);
+  });
+
+  it('keeps the legacy condition when configured for all-channels', () => {
+    expect(browserPushDescriptor.condition({
+      browserPush: { nagUntil: 'all-channels' },
+      pushState: { supported: true, subscribed: false },
+      emailOptedIn: true,
     })).toBe(true);
     expect(browserPushDescriptor.condition({
+      browserPush: { nagUntil: 'all-channels' },
       pushState: { supported: true, subscribed: true },
       emailOptedIn: false,
     })).toBe(true);
@@ -67,3 +85,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);
+  });
+});