@micha.bigler/ui-core-micha 2.13.0 → 2.14.0

package/WORK_ORDERS.md

@@ -22,5 +22,5 @@ prefixed ID; never reuse a bare flat number across workstreams.
 | 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 | 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 |
-| NOTIF-13 | Layer-1 transport extraction (pluggable realtime) | Extract the socket out of `NotificationsProvider` into a generic subscribe-by-message-type realtime primitive so a second domain (messaging) can ride the same socket; the catch-all that turns every non-`notification.status` message into a feed entry is replaced by explicit dispatch with unknown types ignored. Additive: `NotificationsProvider` stays the sole mount point, its context value unchanged. Full spec: [work-orders/NOTIF-13.md](work-orders/NOTIF-13.md). | 2026-07-29 | planned | | Tier 2 (cockpit consumes `NotificationsProvider` at 2.12.0 in prod). Phase A, the hinge: unblocks NOTIF-15 (jg bell adoption) and is the substrate for Phase B messaging. Canonical register row: django-core-micha `WORK_ORDERS.md`. Operator decision 2026-07-29: additive only, NO standalone `RealtimeProvider` apps must mount. Scope E (envelope contract + helper + doc) also touches dcm; note that the roadmap wording "dcm multi-stream consumer" overstates it — `push_to_users`/`NotificationConsumer` are already stream-agnostic. |
-| NOTIF-12 | Popup channel via the wizard renderer | Make `popup` a real delivery channel: extract the presentational dialog shell out of `OnboardingWizard`, render popup-eligible notifications through it, and record seen/dismissed on `NotificationRecipient` (design D-F7: renderer reuse only, NOT the onboarding progress store); dcm `PopupDispatcher` stops being a logging stub. Full spec: [work-orders/NOTIF-12.md](work-orders/NOTIF-12.md). | 2026-07-29 | planned | | Tier 2 (extracts a renderer cockpit+jg run in production; the roadmap label "uncritical" is about urgency, not blast radius). **HARD GATE: starts only after NOTIF-13 landed + published** — consumes its envelope contract and `subscribe()`, and edits the same ucm files (AGENTS.md overlap rule). **SHIPS WITH ZERO PRODUCERS, deliberately** (operator decision 2026-07-29, made with the evidence): no notification type declares `popup` in `eligible_channels` anywhere in dcm/jg/cockpit/hram/spesix/survey_app, so the channel is wired but inactive until an app opts a type in. WO therefore requires (a) CHANGELOG wording that does not overclaim (NOTIF-4 R1 precedent) and (b) a test-local producer type proving the path end-to-end, so it is not untested dead code. Was NOTIF-11 (renumbered 2026-07-29 for the jg cutover/drop split). |
+| NOTIF-13 | Layer-1 transport extraction (pluggable realtime) | Extract the socket out of `NotificationsProvider` into a generic subscribe-by-message-type realtime primitive so a second domain (messaging) can ride the same socket; the catch-all that turns every non-`notification.status` message into a feed entry is replaced by explicit dispatch with unknown types ignored. Additive: `NotificationsProvider` stays the sole mount point, its context value unchanged. Full spec: [work-orders/NOTIF-13.md](work-orders/NOTIF-13.md). | 2026-07-29 | done | ucm: 7a83ee9; dcm: de77335 | Tier 2 (cockpit consumes `NotificationsProvider` at 2.12.0 in prod). Phase A, the hinge: unblocks NOTIF-15 (jg bell adoption) and is the substrate for Phase B messaging. Canonical register row: django-core-micha `WORK_ORDERS.md`. Operator decision 2026-07-29: additive only, NO standalone `RealtimeProvider` apps must mount. Scope E (envelope contract + helper + doc) also touches dcm; note that the roadmap wording "dcm multi-stream consumer" overstates it — `push_to_users`/`NotificationConsumer` are already stream-agnostic. Codex failed twice on this WO with a genuine CLI/model-version error (`gpt-5.6-terra requires a newer version of Codex`), not a transient issue — orchestrator fell back to direct Claude implementation per the Codex→Claude fallback rule. Independent `reviewer` (sec_reviewer not required per WO): found R1 (P2, real bug — decoupling the REST seed from the socket connect opened a race where a live push arriving before the initial feed loaded would be silently discarded by `refresh()`'s unconditional `replaceNotifications()`; fixed via a `seeded` state gate restoring the exact original seed-then-connect ordering, re-verified 70/70 green), R2 (P3 — the WO's "must be called out in the CHANGELOG" has no home since ucm has no CHANGELOG.md convention at all; operator decision: document via commit message + this register entry only, no new file), R3 (register housekeeping, closed by this update). ucm full suite 70/70 + `pnpm build` clean; dcm notifications suite 92/92, full dcm suite 392/392. Published: ucm 2.13.0 (npm), dcm 2.33.0 (PyPI, verified live before this record) — no app pin bumps in this WO per spec. |
+| NOTIF-12 | Popup channel via the wizard renderer | Make `popup` a real delivery channel: extract the presentational dialog shell out of `OnboardingWizard`, render popup-eligible notifications through it, and record seen/dismissed on `NotificationRecipient` (design D-F7: renderer reuse only, NOT the onboarding progress store); dcm `PopupDispatcher` stops being a logging stub. Full spec: [work-orders/NOTIF-12.md](work-orders/NOTIF-12.md). | 2026-07-29 | planned | | Tier 2 (extracts a renderer cockpit+jg run in production; the roadmap label "uncritical" is about urgency, not blast radius). **HARD GATE: starts only after NOTIF-13 landed + published** — consumes its envelope contract and `subscribe()`, and edits the same ucm files (AGENTS.md overlap rule). **SHIPS WITH ZERO PRODUCERS, deliberately** (operator decision 2026-07-29, made with the evidence): no notification type declares `popup` in `eligible_channels` anywhere in dcm/jg/cockpit/hram/spesix/survey_app, so the channel is wired but inactive until an app opts a type in. WO therefore requires (a) CHANGELOG wording that does not overclaim (NOTIF-4 R1 precedent) and (b) a test-local producer type proving the path end-to-end, so it is not untested dead code. Was NOTIF-11 (renumbered 2026-07-29 for the jg cutover/drop split). **Gate satisfied 2026-07-30** (ucm 2.13.0 / dcm 2.33.0); WO re-verified against the landed NOTIF-13 code and corrected in `345631d`: NOTIF-13 shipped the envelope as a **domain**-level discriminator, so a popup payload built the same way as a chip payload would be indistinguishable from it - the WO now mandates a `channel` field inside the envelope (never a second envelope value) plus feed de-duplication by `notification_id`, without which chip+popup double-counts the unread badge. |

package/dist/i18n/notificationsTranslations.js

