@actuate-media/cms-admin 0.12.1 → 0.13.0

package/dist/lib/api.js

@@ -3,6 +3,16 @@ let basePath = DEFAULT_BASE;
 export function setApiBase(path) {
     basePath = path;
 }
+/**
+ * Current API base path. Exposed so non-`fetch` consumers (in
+ * particular `EventSource` for SSE channels) can resolve URLs against
+ * the same prefix configured via `setApiBase()`. Keep this read-only
+ * — mutation must always flow through `setApiBase()` so we never have
+ * two callers with diverging views of the base.
+ */
+export function getApiBase() {
+    return basePath;
+}
 function getCsrfToken() {
     if (typeof document === 'undefined')
         return '';

package/dist/lib/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/lib/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/lib/api.ts"],"names":[],"mappings":"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"}

package/dist/lib/notifications-client.d.ts

@@ -58,6 +58,59 @@ export declare function listNotifications(opts?: ListNotificationsOptions): Prom
 export declare function unreadCount(): Promise<NotificationOutcome<number>>;
 export declare function markNotificationRead(id: string): Promise<NotificationOutcome<Notification>>;
 export declare function markAllNotificationsRead(): Promise<NotificationOutcome<number>>;
+/**
+ * Subscribe to the per-user SSE push channel that ships notifications
+ * the instant they're persisted server-side. Replaces the 30-second
+ * poll loop in the notification bell.
+ *
+ * The browser's native `EventSource` handles reconnection for us — on
+ * a server-initiated close (the stream caps at ~4 minutes by design),
+ * the connection re-opens automatically. We DO NOT abort the poll
+ * fallback in callers: SSE is a latency-win, the poll is what keeps
+ * multi-node deployments correct (each node only pushes to its own
+ * subscribers).
+ *
+ * Returns a `close()` function that callers MUST invoke on unmount —
+ * otherwise the browser keeps the connection open and we leak event
+ * listeners.
+ *
+ * `EventSource` itself isn't available in the JSDOM test environment;
+ * callers can inject a `factory` to substitute a test double. In
+ * production we fall back to the global `EventSource` when no factory
+ * is supplied.
+ */
+export interface NotificationStreamOptions {
+    /** Called for every `event: notification` frame. */
+    onNotification: (n: Notification) => void;
+    /** Called once on the `event: ready` frame. */
+    onReady?: (payload: {
+        userId: string;
+    }) => void;
+    /** Called on connection errors. Useful for falling back to the poll loop. */
+    onError?: (event: Event) => void;
+    /**
+     * Optional factory so unit tests can inject a fake `EventSource`,
+     * or a null sentinel when the environment lacks one (SSR, JSDOM
+     * without a polyfill). Production code can rely on the default
+     * (global `EventSource`).
+     */
+    factory?: (url: string) => EventSourceLike | null;
+}
+/**
+ * Minimal subset of the `EventSource` interface our subscriber relies
+ * on. Browsers ship the full DOM type; the admin only needs add/remove
+ * event listeners plus `close()`.
+ */
+export interface EventSourceLike {
+    addEventListener: (type: string, listener: (event: MessageEvent | Event) => void) => void;
+    removeEventListener?: (type: string, listener: (event: MessageEvent | Event) => void) => void;
+    close: () => void;
+}
+export interface NotificationStreamHandle {
+    /** Tear down the EventSource and stop receiving events. Idempotent. */
+    close: () => void;
+}
+export declare function subscribeNotificationStream(opts: NotificationStreamOptions): NotificationStreamHandle;
 /**
  * Cheap single-line summary for the bell list — the server gives us a
  * structured payload, but the dropdown wants one human-readable string

package/dist/lib/notifications-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notifications-client.d.ts","sourceRoot":"","sources":["../../src/lib/notifications-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,MAAM,gBAAgB,GAAG,eAAe,GAAG,kBAAkB,GAAG,iBAAiB,CAAA;AAEvF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAA;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,kBAAkB,CAAA;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,iBAAiB,CAAA;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,MAAM,mBAAmB,GAC3B,mBAAmB,GACnB,sBAAsB,GACtB,qBAAqB,CAAA;AAEzB,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,gBAAgB,CAAA;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,mBAAmB,CAAA;IAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,GACvB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEhD,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAyBD,wBAAsB,iBAAiB,CACrC,IAAI,GAAE,wBAA6B,GAClC,OAAO,CAAC,mBAAmB,CAAC,YAAY,EAAE,CAAC,CAAC,CAK9C;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAQxE;AAED,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,YAAY,CAAC,CAAC,CAOjG;AAED,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CASrF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,CAYtE"}
+{"version":3,"file":"notifications-client.d.ts","sourceRoot":"","sources":["../../src/lib/notifications-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,MAAM,gBAAgB,GAAG,eAAe,GAAG,kBAAkB,GAAG,iBAAiB,CAAA;AAEvF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAA;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,kBAAkB,CAAA;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,iBAAiB,CAAA;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,MAAM,mBAAmB,GAC3B,mBAAmB,GACnB,sBAAsB,GACtB,qBAAqB,CAAA;AAEzB,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,gBAAgB,CAAA;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,mBAAmB,CAAA;IAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,GACvB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEhD,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAyBD,wBAAsB,iBAAiB,CACrC,IAAI,GAAE,wBAA6B,GAClC,OAAO,CAAC,mBAAmB,CAAC,YAAY,EAAE,CAAC,CAAC,CAK9C;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAQxE;AAED,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,YAAY,CAAC,CAAC,CAOjG;AAED,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CASrF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,yBAAyB;IACxC,oDAAoD;IACpD,cAAc,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAA;IACzC,+CAA+C;IAC/C,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;IAC/C,6EAA6E;IAC7E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAChC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,eAAe,GAAG,IAAI,CAAA;CAClD;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,KAAK,IAAI,KAAK,IAAI,CAAA;IACzF,mBAAmB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,KAAK,IAAI,KAAK,IAAI,CAAA;IAC7F,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,uEAAuE;IACvE,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,yBAAyB,GAC9B,wBAAwB,CAqD1B;AAsCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,CAYtE"}

package/dist/lib/notifications-client.js

@@ -10,7 +10,7 @@
  * shape here to avoid taking a hard dependency on the server module
  * (which carries Prisma types that don't belong in the admin bundle).
  */
-import { cmsApi } from './api.js';
+import { cmsApi, getApiBase } from './api.js';
 function failure(error, status) {
     return { ok: false, error, status };
 }
@@ -63,6 +63,94 @@ export async function markAllNotificationsRead() {
     }
     return { ok: true, result: res.data.count };
 }
