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

package/WORK_ORDERS.md

@@ -0,0 +1,22 @@
+# 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) |
+| `PERF-*` | Performance improvements |
+
+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). |
+| PERF-3B1 | Parallel auth bootstrap after CSRF | Starts auth-methods and current-user concurrently once CSRF is available, while preserving error handling and loading semantics. | 2026-07-19 | done |  | Independent `reviewer` + `sec_reviewer` passes both clean (no findings); one P3 test-coverage gap from the reviewer (missing mirror case: auth-methods rejects, current-user succeeds) closed with an added regression test — 45/45 tests green. Published as 2.10.1 (patch, no interface change) and pinned in jg-ferien alongside its PERF-3A companion WO. |

package/dist/auth/AuthContext.js

@@ -37,18 +37,24 @@ export const AuthProvider = ({ children }) => {
             try {
                 // 1) Ensure CSRF cookie exists using the specific client
                 await ensureCsrfToken();
-                // 2) Load auth methods (public)
-                try {
-                    const methods = await fetchAuthMethods();
+                // 2) Both calls depend on CSRF, but not on each other. Await both settlements
+                // so loading stays true until the complete auth bootstrap has finished.
+                const [methodsResult, userResult] = await Promise.allSettled([
+                    fetchAuthMethods(),
+                    fetchCurrentUser(),
+                ]);
+                // Keep defaults when the public auth-methods request fails.
+                if (methodsResult.status === 'fulfilled') {
+                    const methods = methodsResult.value;
                     if (isMounted && methods && typeof methods === 'object') {
                         setAuthMethods((prev) => (Object.assign(Object.assign({}, prev), methods)));
                     }
                 }
-                catch (_a) {
-                    // Keep defaults; login UI remains usable.
+                // Preserve the previous unauthenticated/error handling for current-user.
+                if (userResult.status === 'rejected') {
+                    throw userResult.reason;
                 }
-                // 3) Load user
-                const data = await fetchCurrentUser();
+                const data = userResult.value;
                 if (isMounted) {
                     setUser(mapUserFromApi(data));
                 }

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';
@@ -31,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,
@@ -75,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'
@@ -100,7 +131,8 @@ function getInitialPwaInstallState() {
 // 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 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);
@@ -108,6 +140,8 @@ export function OnboardingProvider({ children, extraSteps = [], extraContext = E
     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;
@@ -228,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, pwaInstall, pwaInstallEnabled }, extraContext)), [user, pushState, emailOptedIn, pwaInstall, pwaInstallEnabled, 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/package.json

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

package/src/auth/AuthContext.jsx

@@ -79,19 +79,27 @@ export const AuthProvider = ({ children }) => {
         // 1) Ensure CSRF cookie exists using the specific client
         await ensureCsrfToken();
 
-        // 2) Load auth methods (public)
-        try {
-          const methods = await fetchAuthMethods();
+        // 2) Both calls depend on CSRF, but not on each other. Await both settlements
+        // so loading stays true until the complete auth bootstrap has finished.
+        const [methodsResult, userResult] = await Promise.allSettled([
+          fetchAuthMethods(),
+          fetchCurrentUser(),
+        ]);
+
+        // Keep defaults when the public auth-methods request fails.
+        if (methodsResult.status === 'fulfilled') {
+          const methods = methodsResult.value;
           if (isMounted && methods && typeof methods === 'object') {
             setAuthMethods((prev) => ({ ...prev, ...methods }));
           }
-        } catch {
-          // Keep defaults; login UI remains usable.
         }
 
-        // 3) Load user
-        const data = await fetchCurrentUser();
-        
+        // Preserve the previous unauthenticated/error handling for current-user.
+        if (userResult.status === 'rejected') {
+          throw userResult.reason;
+        }
+
+        const data = userResult.value;
         if (isMounted) {
           setUser(mapUserFromApi(data));
         }

package/src/onboarding/OnboardingProvider.jsx

@@ -4,6 +4,7 @@ import React, {
   useContext,
   useEffect,
   useMemo,
+  useRef,
   useState,
 } from 'react';
 import { AuthContext } from '../auth/AuthContext';
@@ -36,10 +37,15 @@ 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,
@@ -82,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'
@@ -110,9 +136,14 @@ function getInitialPwaInstallState() {
 // 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, pwaInstallEnabled = false,
+  children,
+  extraSteps = [],
+  extraContext = EMPTY_EXTRA_CONTEXT,
+  pwaInstallEnabled = false,
+  browserPush = EMPTY_BROWSER_PUSH,
 }) {
   const { user } = useContext(AuthContext);
   const [configMap, setConfigMap] = useState({});
@@ -121,6 +152,12 @@ export function OnboardingProvider({
   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],
@@ -248,12 +285,32 @@ export function OnboardingProvider({
     });
   }, []);
 
+  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, pwaInstall, pwaInstallEnabled, ...extraContext,
+      user,
+      pushState,
+      emailOptedIn,
+      pwaInstall,
+      pwaInstallEnabled,
+      browserPush: resolvedBrowserPush,
+      seenSteps: seenAtMountRef.current,
+      ...extraContext,
     }),
-    [user, pushState, emailOptedIn, pwaInstall, pwaInstallEnabled, extraContext],
+    [
+      user,
+      pushState,
+      emailOptedIn,
+      pwaInstall,
+      pwaInstallEnabled,
+      resolvedBrowserPush,
+      seenAtMountRef.current,
+      extraContext,
+    ],
   );
   const activeSteps = useMemo(() => {
     if (!configLoaded || !user) return [];
@@ -261,8 +318,8 @@ export function OnboardingProvider({
   }, [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/tests/AuthContext.test.jsx

@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 import React, { useContext } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { render, screen, waitFor } from '@testing-library/react';
+import { cleanup, render, screen, waitFor } from '@testing-library/react';
 
 const apiClient = vi.hoisted(() => ({
   ensureCsrfToken: vi.fn().mockResolvedValue(undefined),
@@ -19,17 +19,19 @@ vi.mock('../src/auth/ReauthModal', () => ({ ReauthModal: () => null }));
 import { AuthContext, AuthProvider } from '../src/auth/AuthContext';
 
 function Probe() {
-  const { user, refreshUser } = useContext(AuthContext);
+  const { user, loading, refreshUser } = useContext(AuthContext);
   return (
     <div>
       <span data-testid="first-name">{user?.first_name || ''}</span>
+      <span data-testid="loading">{String(loading)}</span>
       <button type="button" onClick={() => refreshUser()}>refresh</button>
     </div>
   );
 }
 
-describe('AuthContext refreshUser', () => {
+describe('AuthContext', () => {
   beforeEach(() => {
+    cleanup();
     vi.clearAllMocks();
   });
 
@@ -47,4 +49,81 @@ describe('AuthContext refreshUser', () => {
     await waitFor(() => expect(screen.getByTestId('first-name').textContent).toBe('Grace'));
     expect(authApi.fetchCurrentUser).toHaveBeenCalledTimes(2);
   });
+
+  it('starts auth methods and current user together after CSRF, then waits for both', async () => {
+    let resolveCsrf;
+    let resolveMethods;
+    let resolveUser;
+    const callOrder = [];
+
+    apiClient.ensureCsrfToken.mockImplementation(() => new Promise((resolve) => {
+      resolveCsrf = resolve;
+    }));
+    authApi.fetchAuthMethods.mockImplementation(() => {
+      callOrder.push('auth-methods');
+      return new Promise((resolve) => {
+        resolveMethods = resolve;
+      });
+    });
+    authApi.fetchCurrentUser.mockImplementation(() => {
+      callOrder.push('current-user');
+      return new Promise((resolve) => {
+        resolveUser = resolve;
+      });
+    });
+
+    render(<AuthProvider><Probe /></AuthProvider>);
+
+    expect(callOrder).toEqual([]);
+    resolveCsrf();
+
+    await waitFor(() => expect(callOrder).toEqual(['auth-methods', 'current-user']));
+    expect(screen.getByTestId('loading').textContent).toBe('true');
+
+    resolveUser({ id: 1, first_name: 'Ada' });
+    await Promise.resolve();
+    expect(screen.getByTestId('loading').textContent).toBe('true');
+
+    resolveMethods({ password_login: false });
+    await waitFor(() => expect(screen.getByTestId('loading').textContent).toBe('false'));
+    expect(screen.getByTestId('first-name').textContent).toBe('Ada');
+  });
+
+  it('still sets the user when auth-methods fails but current-user succeeds', async () => {
+    let resolveUser;
+
+    apiClient.ensureCsrfToken.mockResolvedValue(undefined);
+    authApi.fetchAuthMethods.mockRejectedValue(new Error('auth-methods unavailable'));
+    authApi.fetchCurrentUser.mockImplementation(() => new Promise((resolve) => {
+      resolveUser = resolve;
+    }));
+
+    render(<AuthProvider><Probe /></AuthProvider>);
+
+    await waitFor(() => expect(authApi.fetchAuthMethods).toHaveBeenCalledTimes(1));
+    expect(screen.getByTestId('loading').textContent).toBe('true');
+
+    resolveUser({ id: 1, first_name: 'Ada' });
+    await waitFor(() => expect(screen.getByTestId('loading').textContent).toBe('false'));
+    expect(screen.getByTestId('first-name').textContent).toBe('Ada');
+  });
+
+  it('preserves the unauthenticated state after a current-user failure', async () => {
+    let resolveMethods;
+
+    apiClient.ensureCsrfToken.mockResolvedValue(undefined);
+    authApi.fetchAuthMethods.mockImplementation(() => new Promise((resolve) => {
+      resolveMethods = resolve;
+    }));
+    authApi.fetchCurrentUser.mockRejectedValue(new Error('Unauthenticated'));
+
+    render(<AuthProvider><Probe /></AuthProvider>);
+
+    await waitFor(() => expect(authApi.fetchCurrentUser).toHaveBeenCalledTimes(1));
+    expect(screen.getByTestId('loading').textContent).toBe('true');
+
+    resolveMethods({ password_login: false });
+    await waitFor(() => expect(screen.getByTestId('loading').textContent).toBe('false'));
+    expect(screen.getByTestId('first-name').textContent).toBe('');
+  });
 });

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 renderProvider({ extraContext, extraSteps, pwaInstallEnabled, children = <Probe /> } = {}) {
+function MarkStepSeenProbe() {
+  const onboarding = useOnboarding();
+  return (
+    <>
+      <ActiveStepsProbe />
+      <button type="button" onClick={() => onboarding.markStepSeen('browser_push')}>Mark browser push seen</button>
+    </>
+  );
+}
+
+function renderProvider({ browserPush, extraContext, extraSteps, pwaInstallEnabled, children = <Probe /> } = {}) {
   return render(
     <AuthContext.Provider value={{
       user: {
@@ -40,6 +55,7 @@ function renderProvider({ extraContext, extraSteps, pwaInstallEnabled, children
         extraContext={extraContext}
         extraSteps={extraSteps}
         pwaInstallEnabled={pwaInstallEnabled}
+        browserPush={browserPush}
       >
         {children}
       </OnboardingProvider>
@@ -158,3 +174,121 @@ describe('OnboardingProvider pwa_install capture', () => {
     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

@@ -28,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);