@@ -17,4 +17,6 @@ export const notificationsTranslations = {
     'NotificationSettings.PUSH_CONFLICT': { de: 'Dieses Gerät ist bereits mit einem anderen Konto für Push-Benachrichtigungen verbunden.', fr: 'Cet appareil est déjà associé à un autre compte pour les notifications push.', en: 'This device is already associated with another account for push notifications.', sw: 'Kifaa hiki tayari kimeunganishwa na akaunti nyingine kwa arifa za push.' },
     'NotificationSettings.PUSH_NOT_SUPPORTED': { de: 'Push-Benachrichtigungen werden von diesem Browser nicht unterstützt.', fr: 'Les notifications push ne sont pas prises en charge par ce navigateur.', en: 'Push notifications are not supported by this browser.', sw: 'Arifa za push hazitumiki na kivinjari hiki.' },
     'NotificationSettings.IOS_HINT': { de: 'Füge diese App zuerst zum Home-Bildschirm hinzu, um Push-Benachrichtigungen zu aktivieren.', fr: 'Ajoutez d’abord cette application à l’écran d’accueil pour activer les notifications push.', en: 'Add this app to your home screen first to enable push notifications.', sw: 'Ongeza programu hii kwenye skrini yako ya mwanzo kwanza ili kuwasha arifa za push.' },
+    'PopupSurface.CLOSE': { de: 'Schliessen', fr: 'Fermer', en: 'Close', sw: 'Funga' },
+    'PopupSurface.TITLE': { de: 'Benachrichtigung', fr: 'Notification', en: 'Notification', sw: 'Arifa' },
 };

package/dist/index.js

@@ -35,6 +35,7 @@ export * from './notifications/api';
 export { NotificationsProvider, useNotifications } from './notifications/NotificationsProvider';
 export { useRealtime } from './notifications/realtime';
 export { NotificationBell } from './notifications/NotificationBell';
+export { PopupSurface } from './notifications/PopupSurface';
 export { getNotificationFeed, getUnreadCount, markNotifications } from './notifications/feedApi';
 // --- 8. Onboarding ---
 export * from './onboarding/api';

package/dist/notifications/NotificationsProvider.js

@@ -91,6 +91,19 @@ export function NotificationsProvider({ children, wsUrlBase }) {
             return;
         }
         const pushedNotification = normalizeNotificationPush(data);
+        // NOTIF-12 D2: a notification routed to more than one channel (e.g. chip
+        // + popup) arrives as multiple WS messages sharing one notification_id.
+        // Fold repeats into the existing feed entry (last-write-wins on content)
+        // instead of appending a duplicate and double-incrementing the badge.
+        const existingIndex = pushedNotification.notification_id == null
+            ? -1
+            : notificationsRef.current.findIndex((notification) => notification.notification_id === pushedNotification.notification_id);
+        if (existingIndex !== -1) {
+            const nextNotifications = notificationsRef.current.map((notification, index) => (index === existingIndex
+                ? Object.assign(Object.assign({}, notification), { notification_type: pushedNotification.notification_type, content: pushedNotification.content }) : notification));
+            replaceNotifications(nextNotifications);
+            return;
+        }
         replaceNotifications([pushedNotification, ...notificationsRef.current]);
         setUnreadCount((count) => count + 1);
     }, [replaceNotifications]);

package/dist/notifications/PopupSurface.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import Button from '@mui/material/Button';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import { useOnboarding } from '../onboarding/OnboardingProvider';
+import { WizardDialogShell } from '../onboarding/WizardDialogShell';
+import { useNotifications } from './NotificationsProvider';
+import { DEFAULT_ENVELOPE, useRealtime } from './realtime';
+function PopupStepComponent({ onDismiss, ctx }) {
+    const { t } = useTranslation();
+    const content = (ctx === null || ctx === void 0 ? void 0 : ctx.content) || {};
+    return (_jsxs(Stack, { spacing: 2, children: [content.body_key && (_jsx(Typography, { variant: "body1", children: t(content.body_key, content.params || {}) })), _jsx(Button, { onClick: onDismiss, sx: { alignSelf: 'flex-end' }, children: t('PopupSurface.CLOSE') })] }));
+}
+const POPUP_STEP = { blocking: false, Component: PopupStepComponent };
+/**
+ * Renders popup-eligible notifications (NOTIF-12) through the onboarding
+ * wizard's dialog shell, reusing only the renderer (design D-F7) — status
+ * lives on NotificationRecipient via the existing feed/mark path, never in
+ * the onboarding progress store.
+ *
+ * Deliberately session-live only: it watches the raw realtime stream for
+ * `channel === "popup"` messages rather than the already-seeded feed list,
+ * since the feed carries no per-channel discriminator (see NotificationsProvider).
+ */
+export function PopupSurface() {
+    var _a;
+    const { t } = useTranslation();
+    const { markSeen, markDismissed } = useNotifications();
+    const { subscribe } = useRealtime();
+    const onboarding = useOnboarding();
+    const [queue, setQueue] = useState([]);
+    const seenIdsRef = useRef(new Set());
+    const handleRealtimeMessage = useCallback((data) => {
+        if (data.type === 'notification.status')
+            return;
+        if (data.channel !== 'popup')
+            return;
+        setQueue((previous) => {
+            var _a;
+            if (previous.some((item) => item.notification_id === data.notification_id))
+                return previous;
+            return [...previous, {
+                    notification_id: data.notification_id,
+                    // recipient_id is the id feed/mark/ actually resolves against
+                    // (NotificationRecipient.pk, not Notification.pk). Fall back to
+                    // notification_id only for an older dcm that predates it — matching
+                    // NotificationsProvider's own normalizeNotificationPush precedent.
+                    markId: (_a = data.recipient_id) !== null && _a !== void 0 ? _a : data.notification_id,
+                    content: data.content || {},
+                }];
+        });
+    }, []);
+    useEffect(() => subscribe(DEFAULT_ENVELOPE, handleRealtimeMessage), [subscribe, handleRealtimeMessage]);
+    // Any active onboarding step — blocking or not — must win: OnboardingWizard
+    // renders its own dialog for as long as onboarding.activeSteps is non-empty,
+    // and two independent MUI Dialogs must never be mounted at once.
+    const onboardingActive = Boolean((_a = onboarding === null || onboarding === void 0 ? void 0 : onboarding.activeSteps) === null || _a === void 0 ? void 0 : _a.length);
+    const activePopup = queue[0];
+    useEffect(() => {
+        if (!activePopup || onboardingActive)
+            return;
+        if (activePopup.markId == null)
+            return;
+        if (seenIdsRef.current.has(activePopup.notification_id))
+            return;
+        seenIdsRef.current.add(activePopup.notification_id);
+        markSeen([activePopup.markId]);
+    }, [activePopup, onboardingActive, markSeen]);
+    const dismissActivePopup = useCallback(() => {
+        if (!activePopup)
+            return;
+        if (activePopup.markId != null)
+            markDismissed([activePopup.markId]);
+        setQueue((previous) => previous.filter((item) => item.notification_id !== activePopup.notification_id));
+    }, [activePopup, markDismissed]);
+    if (!activePopup || onboardingActive)
+        return null;
+    return (_jsx(WizardDialogShell, { step: POPUP_STEP, stepIndex: 0, total: 1, onComplete: dismissActivePopup, onDismiss: dismissActivePopup, ctx: { content: activePopup.content }, title: activePopup.content.title_key
+            ? t(activePopup.content.title_key, activePopup.content.params || {})
+            : t('PopupSurface.TITLE') }));
+}
+export default PopupSurface;

