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

package/WORK_ORDERS.md

@@ -10,6 +10,7 @@ rules are defined centrally in `webapps/AGENTS.md` → "Work-Order Register".
 |---|---|
 | `ONB-*` | Onboarding wizard (steps, conditions, persistence) |
 | `PERF-*` | Performance improvements |
+| `NOTIF-*` | Shared notifications platform (dcm register is canonical; this repo's rows are its ucm-side WOs) |
 
 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.
@@ -19,4 +20,5 @@ prefixed ID; never reuse a bare flat number across workstreams.
 | 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. |
+| 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 | ee89329 | 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. |
+| NOTIF-6 | NotificationsProvider + bell on canonical dcm feed/* API | Single-WS-owner `NotificationsProvider`/`useNotifications` (initial REST seed via `feedApi.js` + one `/ws/notifications/` socket, reconnect w/ backoff) + generic MUI `NotificationBell`; additive exports only | 2026-07-27 | done | 6c63fb9 | Codex-built direct (no nesting), independent `reviewer`: single-WS-owner invariant traced clean (no way to break it — `authenticated`/`replaceNotifications`/`refresh` all referentially stable across unrelated re-renders, re-render test is genuine not a no-op). R1 (P2, real bug): the `notification.status` WS handler patched item flags but never adjusted `unreadCount`, so the badge went stale after a cross-tab/cross-device mark — the test had locked in the stale count as expected behavior. Fixed: delta computed from before/after unread state on the WS patch path, mirroring `mark()`'s own logic; test corrected + a new cross-tab regression test added. 57 passing, build clean. No new npm dependency. Full history + backend contract: dcm's `WORK_ORDERS.md`/`docs/design/notifications-platform.md`. Publishes ucm 2.11.0 |

package/dist/i18n/notificationsTranslations.js

@@ -1,4 +1,7 @@
 export const notificationsTranslations = {
+    'NotificationBell.TITLE': { de: 'Benachrichtigungen', fr: 'Notifications', en: 'Notifications', sw: 'Arifa' },
+    'NotificationBell.EMPTY': { de: 'Keine Benachrichtigungen vorhanden.', fr: 'Aucune notification.', en: 'No notifications.', sw: 'Hakuna arifa.' },
+    'NotificationBell.MARK_ALL': { de: 'Alle als gelesen markieren', fr: 'Tout marquer comme lu', en: 'Mark all as read', sw: 'Weka zote alama kuwa zimesomwa' },
     'NotificationSettings.TITLE': { de: 'Benachrichtigungen', fr: 'Notifications', en: 'Notifications', sw: 'Arifa' },
     'NotificationSettings.SUBTITLE': { de: 'Lege fest, wie du informiert werden möchtest.', fr: 'Choisissez comment vous souhaitez être informé.', en: 'Choose how you want to be notified.', sw: 'Chagua jinsi unavyotaka kuarifiwa.' },
     'NotificationSettings.LOAD_ERROR': { de: 'Benachrichtigungseinstellungen konnten nicht geladen werden.', fr: 'Impossible de charger les paramètres de notification.', en: 'Notification settings could not be loaded.', sw: 'Mipangilio ya arifa haikuweza kupakiwa.' },

package/dist/index.js

@@ -32,6 +32,9 @@ export { authTranslations } from './i18n/authTranslations';
 // --- 7. Notifications ---
 export { NotificationSettings } from './notifications/NotificationSettings';
 export * from './notifications/api';
+export { NotificationsProvider, useNotifications } from './notifications/NotificationsProvider';
+export { NotificationBell } from './notifications/NotificationBell';
+export { getNotificationFeed, getUnreadCount, markNotifications } from './notifications/feedApi';
 // --- 8. Onboarding ---
 export * from './onboarding/api';
 export { selectActiveSteps } from './onboarding/stepSelection';

package/dist/notifications/NotificationBell.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState } from 'react';
+import NotificationsIcon from '@mui/icons-material/Notifications';
+import { Badge, Box, Button, IconButton, List, ListItemButton, ListItemText, Menu, Typography, } from '@mui/material';
+import { useTranslation } from 'react-i18next';
+import { useNotifications } from './NotificationsProvider';
+export function NotificationBell({ resolveLink }) {
+    const { t } = useTranslation();
+    const { notifications, unreadCount, markSeen } = useNotifications();
+    const [anchorEl, setAnchorEl] = useState(null);
+    const open = Boolean(anchorEl);
+    const unreadIds = notifications
+        .filter((notification) => !notification.seen && !notification.dismissed && notification.id != null)
+        .map((notification) => notification.id);
+    const handleItemClick = (notification) => {
+        var _a;
+        if (notification.id != null)
+            markSeen([notification.id]);
+        setAnchorEl(null);
+        if (resolveLink && ((_a = notification.content) === null || _a === void 0 ? void 0 : _a.link))
+            resolveLink(notification.content.link);
+    };
+    return (_jsxs(_Fragment, { children: [_jsx(IconButton, { "aria-label": t('NotificationBell.TITLE'), color: "inherit", onClick: (event) => setAnchorEl(event.currentTarget), children: _jsx(Badge, { badgeContent: unreadCount, color: "error", max: 99, children: _jsx(NotificationsIcon, {}) }) }), _jsx(Menu, { anchorEl: anchorEl, anchorOrigin: { horizontal: 'right', vertical: 'bottom' }, onClose: () => setAnchorEl(null), open: open, transformOrigin: { horizontal: 'right', vertical: 'top' }, children: _jsxs(Box, { sx: { minWidth: 320 }, children: [_jsxs(Box, { sx: { alignItems: 'center', display: 'flex', justifyContent: 'space-between', px: 2, py: 1 }, children: [_jsx(Typography, { variant: "subtitle1", children: t('NotificationBell.TITLE') }), unreadIds.length > 0 && (_jsx(Button, { onClick: () => markSeen(unreadIds), size: "small", children: t('NotificationBell.MARK_ALL') }))] }), notifications.length === 0 ? (_jsx(Typography, { sx: { px: 2, py: 2 }, variant: "body2", children: t('NotificationBell.EMPTY') })) : (_jsx(List, { dense: true, disablePadding: true, children: notifications.map((notification) => {
+                                var _a, _b, _c, _d;
+                                return (_jsx(ListItemButton, { onClick: () => handleItemClick(notification), children: _jsx(ListItemText, { primary: t((_a = notification.content) === null || _a === void 0 ? void 0 : _a.title_key, ((_b = notification.content) === null || _b === void 0 ? void 0 : _b.params) || {}), secondary: ((_c = notification.content) === null || _c === void 0 ? void 0 : _c.body_key)
+                                            ? t(notification.content.body_key, notification.content.params || {})
+                                            : undefined, slotProps: { primary: { fontWeight: notification.seen || notification.dismissed ? 'regular' : 'bold' } } }) }, (_d = notification.id) !== null && _d !== void 0 ? _d : notification.notification_id));
+                            }) }))] }) })] }));
+}

package/dist/notifications/NotificationsProvider.js

@@ -0,0 +1,194 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { AuthContext } from '../auth/AuthContext';
+import { getNotificationFeed, getUnreadCount, markNotifications } from './feedApi';
+const INITIAL_BACKOFF_MS = 1000;
+const MAX_BACKOFF_MS = 30000;
+const NotificationsContext = createContext(null);
+function normalizeNotification(notification) {
+    var _a, _b, _c;
+    return Object.assign(Object.assign({}, notification), { content: notification.content || {}, seen: Boolean((_a = notification.seen) !== null && _a !== void 0 ? _a : notification.seen_at), dismissed: Boolean((_b = notification.dismissed) !== null && _b !== void 0 ? _b : notification.dismissed_at), done: Boolean((_c = notification.done) !== null && _c !== void 0 ? _c : notification.done_at) });
+}
+function normalizeNotificationPush(data) {
+    var _a, _b;
+    return normalizeNotification({
+        id: (_b = (_a = data.id) !== null && _a !== void 0 ? _a : data.recipient_id) !== null && _b !== void 0 ? _b : data.notification_id,
+        notification_id: data.notification_id,
+        notification_type: data.type,
+        content: data.content || {},
+        created_at: data.created_at,
+        seen_at: null,
+        dismissed_at: null,
+        done_at: null,
+    });
+}
+function getWebSocketUrl(wsUrlBase) {
+    if (wsUrlBase) {
+        return new URL('/ws/notifications/', wsUrlBase).toString();
+    }
+    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    return `${protocol}//${window.location.host}/ws/notifications/`;
+}
+function patchStatus(notification, status) {
+    const seen = Boolean(status.seen);
+    const dismissed = Boolean(status.dismissed);
+    const done = Boolean(status.done);
+    return Object.assign(Object.assign({}, notification), { seen,
+        dismissed,
+        done, seen_at: seen ? notification.seen_at || true : null, dismissed_at: dismissed ? notification.dismissed_at || true : null, done_at: done ? notification.done_at || true : null });
+}
+export function NotificationsProvider({ children, wsUrlBase }) {
+    const auth = useContext(AuthContext);
+    const authenticated = Boolean(auth === null || auth === void 0 ? void 0 : auth.user);
+    const [notifications, setNotifications] = useState([]);
+    const [unreadCount, setUnreadCount] = useState(0);
+    const notificationsRef = useRef([]);
+    const socketRef = useRef(null);
+    const replaceNotifications = useCallback((nextNotifications) => {
+        notificationsRef.current = nextNotifications;
+        setNotifications(nextNotifications);
+    }, []);
+    const refresh = useCallback(async () => {
+        if (!authenticated) {
+            replaceNotifications([]);
+            setUnreadCount(0);
+            return { notifications: [], unreadCount: 0 };
+        }
+        const [feed, unread] = await Promise.all([getNotificationFeed(), getUnreadCount()]);
+        const nextNotifications = (feed.results || []).map(normalizeNotification);
+        const nextUnreadCount = unread.count || 0;
+        replaceNotifications(nextNotifications);
+        setUnreadCount(nextUnreadCount);
+        return { notifications: nextNotifications, unreadCount: nextUnreadCount };
+    }, [authenticated, replaceNotifications]);
+    useEffect(() => {
+        if (!authenticated) {
+            replaceNotifications([]);
+            setUnreadCount(0);
+            return undefined;
+        }
+        let active = true;
+        let reconnectTimer = null;
+        let backoffMs = INITIAL_BACKOFF_MS;
+        const patchNotifications = (updater) => {
+            const nextNotifications = updater(notificationsRef.current);
+            replaceNotifications(nextNotifications);
+        };
+        const handleMessage = (event) => {
+            let data;
+            try {
+                data = JSON.parse(event.data);
+            }
+            catch (_a) {
+                return;
+            }
+            if (data.type === 'notification.status') {
+                let unreadDelta = 0;
+                patchNotifications((current) => current.map((notification) => {
+                    if (notification.notification_id !== data.notification_id)
+                        return notification;
+                    const wasUnread = !notification.seen && !notification.dismissed;
+                    const patched = patchStatus(notification, data.status || {});
+                    const isUnread = !patched.seen && !patched.dismissed;
+                    if (wasUnread !== isUnread) {
+                        unreadDelta += isUnread ? 1 : -1;
+                    }
+                    return patched;
+                }));
+                if (unreadDelta) {
+                    setUnreadCount((count) => Math.max(0, count + unreadDelta));
+                }
+                return;
+            }
+            const pushedNotification = normalizeNotificationPush(data);
+            patchNotifications((current) => [pushedNotification, ...current]);
+            setUnreadCount((count) => count + 1);
+        };
+        const connect = () => {
+            if (!active || socketRef.current)
+                return;
+            const socket = new WebSocket(getWebSocketUrl(wsUrlBase));
+            socketRef.current = socket;
+            socket.onopen = () => {
+                backoffMs = INITIAL_BACKOFF_MS;
+            };
+            socket.onmessage = handleMessage;
+            socket.onerror = () => {
+                socket.close();
+            };
+            socket.onclose = () => {
+                if (socketRef.current === socket) {
+                    socketRef.current = null;
+                }
+                if (!active || reconnectTimer)
+                    return;
+                reconnectTimer = setTimeout(() => {
+                    reconnectTimer = null;
+                    connect();
+                }, backoffMs);
+                backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+            };
+        };
+        const seedAndConnect = async () => {
+            try {
+                await refresh();
+            }
+            catch (_a) {
+                // The live stream remains useful if the initial REST request is temporarily unavailable.
+            }
+            if (active)
+                connect();
+        };
+        seedAndConnect();
+        return () => {
+            active = false;
+            clearTimeout(reconnectTimer);
+            const socket = socketRef.current;
+            socketRef.current = null;
+            if (socket)
+                socket.close();
+        };
+    }, [authenticated, refresh, replaceNotifications, wsUrlBase]);
+    const mark = useCallback((action, ids) => {
+        const selectedIds = Array.isArray(ids) ? ids : [];
+        const selected = new Set(selectedIds);
+        const current = notificationsRef.current;
+        let unreadDelta = 0;
+        const nextNotifications = current.map((notification) => {
+            if (!selected.has(notification.id))
+                return notification;
+            const wasUnread = !notification.seen && !notification.dismissed;
+            if ((action === 'seen' || action === 'dismissed') && wasUnread) {
+                unreadDelta += 1;
+            }
+            return patchStatus(notification, {
+                seen: action === 'seen' ? true : notification.seen,
+                dismissed: action === 'dismissed' ? true : notification.dismissed,
+                done: action === 'done' ? true : notification.done,
+            });
+        });
+        replaceNotifications(nextNotifications);
+        if (unreadDelta) {
+            setUnreadCount((count) => Math.max(0, count - unreadDelta));
+        }
+        return markNotifications({ action, ids: selectedIds });
+    }, [replaceNotifications]);
+    const markSeen = useCallback((ids) => mark('seen', ids), [mark]);
+    const markDismissed = useCallback((ids) => mark('dismissed', ids), [mark]);
+    const markDone = useCallback((ids) => mark('done', ids), [mark]);
+    return (_jsx(NotificationsContext.Provider, { value: {
+            notifications,
+            unreadCount,
+            markSeen,
+            markDismissed,
+            markDone,
+            refresh,
+        }, children: children }));
+}
+export function useNotifications() {
+    const context = useContext(NotificationsContext);
+    if (!context) {
+        throw new Error('useNotifications must be used within a NotificationsProvider');
+    }
+    return context;
+}

package/dist/notifications/feedApi.js

@@ -0,0 +1,15 @@
+import apiClient from '../auth/apiClient';
+export async function getNotificationFeed({ status } = {}) {
+    const response = await apiClient.get('/api/notifications/feed/', {
+        params: status ? { status } : undefined,
+    });
+    return response.data;
+}
+export async function getUnreadCount() {
+    const response = await apiClient.get('/api/notifications/feed/unread-count/');
+    return response.data;
+}
+export async function markNotifications({ action, ids }) {
+    const response = await apiClient.post('/api/notifications/feed/mark/', { action, ids });
+    return response.data;
+}

package/package.json

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

package/src/i18n/notificationsTranslations.ts

@@ -1,4 +1,7 @@
 export const notificationsTranslations = {
+  'NotificationBell.TITLE': { de: 'Benachrichtigungen', fr: 'Notifications', en: 'Notifications', sw: 'Arifa' },
+  'NotificationBell.EMPTY': { de: 'Keine Benachrichtigungen vorhanden.', fr: 'Aucune notification.', en: 'No notifications.', sw: 'Hakuna arifa.' },
+  'NotificationBell.MARK_ALL': { de: 'Alle als gelesen markieren', fr: 'Tout marquer comme lu', en: 'Mark all as read', sw: 'Weka zote alama kuwa zimesomwa' },
   'NotificationSettings.TITLE': { de: 'Benachrichtigungen', fr: 'Notifications', en: 'Notifications', sw: 'Arifa' },
   'NotificationSettings.SUBTITLE': { de: 'Lege fest, wie du informiert werden möchtest.', fr: 'Choisissez comment vous souhaitez être informé.', en: 'Choose how you want to be notified.', sw: 'Chagua jinsi unavyotaka kuarifiwa.' },
   'NotificationSettings.LOAD_ERROR': { de: 'Benachrichtigungseinstellungen konnten nicht geladen werden.', fr: 'Impossible de charger les paramètres de notification.', en: 'Notification settings could not be loaded.', sw: 'Mipangilio ya arifa haikuweza kupakiwa.' },

package/src/index.js

@@ -45,6 +45,9 @@ export { authTranslations } from './i18n/authTranslations';
 // --- 7. Notifications ---
 export { NotificationSettings } from './notifications/NotificationSettings';
 export * from './notifications/api';
+export { NotificationsProvider, useNotifications } from './notifications/NotificationsProvider';
+export { NotificationBell } from './notifications/NotificationBell';
+export { getNotificationFeed, getUnreadCount, markNotifications } from './notifications/feedApi';
 
 // --- 8. Onboarding ---
 export * from './onboarding/api';

package/src/notifications/NotificationBell.jsx

@@ -0,0 +1,84 @@
+import { useState } from 'react';
+
+import NotificationsIcon from '@mui/icons-material/Notifications';
+import {
+  Badge,
+  Box,
+  Button,
+  IconButton,
+  List,
+  ListItemButton,
+  ListItemText,
+  Menu,
+  Typography,
+} from '@mui/material';
+import { useTranslation } from 'react-i18next';
+
+import { useNotifications } from './NotificationsProvider';
+
+export function NotificationBell({ resolveLink }) {
+  const { t } = useTranslation();
+  const { notifications, unreadCount, markSeen } = useNotifications();
+  const [anchorEl, setAnchorEl] = useState(null);
+  const open = Boolean(anchorEl);
+  const unreadIds = notifications
+    .filter((notification) => !notification.seen && !notification.dismissed && notification.id != null)
+    .map((notification) => notification.id);
+
+  const handleItemClick = (notification) => {
+    if (notification.id != null) markSeen([notification.id]);
+    setAnchorEl(null);
+    if (resolveLink && notification.content?.link) resolveLink(notification.content.link);
+  };
+
+  return (
+    <>
+      <IconButton
+        aria-label={t('NotificationBell.TITLE')}
+        color="inherit"
+        onClick={(event) => setAnchorEl(event.currentTarget)}
+      >
+        <Badge badgeContent={unreadCount} color="error" max={99}>
+          <NotificationsIcon />
+        </Badge>
+      </IconButton>
+      <Menu
+        anchorEl={anchorEl}
+        anchorOrigin={{ horizontal: 'right', vertical: 'bottom' }}
+        onClose={() => setAnchorEl(null)}
+        open={open}
+        transformOrigin={{ horizontal: 'right', vertical: 'top' }}
+      >
+        <Box sx={{ minWidth: 320 }}>
+          <Box sx={{ alignItems: 'center', display: 'flex', justifyContent: 'space-between', px: 2, py: 1 }}>
+            <Typography variant="subtitle1">{t('NotificationBell.TITLE')}</Typography>
+            {unreadIds.length > 0 && (
+              <Button onClick={() => markSeen(unreadIds)} size="small">
+                {t('NotificationBell.MARK_ALL')}
+              </Button>
+            )}
+          </Box>
+          {notifications.length === 0 ? (
+            <Typography sx={{ px: 2, py: 2 }} variant="body2">
+              {t('NotificationBell.EMPTY')}
+            </Typography>
+          ) : (
+            <List dense disablePadding>
+              {notifications.map((notification) => (
+                <ListItemButton key={notification.id ?? notification.notification_id} onClick={() => handleItemClick(notification)}>
+                  <ListItemText
+                    primary={t(notification.content?.title_key, notification.content?.params || {})}
+                    secondary={notification.content?.body_key
+                      ? t(notification.content.body_key, notification.content.params || {})
+                      : undefined}
+                    slotProps={{ primary: { fontWeight: notification.seen || notification.dismissed ? 'regular' : 'bold' } }}
+                  />
+                </ListItemButton>
+              ))}
+            </List>
+          )}
+        </Box>
+      </Menu>
+    </>
+  );
+}

package/src/notifications/NotificationsProvider.jsx

@@ -0,0 +1,232 @@
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
+
+import { AuthContext } from '../auth/AuthContext';
+import { getNotificationFeed, getUnreadCount, markNotifications } from './feedApi';
+
+const INITIAL_BACKOFF_MS = 1_000;
+const MAX_BACKOFF_MS = 30_000;
+
+const NotificationsContext = createContext(null);
+
+function normalizeNotification(notification) {
+  return {
+    ...notification,
+    content: notification.content || {},
+    seen: Boolean(notification.seen ?? notification.seen_at),
+    dismissed: Boolean(notification.dismissed ?? notification.dismissed_at),
+    done: Boolean(notification.done ?? notification.done_at),
+  };
+}
+
+function normalizeNotificationPush(data) {
+  return normalizeNotification({
+    id: data.id ?? data.recipient_id ?? data.notification_id,
+    notification_id: data.notification_id,
+    notification_type: data.type,
+    content: data.content || {},
+    created_at: data.created_at,
+    seen_at: null,
+    dismissed_at: null,
+    done_at: null,
+  });
+}
+
+function getWebSocketUrl(wsUrlBase) {
+  if (wsUrlBase) {
+    return new URL('/ws/notifications/', wsUrlBase).toString();
+  }
+
+  const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+  return `${protocol}//${window.location.host}/ws/notifications/`;
+}
+
+function patchStatus(notification, status) {
+  const seen = Boolean(status.seen);
+  const dismissed = Boolean(status.dismissed);
+  const done = Boolean(status.done);
+
+  return {
+    ...notification,
+    seen,
+    dismissed,
+    done,
+    seen_at: seen ? notification.seen_at || true : null,
+    dismissed_at: dismissed ? notification.dismissed_at || true : null,
+    done_at: done ? notification.done_at || true : null,
+  };
+}
+
+export function NotificationsProvider({ children, wsUrlBase }) {
+  const auth = useContext(AuthContext);
+  const authenticated = Boolean(auth?.user);
+  const [notifications, setNotifications] = useState([]);
+  const [unreadCount, setUnreadCount] = useState(0);
+  const notificationsRef = useRef([]);
+  const socketRef = useRef(null);
+
+  const replaceNotifications = useCallback((nextNotifications) => {
+    notificationsRef.current = nextNotifications;
+    setNotifications(nextNotifications);
+  }, []);
+
+  const refresh = useCallback(async () => {
+    if (!authenticated) {
+      replaceNotifications([]);
+      setUnreadCount(0);
+      return { notifications: [], unreadCount: 0 };
+    }
+
+    const [feed, unread] = await Promise.all([getNotificationFeed(), getUnreadCount()]);
+    const nextNotifications = (feed.results || []).map(normalizeNotification);
+    const nextUnreadCount = unread.count || 0;
+    replaceNotifications(nextNotifications);
+    setUnreadCount(nextUnreadCount);
+    return { notifications: nextNotifications, unreadCount: nextUnreadCount };
+  }, [authenticated, replaceNotifications]);
+
+  useEffect(() => {
+    if (!authenticated) {
+      replaceNotifications([]);
+      setUnreadCount(0);
+      return undefined;
+    }
+
+    let active = true;
+    let reconnectTimer = null;
+    let backoffMs = INITIAL_BACKOFF_MS;
+
+    const patchNotifications = (updater) => {
+      const nextNotifications = updater(notificationsRef.current);
+      replaceNotifications(nextNotifications);
+    };
+
+    const handleMessage = (event) => {
+      let data;
+      try {
+        data = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+
+      if (data.type === 'notification.status') {
+        let unreadDelta = 0;
+        patchNotifications((current) => current.map((notification) => {
+          if (notification.notification_id !== data.notification_id) return notification;
+
+          const wasUnread = !notification.seen && !notification.dismissed;
+          const patched = patchStatus(notification, data.status || {});
+          const isUnread = !patched.seen && !patched.dismissed;
+          if (wasUnread !== isUnread) {
+            unreadDelta += isUnread ? 1 : -1;
+          }
+          return patched;
+        }));
+        if (unreadDelta) {
+          setUnreadCount((count) => Math.max(0, count + unreadDelta));
+        }
+        return;
+      }
+
+      const pushedNotification = normalizeNotificationPush(data);
+      patchNotifications((current) => [pushedNotification, ...current]);
+      setUnreadCount((count) => count + 1);
+    };
+
+    const connect = () => {
+      if (!active || socketRef.current) return;
+
+      const socket = new WebSocket(getWebSocketUrl(wsUrlBase));
+      socketRef.current = socket;
+
+      socket.onopen = () => {
+        backoffMs = INITIAL_BACKOFF_MS;
+      };
+      socket.onmessage = handleMessage;
+      socket.onerror = () => {
+        socket.close();
+      };
+      socket.onclose = () => {
+        if (socketRef.current === socket) {
+          socketRef.current = null;
+        }
+        if (!active || reconnectTimer) return;
+        reconnectTimer = setTimeout(() => {
+          reconnectTimer = null;
+          connect();
+        }, backoffMs);
+        backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+      };
+    };
+
+    const seedAndConnect = async () => {
+      try {
+        await refresh();
+      } catch {
+        // The live stream remains useful if the initial REST request is temporarily unavailable.
+      }
+      if (active) connect();
+    };
+
+    seedAndConnect();
+
+    return () => {
+      active = false;
+      clearTimeout(reconnectTimer);
+      const socket = socketRef.current;
+      socketRef.current = null;
+      if (socket) socket.close();
+    };
+  }, [authenticated, refresh, replaceNotifications, wsUrlBase]);
+
+  const mark = useCallback((action, ids) => {
+    const selectedIds = Array.isArray(ids) ? ids : [];
+    const selected = new Set(selectedIds);
+    const current = notificationsRef.current;
+    let unreadDelta = 0;
+    const nextNotifications = current.map((notification) => {
+      if (!selected.has(notification.id)) return notification;
+
+      const wasUnread = !notification.seen && !notification.dismissed;
+      if ((action === 'seen' || action === 'dismissed') && wasUnread) {
+        unreadDelta += 1;
+      }
+
+      return patchStatus(notification, {
+        seen: action === 'seen' ? true : notification.seen,
+        dismissed: action === 'dismissed' ? true : notification.dismissed,
+        done: action === 'done' ? true : notification.done,
+      });
+    });
+
+    replaceNotifications(nextNotifications);
+    if (unreadDelta) {
+      setUnreadCount((count) => Math.max(0, count - unreadDelta));
+    }
+    return markNotifications({ action, ids: selectedIds });
+  }, [replaceNotifications]);
+
+  const markSeen = useCallback((ids) => mark('seen', ids), [mark]);
+  const markDismissed = useCallback((ids) => mark('dismissed', ids), [mark]);
+  const markDone = useCallback((ids) => mark('done', ids), [mark]);
+
+  return (
+    <NotificationsContext.Provider value={{
+      notifications,
+      unreadCount,
+      markSeen,
+      markDismissed,
+      markDone,
+      refresh,
+    }}>
+      {children}
+    </NotificationsContext.Provider>
+  );
+}
+
+export function useNotifications() {
+  const context = useContext(NotificationsContext);
+  if (!context) {
+    throw new Error('useNotifications must be used within a NotificationsProvider');
+  }
+  return context;
+}

package/src/notifications/feedApi.js

@@ -0,0 +1,18 @@
+import apiClient from '../auth/apiClient';
+
+export async function getNotificationFeed({ status } = {}) {
+  const response = await apiClient.get('/api/notifications/feed/', {
+    params: status ? { status } : undefined,
+  });
+  return response.data;
+}
+
+export async function getUnreadCount() {
+  const response = await apiClient.get('/api/notifications/feed/unread-count/');
+  return response.data;
+}
+
+export async function markNotifications({ action, ids }) {
+  const response = await apiClient.post('/api/notifications/feed/mark/', { action, ids });
+  return response.data;
+}

package/tests/NotificationBell.test.jsx

@@ -0,0 +1,60 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+
+const notifications = vi.hoisted(() => ({
+  useNotifications: vi.fn(),
+}));
+const translation = vi.hoisted(() => ({
+  t: vi.fn((key) => `translated:${key}`),
+}));
+
+vi.mock('../src/notifications/NotificationsProvider', () => notifications);
+vi.mock('react-i18next', () => ({ useTranslation: () => translation }));
+
+import { NotificationBell } from '../src/notifications/NotificationBell';
+
+describe('NotificationBell', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    notifications.useNotifications.mockReturnValue({
+      unreadCount: 2,
+      markSeen: vi.fn(),
+      notifications: [{
+        id: 7,
+        notification_id: 70,
+        seen: false,
+        dismissed: false,
+        content: {
+          title_key: 'domain.notification.title',
+          body_key: 'domain.notification.body',
+          params: { name: 'Ada' },
+          link: '/payments/7',
+        },
+      }],
+    });
+  });
+
+  it('renders the unread badge, translates item content, and handles item navigation', () => {
+    const resolveLink = vi.fn();
+    render(<NotificationBell resolveLink={resolveLink} />);
+
+    expect(screen.getByText('2')).toBeTruthy();
+    fireEvent.click(screen.getByRole('button', { name: 'translated:NotificationBell.TITLE' }));
+
+    expect(screen.getByText('translated:domain.notification.title')).toBeTruthy();
+    expect(screen.getByText('translated:domain.notification.body')).toBeTruthy();
+    expect(translation.t).toHaveBeenCalledWith('domain.notification.title', { name: 'Ada' });
+    expect(translation.t).toHaveBeenCalledWith('domain.notification.body', { name: 'Ada' });
+
+    fireEvent.click(screen.getByText('translated:domain.notification.title'));
+
+    expect(notifications.useNotifications.mock.results[0].value.markSeen).toHaveBeenCalledWith([7]);
+    expect(resolveLink).toHaveBeenCalledWith('/payments/7');
+  });
+});

package/tests/NotificationsProvider.test.jsx

@@ -0,0 +1,197 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+
+const feedApi = vi.hoisted(() => ({
+  getNotificationFeed: vi.fn(),
+  getUnreadCount: vi.fn(),
+  markNotifications: vi.fn(),
+}));
+
+vi.mock('../src/notifications/feedApi', () => feedApi);
+
+import { AuthContext } from '../src/auth/AuthContext';
+import { NotificationsProvider, useNotifications } from '../src/notifications/NotificationsProvider';
+
+class MockWebSocket {
+  static instances = [];
+
+  constructor(url) {
+    this.url = url;
+    this.close = vi.fn(() => this.onclose?.());
+    MockWebSocket.instances.push(this);
+  }
+}
+
+const firstNotification = {
+  id: 1,
+  notification_id: 101,
+  content: { title_key: 'first.title' },
+  seen_at: null,
+  dismissed_at: null,
+  done_at: null,
+};
+
+const secondNotification = {
+  id: 2,
+  notification_id: 102,
+  content: { title_key: 'second.title' },
+  seen_at: null,
+  dismissed_at: null,
+  done_at: null,
+};
+
+function Consumer() {
+  const notifications = useNotifications();
+  return (
+    <>
+      <output data-testid="notifications">{JSON.stringify(notifications.notifications)}</output>
+      <output data-testid="unread-count">{notifications.unreadCount}</output>
+      <button onClick={() => notifications.markSeen([1])}>seen</button>
+      <button onClick={() => notifications.markDismissed([2])}>dismissed</button>
+      <button onClick={() => notifications.markDone([1])}>done</button>
+    </>
+  );
+}
+
+function renderProvider({ children = <Consumer />, user = { id: 4 }, ...providerProps } = {}) {
+  return render(
+    <AuthContext.Provider value={{ user }}>
+      <NotificationsProvider {...providerProps}>{children}</NotificationsProvider>
+    </AuthContext.Provider>,
+  );
+}
+
+function currentNotifications() {
+  return JSON.parse(screen.getByTestId('notifications').textContent);
+}
+
+describe('NotificationsProvider', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    MockWebSocket.instances = [];
+    vi.stubGlobal('WebSocket', MockWebSocket);
+    feedApi.getNotificationFeed.mockResolvedValue({ results: [firstNotification, secondNotification] });
+    feedApi.getUnreadCount.mockResolvedValue({ count: 2 });
+    feedApi.markNotifications.mockResolvedValue({ updated: 1 });
+  });
+
+  it('seeds state from the feed and unread-count endpoints', async () => {
+    renderProvider();
+
+    await waitFor(() => expect(screen.getByTestId('unread-count').textContent).toBe('2'));
+
+    expect(currentNotifications()).toEqual(expect.arrayContaining([
+      expect.objectContaining({ id: 1, notification_id: 101, seen: false }),
+      expect.objectContaining({ id: 2, notification_id: 102, dismissed: false }),
+    ]));
+    expect(MockWebSocket.instances).toHaveLength(1);
+  });
+
+  it('prepends a new notification push and increments the unread count', async () => {
+    renderProvider();
+    await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
+
+    MockWebSocket.instances[0].onmessage({ data: JSON.stringify({
+      type: 'payment_due',
+      notification_id: 303,
+      content: { title_key: 'payment.title', body_key: 'payment.body', params: { amount: 20 } },
+    }) });
+
+    await waitFor(() => expect(screen.getByTestId('unread-count').textContent).toBe('3'));
+    expect(currentNotifications()[0]).toEqual(expect.objectContaining({
+      id: 303,
+      notification_id: 303,
+      notification_type: 'payment_due',
+      seen: false,
+    }));
+  });
+
+  it('applies a status push to the matching notification without duplication', async () => {
+    renderProvider();
+    await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
+
+    MockWebSocket.instances[0].onmessage({ data: JSON.stringify({
+      type: 'notification.status',
+      notification_id: 101,
+      status: { seen: true, dismissed: false, done: true },
+    }) });
+
+    await waitFor(() => expect(currentNotifications()[0]).toEqual(expect.objectContaining({
+      notification_id: 101,
+      seen: true,
+      dismissed: false,
+      done: true,
+    })));
+    expect(currentNotifications()).toHaveLength(2);
+    expect(currentNotifications()[1]).toEqual(expect.objectContaining({ notification_id: 102, seen: false }));
+    expect(screen.getByTestId('unread-count').textContent).toBe('1');
+  });
+
+  it('decrements unread count on a cross-tab status push and does not double-count a repeat push', async () => {
+    renderProvider();
+    await waitFor(() => expect(screen.getByTestId('unread-count').textContent).toBe('2'));
+
+    MockWebSocket.instances[0].onmessage({ data: JSON.stringify({
+      type: 'notification.status',
+      notification_id: 101,
+      status: { seen: true, dismissed: false, done: false },
+    }) });
+    await waitFor(() => expect(screen.getByTestId('unread-count').textContent).toBe('1'));
+
+    MockWebSocket.instances[0].onmessage({ data: JSON.stringify({
+      type: 'notification.status',
+      notification_id: 101,
+      status: { seen: true, dismissed: false, done: true },
+    }) });
+    await waitFor(() => expect(currentNotifications()[0]).toEqual(expect.objectContaining({ done: true })));
+    expect(screen.getByTestId('unread-count').textContent).toBe('1');
+  });
+
+  it('constructs only one WebSocket across a provider re-render', async () => {
+    const { rerender } = renderProvider();
+    await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
+
+    rerender(
+      <AuthContext.Provider value={{ user: { id: 4 } }}>
+        <NotificationsProvider><Consumer /></NotificationsProvider>
+      </AuthContext.Provider>,
+    );
+
+    expect(MockWebSocket.instances).toHaveLength(1);
+  });
+
+  it('closes the socket on unmount', async () => {
+    const { unmount } = renderProvider();
+    await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
+    const socket = MockWebSocket.instances[0];
+
+    unmount();
+
+    expect(socket.close).toHaveBeenCalledOnce();
+  });
+
+  it('marks rows optimistically and sends each canonical action', async () => {
+    renderProvider();
+    await waitFor(() => expect(screen.getByTestId('unread-count').textContent).toBe('2'));
+
+    fireEvent.click(screen.getByRole('button', { name: 'seen' }));
+    expect(currentNotifications()[0]).toEqual(expect.objectContaining({ seen: true }));
+    expect(screen.getByTestId('unread-count').textContent).toBe('1');
+    expect(feedApi.markNotifications).toHaveBeenCalledWith({ action: 'seen', ids: [1] });
+
+    fireEvent.click(screen.getByRole('button', { name: 'dismissed' }));
+    expect(currentNotifications()[1]).toEqual(expect.objectContaining({ dismissed: true }));
+    expect(screen.getByTestId('unread-count').textContent).toBe('0');
+    expect(feedApi.markNotifications).toHaveBeenCalledWith({ action: 'dismissed', ids: [2] });
+
+    fireEvent.click(screen.getByRole('button', { name: 'done' }));
+    expect(currentNotifications()[0]).toEqual(expect.objectContaining({ done: true }));
+    expect(feedApi.markNotifications).toHaveBeenCalledWith({ action: 'done', ids: [1] });
+  });
+});

package/tests/feedApi.test.js

@@ -0,0 +1,46 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const client = vi.hoisted(() => ({
+  get: vi.fn(),
+  post: vi.fn(),
+}));
+
+vi.mock('../src/auth/apiClient', () => ({ default: client }));
+
+import { getNotificationFeed, getUnreadCount, markNotifications } from '../src/notifications/feedApi';
+
+describe('notification feed API', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('loads the feed with an optional status filter', async () => {
+    const data = { count: 1, results: [] };
+    client.get.mockResolvedValue({ data });
+
+    await expect(getNotificationFeed({ status: 'unseen' })).resolves.toBe(data);
+
+    expect(client.get).toHaveBeenCalledWith('/api/notifications/feed/', { params: { status: 'unseen' } });
+  });
+
+  it('loads the unread count', async () => {
+    const data = { count: 3 };
+    client.get.mockResolvedValue({ data });
+
+    await expect(getUnreadCount()).resolves.toBe(data);
+
+    expect(client.get).toHaveBeenCalledWith('/api/notifications/feed/unread-count/');
+  });
+
+  it('marks recipient rows with the supplied action and ids', async () => {
+    const data = { updated: 2 };
+    client.post.mockResolvedValue({ data });
+
+    await expect(markNotifications({ action: 'seen', ids: [4, 8] })).resolves.toBe(data);
+
+    expect(client.post).toHaveBeenCalledWith('/api/notifications/feed/mark/', {
+      action: 'seen',
+      ids: [4, 8],
+    });
+  });
+});

package/tests/notificationsExports.test.js

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  NotificationSettings,
+  getNotificationPreferences,
+  getVapidPublicKey,
+  listPushSubscriptions,
+  notificationsTranslations,
+  patchNotificationPreferences,
+  removePushSubscription,
+  savePushSubscription,
+  urlBase64ToUint8Array,
+} from '../src/index';
+
+describe('notification barrel exports', () => {
+  it('preserves legacy notification exports and translations', () => {
+    [
+      NotificationSettings,
+      getNotificationPreferences,
+      patchNotificationPreferences,
+      getVapidPublicKey,
+      listPushSubscriptions,
+      savePushSubscription,
+      removePushSubscription,
+      urlBase64ToUint8Array,
+      notificationsTranslations,
+    ].forEach((value) => expect(value).toBeDefined());
+  });
+});