+export function subscribeNotificationStream(opts) {
+    // The `cmsApi()` helper handles base-path / origin resolution for
+    // fetch calls, but EventSource takes a raw URL. We mirror its
+    // logic locally — `/api/cms/notifications/stream` is correct for
+    // both the local dev server and any production deploy that mounts
+    // the CMS API at the default prefix. Custom prefixes are handled by
+    // the consumer override (factory).
+    // Resolve against `setApiBase()` so a consumer mounting the CMS at
+    // a non-default prefix (e.g. `/cms-api`) still hits the right SSE
+    // endpoint — `EventSource` doesn't go through `cmsApi()`, so we
+    // can't rely on its url-construction logic.
+    const url = `${getApiBase()}/notifications/stream`;
+    const make = opts.factory ?? defaultEventSourceFactory;
+    const source = make(url);
+    if (!source) {
+        // No EventSource available (SSR? JSDOM without polyfill? Or the
+        // injected factory deliberately returns null in tests). Return a
+        // no-op handle so callers can compose without conditional logic.
+        return { close: () => { } };
+    }
+    let closed = false;
+    const onReady = (event) => {
+        if (!opts.onReady)
+            return;
+        const data = parseEventData(event);
+        if (data && typeof data.userId === 'string') {
+            opts.onReady({ userId: data.userId });
+        }
+    };
+    const onNotification = (event) => {
+        const data = parseEventData(event);
+        if (data && isNotification(data)) {
+            opts.onNotification(data);
+        }
+    };
+    const onError = (event) => {
+        opts.onError?.(event);
+    };
+    source.addEventListener('ready', onReady);
+    source.addEventListener('notification', onNotification);
+    source.addEventListener('error', onError);
+    return {
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            source.removeEventListener?.('ready', onReady);
+            source.removeEventListener?.('notification', onNotification);
+            source.removeEventListener?.('error', onError);
+            source.close();
+        },
+    };
+}
+function defaultEventSourceFactory(url) {
+    if (typeof EventSource === 'undefined')
+        return null;
+    // `withCredentials: true` so the admin session cookie travels with
+    // the connection upgrade — every notification stream requires auth
+    // and the same-origin cookie is the only credential we trust here.
+    return new EventSource(url, { withCredentials: true });
+}
+function parseEventData(event) {
+    // EventSource emits MessageEvents with `data: string`. Plain
+    // `Event` (e.g. the `error` event) has no payload; ignore.
+    const data = event.data;
+    if (typeof data !== 'string')
+        return null;
+    try {
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+function isNotification(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    // Defensive: don't trust the wire blindly — verify the discriminant
+    // properties our consumers will read. A drift in the server-side
+    // wire format must surface as "missing fields" in the test suite,
+    // not as runtime errors deep in the bell's render path.
+    return (typeof v.id === 'string' &&
+        typeof v.userId === 'string' &&
+        typeof v.createdAt === 'string' &&
+        !!v.payload &&
+        typeof v.payload.kind === 'string');
+}
 /**
  * Cheap single-line summary for the bell list — the server gives us a
  * structured payload, but the dropdown wants one human-readable string

package/dist/lib/notifications-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"notifications-client.js","sourceRoot":"","sources":["../../src/lib/notifications-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"notifications-client.js","sourceRoot":"","sources":["../../src/lib/notifications-client.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actuate-media/cms-admin",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/actuate-media/actuatecms.git",
@@ -87,7 +87,7 @@
     "tailwindcss": "^4.0.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0",
-    "@actuate-media/cms-core": "0.22.0",
+    "@actuate-media/cms-core": "0.24.0",
     "@actuate-media/component-blocks": "0.2.0"
   },
   "scripts": {

package/src/__tests__/components/notification-bell.test.tsx

@@ -4,7 +4,12 @@ import React from 'react'
 import { act, fireEvent, render, screen, waitFor } from '@testing-library/react'
 
 import { NotificationBell, type NotificationsApi } from '../../components/NotificationBell.js'
-import type { Notification, NotificationOutcome } from '../../lib/notifications-client.js'
+import type {
+  Notification,
+  NotificationOutcome,
+  NotificationStreamHandle,
+  NotificationStreamOptions,
+} from '../../lib/notifications-client.js'
 
 function ok<T>(value: T): NotificationOutcome<T> {
   return { ok: true, result: value }
@@ -211,3 +216,164 @@ describe('NotificationBell — dropdown', () => {
     await waitFor(() => expect(onError).toHaveBeenCalledWith('CSRF'))
   })
 })
+
+// ---------------------------------------------------------------------------
+// SSE push channel (Phase 7) — verify the bell wires up subscribe(),
+// processes incoming notifications, and tears down on unmount.
+// ---------------------------------------------------------------------------
+describe('NotificationBell — SSE push', () => {
+  function withSubscribe(api: NotificationsApi) {
+    let captured: NotificationStreamOptions | undefined
+    let closed = false
+    const handle: NotificationStreamHandle = {
+      close: () => {
+        closed = true
+      },
+    }
+    const subscribe = vi.fn((opts: NotificationStreamOptions) => {
+      captured = opts
+      return handle
+    })
+    return {
+      api: { ...api, subscribe },
+      push: (n: Notification) => captured?.onNotification(n),
+      pushError: (e: Event) => captured?.onError?.(e),
+      isClosed: () => closed,
+    }
+  }
+
+  it('subscribes on mount and bumps the badge when a new notification arrives', async () => {
+    const fake = createFakeApi()
+    const wired = withSubscribe(fake.api)
+    render(<NotificationBell api={wired.api} pollIntervalMs={0} />)
+    await waitFor(() => expect(fake.api.unread).toHaveBeenCalled())
+    await act(async () => {
+      wired.push(row({ id: 'sse-1' }))
+    })
+    await waitFor(() => expect(screen.getByTestId('bell-badge').textContent).toBe('1'))
+  })
+
+  it('does not double-count a notification that arrives via both SSE and REST', async () => {
+    const fake = createFakeApi()
+    const wired = withSubscribe(fake.api)
+    fake.setRows([row({ id: 'race' })])
+    render(<NotificationBell api={wired.api} pollIntervalMs={0} />)
+    // Open the dropdown so the row is in `items` from the REST list.
+    await waitFor(() => expect(screen.getByTestId('bell-badge').textContent).toBe('1'))
+    fireEvent.click(screen.getByTestId('bell-button'))
+    await waitFor(() => expect(screen.getByTestId('bell-row-race')).toBeTruthy())
+    // Now push the same row via SSE — must NOT add a duplicate or
+    // bump the badge above 1.
+    await act(async () => {
+      wired.push(row({ id: 'race' }))
+    })
+    expect(screen.getAllByTestId('bell-row-race')).toHaveLength(1)
+    expect(screen.getByTestId('bell-badge').textContent).toBe('1')
+  })
+
+  it('prepends new pushed rows to the open dropdown', async () => {
+    const fake = createFakeApi()
+    const wired = withSubscribe(fake.api)
+    fake.setRows([row({ id: 'old' })])
+    render(<NotificationBell api={wired.api} pollIntervalMs={0} />)
+    await waitFor(() => expect(screen.getByTestId('bell-badge').textContent).toBe('1'))
+    fireEvent.click(screen.getByTestId('bell-button'))
+    await waitFor(() => expect(screen.getByTestId('bell-row-old')).toBeTruthy())
+    await act(async () => {
+      wired.push(row({ id: 'fresh' }))
+    })
+    const rows = screen.getAllByTestId(/^bell-row-/)
+    expect(rows[0]!.getAttribute('data-testid')).toBe('bell-row-fresh')
+  })
+
+  it('does NOT bump the badge when the pushed notification is already read', async () => {
+    const fake = createFakeApi()
+    const wired = withSubscribe(fake.api)
+    render(<NotificationBell api={wired.api} pollIntervalMs={0} />)
+    await waitFor(() => expect(fake.api.unread).toHaveBeenCalled())
+    await act(async () => {
+      wired.push(row({ id: 'already-read', readAt: '2026-01-02T00:00:00.000Z' }))
+    })
+    // Already-read notifications still appear in the list when the
+    // user opens the dropdown with includeRead=true, but they must
+    // NOT register a fresh unread bump.
+    expect(screen.queryByTestId('bell-badge')).toBeNull()
+  })
+
+  it('closes the SSE subscription when the bell unmounts', async () => {
+    const fake = createFakeApi()
+    const wired = withSubscribe(fake.api)
+    const { unmount } = render(<NotificationBell api={wired.api} pollIntervalMs={0} />)
+    await waitFor(() => expect(fake.api.unread).toHaveBeenCalled())
+    unmount()
+    expect(wired.isClosed()).toBe(true)
+  })
+
+  it('does not surface transient SSE errors via onError (poll loop handles convergence)', async () => {
+    const fake = createFakeApi()
+    const wired = withSubscribe(fake.api)
+    const onError = vi.fn()
+    render(<NotificationBell api={wired.api} pollIntervalMs={0} onError={onError} />)
+    await waitFor(() => expect(fake.api.unread).toHaveBeenCalled())
+    await act(async () => {
+      wired.pushError(new Event('error'))
+    })
+    // Deliberately quiet — see NotificationBell SSE handler comment.
+    expect(onError).not.toHaveBeenCalled()
+  })
+
+  it('mark-all-read failure does not drop SSE rows that arrived mid-flight', async () => {
+    const fake = createFakeApi()
+    const wired = withSubscribe(fake.api)
+    fake.setRows([row({ id: 'before' })])
+    // Hold the markAllRead promise so we can interleave an SSE push.
+    let resolveMark: (v: NotificationOutcome<number>) => void = () => undefined
+    ;(wired.api.markAllRead as ReturnType<typeof vi.fn>).mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveMark = resolve
+        }),
+    )
+    const onError = vi.fn()
+    render(<NotificationBell api={wired.api} pollIntervalMs={0} onError={onError} />)
+    await waitFor(() => expect(screen.getByTestId('bell-badge').textContent).toBe('1'))
+    fireEvent.click(screen.getByTestId('bell-button'))
+    await waitFor(() => expect(screen.getByTestId('bell-row-before')).toBeTruthy())
+
+    // Click mark-all — handler optimistically marks 'before' read,
+    // but the API promise is still pending.
+    await act(async () => {
+      fireEvent.click(screen.getByTestId('bell-mark-all'))
+    })
+    // While in flight, a fresh notification arrives via SSE.
+    await act(async () => {
+      wired.push(row({ id: 'mid-flight' }))
+    })
+
+    // Now resolve the API with a failure.
+    await act(async () => {
+      resolveMark({ ok: false, error: 'server', status: 500 })
+      // flush promise chain
+      await Promise.resolve()
+    })
+
+    expect(onError).toHaveBeenCalledWith('server')
+    // The original row was rolled back to unread...
+    expect(screen.getByTestId('bell-row-before').getAttribute('data-read')).toBe('false')
+    // ...and the SSE arrival is still present (not dropped by the
+    // legacy snapshot-replace rollback).
+    expect(screen.getByTestId('bell-row-mid-flight')).toBeTruthy()
+  })
+
+  it('still mounts cleanly when api.subscribe is undefined (no SSE support)', async () => {
+    const fake = createFakeApi()
+    // Strip the `subscribe` member entirely — defaultApi has it,
+    // but consumer-provided test APIs may not.
+    const apiWithoutSubscribe: NotificationsApi = { ...fake.api }
+    delete (apiWithoutSubscribe as { subscribe?: unknown }).subscribe
+    render(<NotificationBell api={apiWithoutSubscribe} pollIntervalMs={0} />)
+    await waitFor(() => expect(fake.api.unread).toHaveBeenCalled())
+    // No crash, badge from unread() shows nothing, no items.
+    expect(screen.queryByTestId('bell-badge')).toBeNull()
+  })
+})

package/src/__tests__/lib/notifications-client.test.ts

@@ -3,6 +3,10 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 const cmsApiMock = vi.fn()
 vi.mock('../../lib/api.js', () => ({
   cmsApi: (...args: unknown[]) => cmsApiMock(...args),
+  // SSE uses EventSource, which doesn't go through cmsApi. The
+  // helper resolves the URL via getApiBase() — return the production
+  // default so tests don't need to know the prefix.
+  getApiBase: () => '/api/cms',
 }))
 
 const {
@@ -10,9 +14,14 @@ const {
   markAllNotificationsRead,
   markNotificationRead,
   notificationSummary,
+  subscribeNotificationStream,
   unreadCount,
 } = await import('../../lib/notifications-client.js')
-import type { Notification } from '../../lib/notifications-client.js'
+import type {
+  EventSourceLike,
+  Notification,
+  NotificationStreamOptions,
+} from '../../lib/notifications-client.js'
 
 function row(overrides: Partial<Notification> = {}): Notification {
   return {
@@ -193,3 +202,138 @@ describe('notificationSummary', () => {
     ).toMatch(/^Someone replied/)
   })
 })
+
+// ---------------------------------------------------------------------------
+// SSE push channel — subscribeNotificationStream
+// ---------------------------------------------------------------------------
+
+/**
+ * In-memory `EventSource` double. Tests drive the wire by invoking
+ * `emit(event, payload)`; the subscriber dispatches the right
+ * listener. We deliberately keep the shape minimal — `EventSource`
+ * has dozens of properties our admin doesn't touch.
+ */
+function makeFakeSource() {
+  const listeners = new Map<string, Set<(e: MessageEvent | Event) => void>>()
+  let closed = false
+  const source: EventSourceLike = {
+    addEventListener: (type, listener) => {
+      if (closed) return
+      let set = listeners.get(type)
+      if (!set) {
+        set = new Set()
+        listeners.set(type, set)
+      }
+      set.add(listener)
+    },
+    removeEventListener: (type, listener) => {
+      listeners.get(type)?.delete(listener)
+    },
+    close: () => {
+      closed = true
+      listeners.clear()
+    },
+  }
+  return {
+    source,
+    listenerCount: (type: string) => listeners.get(type)?.size ?? 0,
+    isClosed: () => closed,
+    emit(type: string, payload: unknown) {
+      const set = listeners.get(type)
+      if (!set) return
+      const event =
+        typeof payload === 'string'
+          ? ({ data: payload } as MessageEvent)
+          : payload === undefined
+            ? (new Event(type) as Event)
+            : ({ data: JSON.stringify(payload) } as MessageEvent)
+      for (const l of [...set]) l(event)
+    },
+  }
+}
+
+function startStream(
+  fake: ReturnType<typeof makeFakeSource>,
+  overrides: Partial<NotificationStreamOptions> = {},
+) {
+  return subscribeNotificationStream({
+    onNotification: () => undefined,
+    factory: () => fake.source,
+    ...overrides,
+  })
+}
+
+describe('subscribeNotificationStream', () => {
+  it('dispatches `notification` frames as Notification objects', () => {
+    const fake = makeFakeSource()
+    const seen: Notification[] = []
+    startStream(fake, { onNotification: (n) => seen.push(n) })
+    fake.emit('notification', row({ id: 'sse-1' }))
+    expect(seen.map((n) => n.id)).toEqual(['sse-1'])
+  })
+
+  it('dispatches `ready` frames once via onReady', () => {
+    const fake = makeFakeSource()
+    const readys: Array<{ userId: string }> = []
+    startStream(fake, { onReady: (p) => readys.push(p) })
+    fake.emit('ready', { userId: 'user-1' })
+    expect(readys).toEqual([{ userId: 'user-1' }])
+  })
+
+  it('ignores malformed payloads (defence against wire drift)', () => {
+    const fake = makeFakeSource()
+    const seen: Notification[] = []
+    startStream(fake, { onNotification: (n) => seen.push(n) })
+    // Missing id + payload — must not throw, must not deliver.
+    fake.emit('notification', { userId: 'user-1', createdAt: 'now' })
+    fake.emit('notification', 'not json')
+    expect(seen).toEqual([])
+  })
+
+  it('removes its listeners and closes the underlying source on close()', () => {
+    const fake = makeFakeSource()
+    const handle = startStream(fake)
+    expect(fake.listenerCount('notification')).toBe(1)
+    expect(fake.listenerCount('ready')).toBe(1)
+    expect(fake.listenerCount('error')).toBe(1)
+    handle.close()
+    expect(fake.isClosed()).toBe(true)
+    // Second close() is a no-op — guards against double-unmount loops.
+    handle.close()
+    expect(fake.isClosed()).toBe(true)
+  })
+
+  it('returns a no-op handle when no EventSource is available', () => {
+    // No factory + no global EventSource (vitest jsdom env doesn't
+    // ship one). The subscriber must NOT throw — admin code must
+    // remain mountable in SSR / Node environments.
+    const handle = subscribeNotificationStream({
+      onNotification: () => undefined,
+      factory: () => null,
+    })
+    expect(() => handle.close()).not.toThrow()
+  })
+
+  it('forwards error events to onError without crashing the page', () => {
+    const fake = makeFakeSource()
+    const errors: Event[] = []
+    startStream(fake, { onError: (e) => errors.push(e) })
+    fake.emit('error', undefined)
+    expect(errors).toHaveLength(1)
+  })
+
+  it('builds the stream URL from getApiBase() so consumers with a custom prefix connect to the right host', () => {
+    // Custom factory inspects the URL it's handed. Verifies the
+    // subscriber composes /<base>/notifications/stream rather than
+    // hardcoding the production prefix.
+    const seen: string[] = []
+    subscribeNotificationStream({
+      onNotification: () => undefined,
+      factory: (url) => {
+        seen.push(url)
+        return null
+      },
+    })
+    expect(seen).toEqual(['/api/cms/notifications/stream'])
+  })
+})