package/dist/onboarding/OnboardingWizard.js

@@ -1,16 +1,9 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 import React, { useContext, useEffect, useRef, useState } from 'react';
-import { useTranslation } from 'react-i18next';
-import Box from '@mui/material/Box';
-import Dialog from '@mui/material/Dialog';
-import DialogContent from '@mui/material/DialogContent';
-import DialogTitle from '@mui/material/DialogTitle';
-import LinearProgress from '@mui/material/LinearProgress';
-import Typography from '@mui/material/Typography';
 import { AuthContext } from '../auth/AuthContext';
 import { useOnboarding } from './OnboardingProvider';
+import { WizardDialogShell } from './WizardDialogShell';
 export function OnboardingWizard() {
-    const { t } = useTranslation();
     const onboarding = useOnboarding();
     const authContext = useContext(AuthContext);
     const [sessionDismissed, setSessionDismissed] = useState(() => new Set());
@@ -37,8 +30,6 @@ export function OnboardingWizard() {
         return null;
     const { dismissStep, ctx } = onboarding;
     const total = totalRef.current || visibleSteps.length;
-    const progress = total > 1 ? Math.round((completed / total) * 100) : 0;
-    const StepComponent = currentStep.Component;
     const completeCurrentStep = () => {
         var _a, _b;
         setSessionDismissed((previous) => new Set([...previous, currentStep.id]));
@@ -52,6 +43,6 @@ export function OnboardingWizard() {
             dismissStep(currentStep.id);
         completeCurrentStep();
     };
-    return (_jsxs(Dialog, { open: true, fullWidth: true, maxWidth: "sm", disableEscapeKeyDown: currentStep.blocking, onClose: currentStep.blocking ? undefined : dismissCurrentStep, children: [_jsxs(DialogTitle, { sx: { pb: 0 }, children: [_jsx(Box, { sx: { display: 'flex', alignItems: 'center', justifyContent: 'space-between' }, children: _jsx(Typography, { variant: "subtitle2", color: "text.secondary", children: total > 1 ? t('Onboarding.STEP_COUNTER', { current: completed + 1, total }) : t('Onboarding.SETUP') }) }), total > 1 && _jsx(LinearProgress, { variant: "determinate", value: progress, sx: { mt: 1, borderRadius: 1 } })] }), _jsx(DialogContent, { sx: { pt: 2 }, children: _jsx(StepComponent, { onComplete: completeCurrentStep, onDismiss: dismissCurrentStep, ctx: ctx }) })] }));
+    return (_jsx(WizardDialogShell, { step: currentStep, stepIndex: completed, total: total, onComplete: completeCurrentStep, onDismiss: dismissCurrentStep, ctx: ctx }));
 }
 export default OnboardingWizard;

package/dist/onboarding/WizardDialogShell.js

@@ -0,0 +1,29 @@
+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 Dialog from '@mui/material/Dialog';
+import DialogContent from '@mui/material/DialogContent';
+import DialogTitle from '@mui/material/DialogTitle';
+import LinearProgress from '@mui/material/LinearProgress';
+import Typography from '@mui/material/Typography';
+/**
+ * Presentational dialog shell shared by OnboardingWizard and the popup
+ * notification surface (NOTIF-12). Owns only the dialog frame, the
+ * counter/progress header, and the onComplete/onDismiss/ctx child contract —
+ * step selection, dismissal persistence, and any progress store stay with
+ * the caller.
+ */
+export function WizardDialogShell({ step, stepIndex, total, onComplete, onDismiss, ctx, title }) {
+    const { t } = useTranslation();
+    const progress = total > 1 ? Math.round((stepIndex / total) * 100) : 0;
+    const StepComponent = step.Component;
+    // `title` lets a non-onboarding caller (e.g. the popup surface) supply its
+    // own header instead of the onboarding-specific step counter/"Setup" copy.
+    // Omitted by OnboardingWizard, so its header text is unchanged.
+    const headerLabel = title !== null && title !== void 0 ? title : (total > 1
+        ? t('Onboarding.STEP_COUNTER', { current: stepIndex + 1, total })
+        : t('Onboarding.SETUP'));
+    return (_jsxs(Dialog, { open: true, fullWidth: true, maxWidth: "sm", disableEscapeKeyDown: step.blocking, onClose: step.blocking ? undefined : onDismiss, children: [_jsxs(DialogTitle, { sx: { pb: 0 }, children: [_jsx(Box, { sx: { display: 'flex', alignItems: 'center', justifyContent: 'space-between' }, children: _jsx(Typography, { variant: "subtitle2", color: "text.secondary", children: headerLabel }) }), total > 1 && _jsx(LinearProgress, { variant: "determinate", value: progress, sx: { mt: 1, borderRadius: 1 } })] }), _jsx(DialogContent, { sx: { pt: 2 }, children: _jsx(StepComponent, { onComplete: onComplete, onDismiss: onDismiss, ctx: ctx }) })] }));
+}
+export default WizardDialogShell;

package/package.json

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

package/src/i18n/notificationsTranslations.ts

@@ -17,4 +17,6 @@ export const notificationsTranslations = {
   'NotificationSettings.PUSH_CONFLICT': { de: 'Dieses Gerät ist bereits mit einem anderen Konto für Push-Benachrichtigungen verbunden.', fr: 'Cet appareil est déjà associé à un autre compte pour les notifications push.', en: 'This device is already associated with another account for push notifications.', sw: 'Kifaa hiki tayari kimeunganishwa na akaunti nyingine kwa arifa za push.' },
   'NotificationSettings.PUSH_NOT_SUPPORTED': { de: 'Push-Benachrichtigungen werden von diesem Browser nicht unterstützt.', fr: 'Les notifications push ne sont pas prises en charge par ce navigateur.', en: 'Push notifications are not supported by this browser.', sw: 'Arifa za push hazitumiki na kivinjari hiki.' },
   'NotificationSettings.IOS_HINT': { de: 'Füge diese App zuerst zum Home-Bildschirm hinzu, um Push-Benachrichtigungen zu aktivieren.', fr: 'Ajoutez d’abord cette application à l’écran d’accueil pour activer les notifications push.', en: 'Add this app to your home screen first to enable push notifications.', sw: 'Ongeza programu hii kwenye skrini yako ya mwanzo kwanza ili kuwasha arifa za push.' },
+  'PopupSurface.CLOSE': { de: 'Schliessen', fr: 'Fermer', en: 'Close', sw: 'Funga' },
+  'PopupSurface.TITLE': { de: 'Benachrichtigung', fr: 'Notification', en: 'Notification', sw: 'Arifa' },
 };

package/src/index.js

@@ -48,6 +48,7 @@ export * from './notifications/api';
 export { NotificationsProvider, useNotifications } from './notifications/NotificationsProvider';
 export { useRealtime } from './notifications/realtime';
 export { NotificationBell } from './notifications/NotificationBell';
+export { PopupSurface } from './notifications/PopupSurface';
 export { getNotificationFeed, getUnreadCount, markNotifications } from './notifications/feedApi';
 
 // --- 8. Onboarding ---

package/src/notifications/NotificationsProvider.jsx

@@ -116,6 +116,27 @@ export function NotificationsProvider({ children, wsUrlBase }) {
     }
 
     const pushedNotification = normalizeNotificationPush(data);
+
+    // NOTIF-12 D2: a notification routed to more than one channel (e.g. chip
+    // + popup) arrives as multiple WS messages sharing one notification_id.
+    // Fold repeats into the existing feed entry (last-write-wins on content)
+    // instead of appending a duplicate and double-incrementing the badge.
+    const existingIndex = pushedNotification.notification_id == null
+      ? -1
+      : notificationsRef.current.findIndex(
+        (notification) => notification.notification_id === pushedNotification.notification_id,
+      );
+
+    if (existingIndex !== -1) {
+      const nextNotifications = notificationsRef.current.map((notification, index) => (
+        index === existingIndex
+          ? { ...notification, notification_type: pushedNotification.notification_type, content: pushedNotification.content }
+          : notification
+      ));
+      replaceNotifications(nextNotifications);
+      return;
+    }
+
     replaceNotifications([pushedNotification, ...notificationsRef.current]);
     setUnreadCount((count) => count + 1);
   }, [replaceNotifications]);

package/src/notifications/PopupSurface.jsx

@@ -0,0 +1,103 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import Button from '@mui/material/Button';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import { useOnboarding } from '../onboarding/OnboardingProvider';
+import { WizardDialogShell } from '../onboarding/WizardDialogShell';
+import { useNotifications } from './NotificationsProvider';
+import { DEFAULT_ENVELOPE, useRealtime } from './realtime';
+
+function PopupStepComponent({ onDismiss, ctx }) {
+  const { t } = useTranslation();
+  const content = ctx?.content || {};
+
+  return (
+    <Stack spacing={2}>
+      {content.body_key && (
+        <Typography variant="body1">{t(content.body_key, content.params || {})}</Typography>
+      )}
+      <Button onClick={onDismiss} sx={{ alignSelf: 'flex-end' }}>
+        {t('PopupSurface.CLOSE')}
+      </Button>
+    </Stack>
+  );
+}
+
+const POPUP_STEP = { blocking: false, Component: PopupStepComponent };
+
+/**
+ * Renders popup-eligible notifications (NOTIF-12) through the onboarding
+ * wizard's dialog shell, reusing only the renderer (design D-F7) — status
+ * lives on NotificationRecipient via the existing feed/mark path, never in
+ * the onboarding progress store.
+ *
+ * Deliberately session-live only: it watches the raw realtime stream for
+ * `channel === "popup"` messages rather than the already-seeded feed list,
+ * since the feed carries no per-channel discriminator (see NotificationsProvider).
+ */
+export function PopupSurface() {
+  const { t } = useTranslation();
+  const { markSeen, markDismissed } = useNotifications();
+  const { subscribe } = useRealtime();
+  const onboarding = useOnboarding();
+  const [queue, setQueue] = useState([]);
+  const seenIdsRef = useRef(new Set());
+
+  const handleRealtimeMessage = useCallback((data) => {
+    if (data.type === 'notification.status') return;
+    if (data.channel !== 'popup') return;
+    setQueue((previous) => {
+      if (previous.some((item) => item.notification_id === data.notification_id)) return previous;
+      return [...previous, {
+        notification_id: data.notification_id,
+        // recipient_id is the id feed/mark/ actually resolves against
+        // (NotificationRecipient.pk, not Notification.pk). Fall back to
+        // notification_id only for an older dcm that predates it — matching
+        // NotificationsProvider's own normalizeNotificationPush precedent.
+        markId: data.recipient_id ?? data.notification_id,
+        content: data.content || {},
+      }];
+    });
+  }, []);
+
+  useEffect(() => subscribe(DEFAULT_ENVELOPE, handleRealtimeMessage), [subscribe, handleRealtimeMessage]);
+
+  // Any active onboarding step — blocking or not — must win: OnboardingWizard
+  // renders its own dialog for as long as onboarding.activeSteps is non-empty,
+  // and two independent MUI Dialogs must never be mounted at once.
+  const onboardingActive = Boolean(onboarding?.activeSteps?.length);
+  const activePopup = queue[0];
+
+  useEffect(() => {
+    if (!activePopup || onboardingActive) return;
+    if (activePopup.markId == null) return;
+    if (seenIdsRef.current.has(activePopup.notification_id)) return;
+    seenIdsRef.current.add(activePopup.notification_id);
+    markSeen([activePopup.markId]);
+  }, [activePopup, onboardingActive, markSeen]);
+
+  const dismissActivePopup = useCallback(() => {
+    if (!activePopup) return;
+    if (activePopup.markId != null) markDismissed([activePopup.markId]);
+    setQueue((previous) => previous.filter((item) => item.notification_id !== activePopup.notification_id));
+  }, [activePopup, markDismissed]);
+
+  if (!activePopup || onboardingActive) return null;
+
+  return (
+    <WizardDialogShell
+      step={POPUP_STEP}
+      stepIndex={0}
+      total={1}
+      onComplete={dismissActivePopup}
+      onDismiss={dismissActivePopup}
+      ctx={{ content: activePopup.content }}
+      title={activePopup.content.title_key
+        ? t(activePopup.content.title_key, activePopup.content.params || {})
+        : t('PopupSurface.TITLE')}
+    />
+  );
+}
+
+export default PopupSurface;

package/src/onboarding/OnboardingWizard.jsx

@@ -1,16 +1,9 @@
 import React, { useContext, useEffect, useRef, useState } from 'react';
-import { useTranslation } from 'react-i18next';
-import Box from '@mui/material/Box';
-import Dialog from '@mui/material/Dialog';
-import DialogContent from '@mui/material/DialogContent';
-import DialogTitle from '@mui/material/DialogTitle';
-import LinearProgress from '@mui/material/LinearProgress';
-import Typography from '@mui/material/Typography';
 import { AuthContext } from '../auth/AuthContext';
 import { useOnboarding } from './OnboardingProvider';
+import { WizardDialogShell } from './WizardDialogShell';
 
 export function OnboardingWizard() {
-  const { t } = useTranslation();
   const onboarding = useOnboarding();
   const authContext = useContext(AuthContext);
   const [sessionDismissed, setSessionDismissed] = useState(() => new Set());
@@ -39,8 +32,6 @@ export function OnboardingWizard() {
 
   const { dismissStep, ctx } = onboarding;
   const total = totalRef.current || visibleSteps.length;
-  const progress = total > 1 ? Math.round((completed / total) * 100) : 0;
-  const StepComponent = currentStep.Component;
 
   const completeCurrentStep = () => {
     setSessionDismissed((previous) => new Set([...previous, currentStep.id]));
@@ -56,19 +47,14 @@ export function OnboardingWizard() {
   };
 
   return (
-    <Dialog open fullWidth maxWidth="sm" disableEscapeKeyDown={currentStep.blocking} onClose={currentStep.blocking ? undefined : dismissCurrentStep}>
-      <DialogTitle sx={{ pb: 0 }}>
-        <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
-          <Typography variant="subtitle2" color="text.secondary">
-            {total > 1 ? t('Onboarding.STEP_COUNTER', { current: completed + 1, total }) : t('Onboarding.SETUP')}
-          </Typography>
-        </Box>
-        {total > 1 && <LinearProgress variant="determinate" value={progress} sx={{ mt: 1, borderRadius: 1 }} />}
-      </DialogTitle>
-      <DialogContent sx={{ pt: 2 }}>
-        <StepComponent onComplete={completeCurrentStep} onDismiss={dismissCurrentStep} ctx={ctx} />
-      </DialogContent>
-    </Dialog>
+    <WizardDialogShell
+      step={currentStep}
+      stepIndex={completed}
+      total={total}
+      onComplete={completeCurrentStep}
+      onDismiss={dismissCurrentStep}
+      ctx={ctx}
+    />
   );
 }
 

package/src/onboarding/WizardDialogShell.jsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import Box from '@mui/material/Box';
+import Dialog from '@mui/material/Dialog';
+import DialogContent from '@mui/material/DialogContent';
+import DialogTitle from '@mui/material/DialogTitle';
+import LinearProgress from '@mui/material/LinearProgress';
+import Typography from '@mui/material/Typography';
+
+/**
+ * Presentational dialog shell shared by OnboardingWizard and the popup
+ * notification surface (NOTIF-12). Owns only the dialog frame, the
+ * counter/progress header, and the onComplete/onDismiss/ctx child contract —
+ * step selection, dismissal persistence, and any progress store stay with
+ * the caller.
+ */
+export function WizardDialogShell({ step, stepIndex, total, onComplete, onDismiss, ctx, title }) {
+  const { t } = useTranslation();
+  const progress = total > 1 ? Math.round((stepIndex / total) * 100) : 0;
+  const StepComponent = step.Component;
+  // `title` lets a non-onboarding caller (e.g. the popup surface) supply its
+  // own header instead of the onboarding-specific step counter/"Setup" copy.
+  // Omitted by OnboardingWizard, so its header text is unchanged.
+  const headerLabel = title ?? (total > 1
+    ? t('Onboarding.STEP_COUNTER', { current: stepIndex + 1, total })
+    : t('Onboarding.SETUP'));
+
+  return (
+    <Dialog
+      open
+      fullWidth
+      maxWidth="sm"
+      disableEscapeKeyDown={step.blocking}
+      onClose={step.blocking ? undefined : onDismiss}
+    >
+      <DialogTitle sx={{ pb: 0 }}>
+        <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+          <Typography variant="subtitle2" color="text.secondary">
+            {headerLabel}
+          </Typography>
+        </Box>
+        {total > 1 && <LinearProgress variant="determinate" value={progress} sx={{ mt: 1, borderRadius: 1 }} />}
+      </DialogTitle>
+      <DialogContent sx={{ pt: 2 }}>
+        <StepComponent onComplete={onComplete} onDismiss={onDismiss} ctx={ctx} />
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+export default WizardDialogShell;

package/tests/NotificationsProvider.test.jsx

@@ -195,4 +195,42 @@ describe('NotificationsProvider', () => {
     expect(currentNotifications()[0]).toEqual(expect.objectContaining({ done: true }));
     expect(feedApi.markNotifications).toHaveBeenCalledWith({ action: 'done', ids: [1] });
   });
+
+  it('folds two WS messages for the same notification_id into one feed entry with a single unread increment (NOTIF-12 D2)', async () => {
+    renderProvider();
+    await waitFor(() => expect(screen.getByTestId('unread-count').textContent).toBe('2'));
+    await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
+
+    MockWebSocket.instances[0].onmessage({ data: JSON.stringify({
+      type: 'payment_due',
+      channel: 'chip',
+      notification_id: 404,
+      content: { title_key: 'chip.title' },
+    }) });
+    await waitFor(() => expect(screen.getByTestId('unread-count').textContent).toBe('3'));
+
+    MockWebSocket.instances[0].onmessage({ data: JSON.stringify({
+      type: 'payment_due',
+      channel: 'popup',
+      notification_id: 404,
+      content: { title_key: 'popup.title' },
+    }) });
+
+    await waitFor(() => expect(currentNotifications().find((n) => n.notification_id === 404).content)
+      .toEqual({ title_key: 'popup.title' }));
+    expect(currentNotifications().filter((n) => n.notification_id === 404)).toHaveLength(1);
+    expect(screen.getByTestId('unread-count').textContent).toBe('3');
+  });
+
+  it('NOTIF-13 R1 guard: does not open the socket until the REST seed resolves', async () => {
+    let resolveFeed;
+    feedApi.getNotificationFeed.mockReturnValue(new Promise((resolve) => { resolveFeed = resolve; }));
+
+    renderProvider();
+
+    expect(MockWebSocket.instances).toHaveLength(0);
+
+    resolveFeed({ results: [] });
+    await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
+  });
 });

package/tests/OnboardingWizard.test.jsx

@@ -0,0 +1,143 @@
+// @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';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key, params) => (params && Object.keys(params).length ? `${key}:${JSON.stringify(params)}` : key),
+  }),
+}));
+
+const onboardingModule = vi.hoisted(() => ({ useOnboarding: vi.fn() }));
+vi.mock('../src/onboarding/OnboardingProvider', () => onboardingModule);
+
+import { AuthContext } from '../src/auth/AuthContext';
+import { OnboardingWizard } from '../src/onboarding/OnboardingWizard';
+
+function StepBody({ onComplete, onDismiss }) {
+  return (
+    <div>
+      <button onClick={onComplete}>step-complete</button>
+      <button onClick={onDismiss}>step-dismiss</button>
+    </div>
+  );
+}
+
+function makeStep(overrides = {}) {
+  return {
+    id: 'step-1',
+    blocking: false,
+    persistDismissed: false,
+    Component: StepBody,
+    ...overrides,
+  };
+}
+
+function renderWizard({ onboarding, refreshUser = vi.fn().mockResolvedValue() } = {}) {
+  onboardingModule.useOnboarding.mockReturnValue(onboarding);
+  return render(
+    <AuthContext.Provider value={{ refreshUser }}>
+      <OnboardingWizard />
+    </AuthContext.Provider>,
+  );
+}
+
+describe('OnboardingWizard regression guard (NOTIF-12 shell extraction)', () => {
+  afterEach(() => {
+    cleanup();
+    vi.clearAllMocks();
+  });
+
+  it('renders nothing when there is no active step', () => {
+    renderWizard({ onboarding: { activeSteps: [], markStepSeen: vi.fn(), dismissStep: vi.fn(), ctx: {} } });
+
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+
+  it('shows the single-step SETUP title with no progress bar for exactly one step', () => {
+    renderWizard({ onboarding: {
+      activeSteps: [makeStep()],
+      markStepSeen: vi.fn(),
+      dismissStep: vi.fn(),
+      ctx: {},
+    } });
+
+    expect(screen.getByText('Onboarding.SETUP')).toBeTruthy();
+    expect(screen.queryByRole('progressbar')).toBeNull();
+  });
+
+  it('shows the step counter and progress bar across multiple steps, advancing on completion', () => {
+    renderWizard({ onboarding: {
+      activeSteps: [makeStep({ id: 'a' }), makeStep({ id: 'b' })],
+      markStepSeen: vi.fn(),
+      dismissStep: vi.fn(),
+      ctx: {},
+    } });
+
+    expect(screen.getByText('Onboarding.STEP_COUNTER:{"current":1,"total":2}')).toBeTruthy();
+    expect(screen.getByRole('progressbar')).toBeTruthy();
+
+    fireEvent.click(screen.getByRole('button', { name: 'step-complete' }));
+
+    expect(screen.getByText('Onboarding.STEP_COUNTER:{"current":2,"total":2}')).toBeTruthy();
+  });
+
+  it('marks the current step seen and session-dismisses it once completed, revealing the next step', () => {
+    const markStepSeen = vi.fn();
+    renderWizard({ onboarding: {
+      activeSteps: [makeStep({ id: 'a' }), makeStep({ id: 'b' })],
+      markStepSeen,
+      dismissStep: vi.fn(),
+      ctx: {},
+    } });
+
+    expect(markStepSeen).toHaveBeenCalledWith('a');
+
+    fireEvent.click(screen.getByRole('button', { name: 'step-complete' }));
+
+    expect(markStepSeen).toHaveBeenCalledWith('b');
+  });
+
+  it('disables escape-key close for a blocking step', () => {
+    renderWizard({ onboarding: {
+      activeSteps: [makeStep({ blocking: true })],
+      markStepSeen: vi.fn(),
+      dismissStep: vi.fn(),
+      ctx: {},
+    } });
+
+    const dialog = screen.getByRole('dialog');
+    fireEvent.keyDown(dialog, { key: 'Escape', code: 'Escape' });
+
+    expect(screen.getByRole('dialog')).toBeTruthy();
+  });
+
+  it('calls dismissStep only when the dismissed step is persistDismissed', () => {
+    const dismissStep = vi.fn();
+    renderWizard({ onboarding: {
+      activeSteps: [makeStep({ persistDismissed: true })],
+      markStepSeen: vi.fn(),
+      dismissStep,
+      ctx: {},
+    } });
+
+    fireEvent.click(screen.getByRole('button', { name: 'step-dismiss' }));
+
+    expect(dismissStep).toHaveBeenCalledWith('step-1');
+  });
+
+  it('does not call dismissStep for a non-persistDismissed step on dismiss', () => {
+    const dismissStep = vi.fn();
+    renderWizard({ onboarding: {
+      activeSteps: [makeStep({ persistDismissed: false })],
+      markStepSeen: vi.fn(),
+      dismissStep,
+      ctx: {},
+    } });
+
+    fireEvent.click(screen.getByRole('button', { name: 'step-dismiss' }));
+
+    expect(dismissStep).not.toHaveBeenCalled();
+  });
+});

package/tests/PopupSurface.test.jsx

@@ -0,0 +1,142 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key, params) => (params && Object.keys(params).length ? `${key}:${JSON.stringify(params)}` : key),
+  }),
+}));
+
+const onboardingModule = vi.hoisted(() => ({ useOnboarding: vi.fn() }));
+vi.mock('../src/onboarding/OnboardingProvider', () => onboardingModule);
+
+const notificationsModule = vi.hoisted(() => ({ useNotifications: vi.fn() }));
+vi.mock('../src/notifications/NotificationsProvider', () => notificationsModule);
+
+const realtimeModule = vi.hoisted(() => ({ useRealtime: vi.fn(), DEFAULT_ENVELOPE: 'notification' }));
+vi.mock('../src/notifications/realtime', () => realtimeModule);
+
+import { PopupSurface } from '../src/notifications/PopupSurface';
+
+describe('PopupSurface (NOTIF-12 scope B/C)', () => {
+  let handler;
+  let subscribeFn;
+  let markSeen;
+  let markDismissed;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    handler = null;
+    subscribeFn = (envelope, fn) => {
+      handler = fn;
+      return () => { handler = null; };
+    };
+    markSeen = vi.fn();
+    markDismissed = vi.fn();
+    notificationsModule.useNotifications.mockReturnValue({ markSeen, markDismissed, markDone: vi.fn() });
+    onboardingModule.useOnboarding.mockReturnValue({ activeSteps: [] });
+    realtimeModule.useRealtime.mockImplementation(() => ({ subscribe: subscribeFn }));
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  function push(data) {
+    act(() => {
+      handler(data);
+    });
+  }
+
+  it('renders nothing when no popup-eligible notification is present', () => {
+    render(<PopupSurface />);
+
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+
+  it('renders a popup-eligible notification once, marking seen exactly once on display, and shows the notification title (not the onboarding header)', () => {
+    render(<PopupSurface />);
+
+    push({ notification_id: 1, channel: 'popup', content: { title_key: 'T', body_key: 'B', params: {} } });
+
+    expect(screen.getByRole('dialog')).toBeTruthy();
+    expect(screen.getByText('T')).toBeTruthy();
+    expect(screen.queryByText('Onboarding.SETUP')).toBeNull();
+    expect(markSeen).toHaveBeenCalledTimes(1);
+    expect(markSeen).toHaveBeenCalledWith([1]);
+  });
+
+  it('marks using the wire recipient_id (feed/mark/ id-space), not the notification_id, when present', () => {
+    render(<PopupSurface />);
+
+    push({ notification_id: 10, recipient_id: 999, channel: 'popup', content: { title_key: 'T' } });
+
+    expect(markSeen).toHaveBeenCalledWith([999]);
+
+    fireEvent.click(screen.getByRole('button', { name: 'PopupSurface.CLOSE' }));
+
+    expect(markDismissed).toHaveBeenCalledWith([999]);
+  });
+
+  it('fires markDismissed, never markDone, when the popup is closed', () => {
+    const { markDone } = notificationsModule.useNotifications();
+    render(<PopupSurface />);
+    push({ notification_id: 1, channel: 'popup', content: { title_key: 'T' } });
+
+    fireEvent.click(screen.getByRole('button', { name: 'PopupSurface.CLOSE' }));
+
+    expect(markDismissed).toHaveBeenCalledWith([1]);
+    expect(markDone).not.toHaveBeenCalled();
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+
+  it('ignores a chip-channel message and a channel-less legacy message — no popup storm', () => {
+    render(<PopupSurface />);
+
+    push({ notification_id: 2, channel: 'chip', content: { title_key: 'T' } });
+    push({ notification_id: 3, content: { title_key: 'T' } });
+
+    expect(screen.queryByRole('dialog')).toBeNull();
+    expect(markSeen).not.toHaveBeenCalled();
+  });
+
+  it('ignores a notification.status message regardless of its channel field', () => {
+    render(<PopupSurface />);
+
+    push({ type: 'notification.status', notification_id: 4, channel: 'popup', status: {} });
+
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+
+  it('coexistence: a blocking onboarding step suppresses the popup; it appears once the step clears, never stacking two dialogs', () => {
+    onboardingModule.useOnboarding.mockReturnValue({ activeSteps: [{ id: 'cookie_consent', blocking: true }] });
+    const { rerender } = render(<PopupSurface />);
+
+    push({ notification_id: 5, channel: 'popup', content: { title_key: 'T' } });
+    expect(screen.queryByRole('dialog')).toBeNull();
+    expect(markSeen).not.toHaveBeenCalled();
+
+    onboardingModule.useOnboarding.mockReturnValue({ activeSteps: [] });
+    rerender(<PopupSurface />);
+
+    expect(screen.getAllByRole('dialog')).toHaveLength(1);
+    expect(markSeen).toHaveBeenCalledWith([5]);
+  });
+
+  it('coexistence: a non-blocking onboarding step also suppresses the popup, never stacking two dialogs', () => {
+    onboardingModule.useOnboarding.mockReturnValue({ activeSteps: [{ id: 'browser_push', blocking: false }] });
+    const { rerender } = render(<PopupSurface />);
+
+    push({ notification_id: 6, channel: 'popup', content: { title_key: 'T' } });
+    expect(screen.queryByRole('dialog')).toBeNull();
+    expect(markSeen).not.toHaveBeenCalled();
+
+    onboardingModule.useOnboarding.mockReturnValue({ activeSteps: [] });
+    rerender(<PopupSurface />);
+
+    expect(screen.getAllByRole('dialog')).toHaveLength(1);
+    expect(markSeen).toHaveBeenCalledWith([6]);
+  });
+});

package/tests/notificationsExports.test.js

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 
 import {
   NotificationSettings,
+  PopupSurface,
   getNotificationPreferences,
   getVapidPublicKey,
   listPushSubscriptions,
@@ -26,4 +27,8 @@ describe('notification barrel exports', () => {
       notificationsTranslations,
     ].forEach((value) => expect(value).toBeDefined());
   });
+
+  it('additively exports the NOTIF-12 popup surface', () => {
+    expect(PopupSurface).toBeDefined();
+  });
 });

package/work-orders/NOTIF-12.md

@@ -7,11 +7,10 @@ file. Fall back to direct Claude implementation only on Codex quota / rate-limit
 
 Feature-level WO (Expertenchat envelope). Seams verified against ucm 2.12.0 / dcm 2.32.0.
 
-## HARD GATE — do not start before NOTIF-13 has landed and published
-NOTIF-12 consumes NOTIF-13's envelope contract and its `subscribe(type, handler)` primitive. Starting
-earlier means building on the catch-all in `NotificationsProvider.jsx:130-132` that NOTIF-13 removes.
-Both WOs also edit `ui-core-micha/src/notifications/` and `src/index.js`, so running them in parallel
-violates the AGENTS.md overlap rule. **Sequence: NOTIF-13 → publish → NOTIF-12.**
+## HARD GATE — SATISFIED 2026-07-30
+NOTIF-13 landed and published: ucm **2.13.0** (`7a83ee9`), dcm **2.33.0** (`de77335`), both verified
+live on npm/PyPI. This WO was re-verified against the landed code on 2026-07-30 and the context
+package below describes the **actual shipped API**, not the pre-NOTIF-13 state. Cleared to start.
 
 ## TIER
 Tier 2 — this extracts a renderer out of `OnboardingWizard`, which **cockpit and jg run in
@@ -49,11 +48,27 @@ recorded on `NotificationRecipient` — **not** in the onboarding progress store
 **dcm `notifications/dispatch.py`:**
 - `PopupDispatcher` (`:117-121`) is a stub: logs "queued for unimplemented popup channel" and returns
   `DeliveryResult(ok=None, error="pending")`. It is registered in `_DISPATCHERS` (`:126-133`).
-- The model to copy is `ChipDispatcher` (`:62-74`): it calls
-  `push_to_users([recipient.user], {"type": notification.notification_type, "content": ..., "notification_id": ...})`
-  and returns `DeliveryResult(ok=True)`. **Note the `type` field carries the *domain* type** — this is
-  precisely the overload NOTIF-13 replaces with a proper envelope. Emit NOTIF-13's envelope, not this
-  legacy shape.
+- The model to copy is `ChipDispatcher` (`dispatch.py:64-75`, post-NOTIF-13): it calls
+  `push_to_users([recipient.user], notification_envelope({"type": notification.notification_type, "content": ..., "notification_id": ...}))`
+  and returns `DeliveryResult(ok=True)`.
+
+**How NOTIF-13 actually shipped — read this before writing scope D.** The envelope is a
+**domain-level** discriminator, not a per-channel one:
+- `delivery.py:25` `NOTIFICATION_ENVELOPE = "notification"`; `delivery.py:28-35`
+  `notification_envelope(payload)` merges `{"envelope": "notification"}` into any payload. **Additive**
+  — the pre-existing fields, including the overloaded `type`, are unchanged.
+- ucm `src/notifications/realtime.jsx:68` routes purely on `data.envelope ?? DEFAULT_ENVELOPE`, then
+  fans to every handler subscribed to that envelope.
+- **Inside** the notification envelope, `NotificationsProvider` keeps the original two-way split:
+  `data.type === 'notification.status'` patches status (`:98`), and **everything else is appended to
+  the feed with `unreadCount + 1`** (`:120`).
+
+**Consequence — the trap this WO must avoid:** if `PopupDispatcher` simply calls
+`notification_envelope({...})` like Chip does, its message is **indistinguishable from a chip
+message**. The popup surface subscribing to the `"notification"` envelope would receive every chip
+notification and pop up for all of them, and a notification routed to *both* chip and popup would
+produce **two feed entries and `unreadCount + 2` for one notification**. Scope D and D2 below exist
+to close exactly this.
 - `_render_content(content, user)` (`:44-60`) renders `title_key`/`body_key`/`params` in the
   recipient's language — reuse it rather than re-deriving text client-side if the payload needs text.
 - `prefs.py:22` already treats `popup` as a channel defaulting to True; `router.py:24` narrows to
@@ -82,25 +97,46 @@ reusable renderer (dialog frame, counter/progress header, the `onComplete`/`onDi
 contract). `OnboardingWizard` keeps its current behaviour by composing that shell with the onboarding
 store; the popup surface composes the same shell with notification state.
 
-**B. ucm — the popup surface.** A component that selects popup-eligible notifications from
-notification state, renders them through the shell, marks `seen` on display and `dismissed` on close,
-and subscribes to NOTIF-13's popup envelope type so a popup can appear live. Export additively from
-`src/index.js`.
+**B. ucm — the popup surface.** A component that renders popup-eligible notifications through the
+shell, marks `seen` on display and `dismissed` on close. For live popups it subscribes via
+`useRealtime()` to the **`"notification"` envelope** (`DEFAULT_ENVELOPE` — there is no popup-specific
+envelope, see D) and filters on `channel === "popup"`, ignoring `notification.status` messages and
+channel-less legacy payloads. Export additively from `src/index.js`.
 
 **C. Coexistence rule with onboarding — specify and test it.** Both surfaces render a MUI `Dialog`, so
 two modals can be open at once. Required behaviour: **a blocking onboarding step wins**; the popup
 waits until no blocking onboarding step is active. Non-blocking coexistence must not stack two dialogs.
 
-**D. dcm — implement `PopupDispatcher.deliver`.** Emit NOTIF-13's envelope over `push_to_users` and
-return `DeliveryResult(ok=True)`. Keep the delivery-record semantics identical to `ChipDispatcher`
-(the surrounding `dispatch()` machinery already records pending → sent/failed; do not re-implement it).
+**D. dcm — implement `PopupDispatcher.deliver`, with a channel discriminator *inside* the envelope.**
+Emit through `notification_envelope()` (so Layer-1 routing stays domain-keyed and messaging can still
+ride alongside) and add an explicit **`"channel": "popup"`** field to the payload. Return
+`DeliveryResult(ok=True)`. Keep delivery-record semantics identical to `ChipDispatcher` — the
+surrounding `dispatch()` machinery already records pending → sent/failed; do not re-implement it.
+
+**Do NOT invent a second envelope value** (e.g. `"notification.popup"`). The envelope discriminates
+*domains* so a future messaging stream can share the socket; overloading it with channels would
+undo NOTIF-13's design. Channel selection belongs inside the payload.
+
+For symmetry and so the client can tell the cases apart, `ChipDispatcher` should carry
+`"channel": "chip"` as well. **Backward compatibility:** a payload with **no** `channel` field must
+keep behaving exactly as today (feed entry + unread increment), because an app pinned to an older dcm
+will still send channel-less payloads.
+
+**D2. ucm — de-duplicate by `notification_id` in `NotificationsProvider`.** A notification routed to
+both chip and popup now produces two WS messages. The provider must fold them into **one** feed entry
+and **one** unread increment (de-dupe on `notification_id`, last-write-wins on content). Without this,
+enabling popup alongside chip double-counts the badge. This is an edit to `NotificationsProvider`,
+which is explicitly in scope here — it is not part of NOTIF-13's realtime core.
 
 ## DO NOT TOUCH
 - **The onboarding progress store** — `markStepSeen`, `dismissStep`, `persistDismissed` persistence,
   `OnboardingProvider`'s step-selection semantics, `stepSelection.js`.
 - The four existing step components (`CookieConsentStep`, `CompleteNameStep`, `BrowserPushStep`,
   `PwaInstallStep`) and their props.
-- NOTIF-13's realtime core — **consume** `subscribe()`, do not restructure it.
+- **NOTIF-13's realtime core** (`src/notifications/realtime.jsx`) — consume `useRealtime()` /
+  `subscribe(envelope, handler)`, do not restructure it. In particular leave the `seeded` gate, the
+  backoff/reconnect semantics and the envelope-routing alone. (`NotificationsProvider` itself IS
+  editable — scope D2 requires it.)
 - `feed/*` REST contract, `NotificationBell`, `NotificationSettings`.
 - `prefs.py`, `router.py`, `resolve_channels` — popup already works there; a type opting in is an
   app-side change, not this WO's.
@@ -112,6 +148,14 @@ return `DeliveryResult(ok=True)`. Keep the delivery-record semantics identical t
   run in production. The step counter (`totalRef`/`completed`), the session-dismissed Set, and the
   `blocking` escape-key behaviour are easy to break silently.
 - **Stacked modals** if C is skipped — two dialogs, neither reachable.
+- **Badge double-count** if D2 is skipped: a notification routed to both chip and popup arrives as two
+  WS messages and increments `unreadCount` twice for one notification. This is the single most likely
+  silent defect in this WO.
+- **Popup storm** if B subscribes to the envelope without filtering on `channel` — every chip
+  notification would pop up a modal.
+- **Regressing the NOTIF-13 R1 fix:** the `seeded` gate in `NotificationsProvider` exists because
+  decoupling the REST seed from the socket connect opened a silent-message-loss race. Do not touch it
+  while implementing D2.
 - **Dead code rot:** with no producer, only the tests exercise the path. Hence the mandatory test-local
   producer type.
 - **Status semantics drift:** marking a popup `done` instead of `dismissed` would pollute todo-channel
@@ -126,12 +170,20 @@ ucm (`pnpm test`, vitest):
 - **onboarding regression guard:** existing `OnboardingWizard` behaviour unchanged — step counter,
   progress bar, session-dismissed set, `blocking` disabling escape/backdrop close, `persistDismissed`
   still calling `dismissStep`;
-- with no popup-eligible notification present, nothing renders.
+- with no popup-eligible notification present, nothing renders;
+- **no popup storm:** a `channel: "chip"` message and a channel-less legacy message both leave the
+  popup surface silent;
+- **no double-count (D2):** two WS messages for the same `notification_id` (one `chip`, one `popup`)
+  yield exactly one feed entry and `unreadCount + 1`;
+- **NOTIF-13 R1 guard:** the `seeded` gate still holds — no socket messages are processed before the
+  REST seed completes.
 
 dcm (`pytest` on the notifications package):
 - register a **test-local** notification type declaring `eligible_channels=["popup"]`, call `notify()`,
-  and assert the dispatcher delivered (`ok=True`) with NOTIF-13's envelope shape on the wire — the
-  end-to-end proof required by the scaffolding notice;
+  and assert the dispatcher delivered (`ok=True`) with `envelope: "notification"` **and**
+  `channel: "popup"` on the wire — the end-to-end proof required by the scaffolding notice;
+- a chip delivery still carries `envelope: "notification"` and now `channel: "chip"`, with every other
+  field unchanged (no regression for existing consumers);
 - `resolve_channels` still excludes `popup` for types that do not declare it (no accidental widening);
 - the existing `test_dispatch.py` registry assertion (`:25`) still passes.
 
@@ -157,6 +209,6 @@ exceeds ~2 min. stdout unbuffered. Exactly one final `RESULT: DONE|BLOCKED <reas
 ## MINI-HANDOVER (paste into a fresh Orchestrator session)
 ```
 Orchestrator: implement work-orders/NOTIF-12.md in ui-core-micha (main; scope D also touches
-django-core-micha). Check the hard gate first — NOTIF-13 must be landed and published. git pull,
-read the WO, then follow orchestrate-codex (Codex-first, own independent review, commit on green).
+django-core-micha). The NOTIF-13 gate is satisfied (ucm 2.13.0 / dcm 2.33.0). git pull, read the WO,
+then follow orchestrate-codex (Codex-first, own independent review, commit on green).
 ```