@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.5

package/dist/notifications/headless/browserNotifications.js

@@ -0,0 +1,326 @@
+/**
+ * The native `Notification` Web API — the calls this app makes against it.
+ *
+ * Issue #127, epic #109. Issue #222 adds the service-worker delivery path.
+ *
+ * =============================================================================
+ * THIS IS DECORATION. THE NOTIFICATION CENTRE IS THE FEATURE.
+ * =============================================================================
+ *
+ * Everything in this file can fail, be blocked, or be unavailable, and the
+ * product must be unaffected. Permission is denied by a large fraction of users
+ * and cannot be re-requested; the API does not exist in a non-secure context or
+ * under the test runner's jsdom; some hardened browsers define `Notification`
+ * and throw on touching it. So every function here DEGRADES SILENTLY and none
+ * of them throws.
+ *
+ * The durable surface is `GET /api/notifications` behind the bell, which works
+ * with permission denied, with the SSE stream down, and in a browser that has
+ * never heard of `Notification`. Epic #109 is explicit that a feature existing
+ * only as an OS toast does not exist at all for the users who denied it. That
+ * includes browsers where the toast can ONLY be raised through a service
+ * worker registration (Android Chrome) — see `showAppNotification` below,
+ * which is why this file now has two ways to raise the same toast instead of
+ * one.
+ *
+ * SEPARATED FROM `hooks/useBrowserNotificationPermission.ts` ON PURPOSE. That
+ * hook only OBSERVES permission; this module ACTS. "What prompts, and when?"
+ * is answered by this file's callers — see `requestBrowserNotificationPermission`.
+ */
+/**
+ * Dispatched on `window` after every permission request settles, so every
+ * mounted `useBrowserNotificationPermission` re-reads at once — the app-wide
+ * banner and the settings page stay in agreement whichever of them (or the
+ * auto-prompt) asked. Browsers without a Permissions API `change` event for
+ * notifications would otherwise wait for the next `visibilitychange`.
+ */
+export const NOTIFICATION_PERMISSION_CHANGED_EVENT = 'app:notification-permission-changed';
+function announcePermissionChanged() {
+    try {
+        window.dispatchEvent(new Event(NOTIFICATION_PERMISSION_CHANGED_EVENT));
+    }
+    catch {
+        // Nothing listening can be helped by a throw here.
+    }
+}
+/** Is the constructor there at all, and safe to touch? */
+function isSupported() {
+    if (typeof window === 'undefined' || !('Notification' in window))
+        return false;
+    try {
+        // The ACCESS is the test, not the presence of the key. Some embedded and
+        // privacy-hardened browsers expose `Notification` and throw on reading
+        // `permission` — the same defence `useBrowserNotificationPermission` takes,
+        // for the same reason.
+        void window.Notification.permission;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ask the browser for permission.
+ *
+ * =============================================================================
+ * WHO CALLS THIS (#365)
+ * =============================================================================
+ *
+ * Always through `requestPermissionAndSyncPush` (`services/pushSubscription.ts`),
+ * from three places:
+ *
+ *   * THE AUTO-PROMPT — `hooks/usePushSubscriptionSync.ts`, once per page load,
+ *     only when the deployment has push enabled and the device is `default`.
+ *     A product decision (#365) that reverses the earlier click-only rule:
+ *     push is worthless without permission, so the shell asks up front.
+ *   * The app-wide `NotificationPermissionBanner`'s "Enable notifications"
+ *     button.
+ *   * The "Allow notifications" button on `/settings/notifications`.
+ *
+ * The buttons still matter after the auto-prompt: Firefox ignores a request
+ * with no user gesture, Safari may throw, and Chrome can demote it to a quiet
+ * UI. A denial remains effectively permanent — only the user can undo it in
+ * site settings — so nothing may call this in a loop or on every render.
+ *
+ * @returns the resulting permission, or `null` when the browser has no usable
+ *          `Notification` API. The caller should refresh its permission state
+ *          from `useBrowserNotificationPermission().refresh()` regardless of
+ *          what comes back — that hook is the single source of truth for what
+ *          the UI renders, and this return value is only what one call happened
+ *          to see.
+ */
+export async function requestBrowserNotificationPermission() {
+    if (!isSupported())
+        return null;
+    try {
+        // `Notification.requestPermission()` has two signatures across browsers —
+        // a promise (modern, everywhere current) and a legacy callback (old Safari).
+        // `await` handles the promise form and, on the callback form, simply
+        // resolves the `undefined` it returns; the UI is refreshed from
+        // `Notification.permission` afterwards either way, so the legacy path
+        // degrades to "the banner updates on the next visibility change" rather
+        // than to a broken button.
+        const result = await window.Notification.requestPermission();
+        return result ?? window.Notification.permission;
+    }
+    catch {
+        // A throw here is a browser that refuses the request outright. Not an error
+        // worth surfacing: the permission state is unchanged, and the banner that
+        // prompted the click already explains what is going on.
+        return null;
+    }
+    finally {
+        announcePermissionChanged();
+    }
+}
+/**
+ * Try the page-`Notification` constructor path — the ONLY path that existed
+ * before #222, and now the FALLBACK for browsers that either have no service
+ * worker registration or where the SW call itself failed.
+ *
+ * Kept as its own function rather than inlined into `showAppNotification`
+ * because it is also the emergency exit when the SW attempt throws for a
+ * reason that has nothing to do with Android's SW-only restriction (a
+ * misbehaving embedded browser, a registration stuck mid-update, etc) — one
+ * `try` around one call, reused from two call sites instead of duplicated.
+ *
+ * @param onClick - invoked when the user activates the toast. The window is
+ *        focused first, because a toast is clicked from outside the browser and
+ *        navigating a background tab the user cannot see is not a useful
+ *        outcome. THIS FOCUS/ONCLICK WIRING HAS NO EQUIVALENT ON THE SW PATH —
+ *        `ServiceWorkerRegistration.showNotification()` returns no handle to
+ *        attach a JS `onclick` to; a clicked SW toast instead fires a
+ *        `notificationclick` event inside the worker, which is issue #223's
+ *        job to wire up (`postMessage` back to an open tab, or open one). That
+ *        is a real, currently-unfilled gap on the SW path, not an oversight in
+ *        this function.
+ * @returns whether a toast was actually raised this way.
+ */
+function showPageNotification(notification, onClick) {
+    try {
+        const toast = new window.Notification(notification.title, {
+            body: notification.body,
+            // `tag` COLLAPSES DUPLICATES. The API publishes to every connection the
+            // user has open, so someone with four tabs receives four copies of the
+            // same event and would otherwise get four identical OS toasts. Tagging by
+            // the notification's id makes the browser replace rather than stack them,
+            // which is the only mechanism available — the tabs cannot coordinate, and
+            // adding cross-tab leader election for a toast would be far more machinery
+            // than the problem deserves.
+            tag: notification.id,
+            // NOT `renotify`. With the tag above, re-notifying would restore exactly
+            // the duplicate alerting the tag exists to suppress.
+        });
+        if (onClick) {
+            toast.onclick = () => {
+                try {
+                    // The user clicked something outside the browser; without this the
+                    // navigation happens in a window they still cannot see.
+                    window.focus();
+                    onClick(notification);
+                }
+                finally {
+                    // Dismiss it ourselves. Platform behaviour on click varies — some
+                    // leave the toast sitting in a notification centre — and a toast that
+                    // outlives the click that handled it invites a second one.
+                    toast.close();
+                }
+            };
+        }
+        return true;
+    }
+    catch {
+        // Constructing a `Notification` throws on Android Chrome, where the API is
+        // service-worker-only. That is a supported outcome, not a bug: the
+        // notification is already in the centre and the bell already shows it.
+        return false;
+    }
+}
+/**
+ * Raise a native toast for a notification that just arrived over SSE.
+ *
+ * SILENT NO-OP unless permission is ALREADY `granted`. It never requests —
+ * requesting from an incoming event would fire a prompt with no user gesture,
+ * which is the failure mode the whole permission section above exists to
+ * prevent.
+ *
+ * =============================================================================
+ * WHY THE SERVICE-WORKER PATH IS TRIED FIRST (#222)
+ * =============================================================================
+ *
+ * `new Notification(...)` THROWS ON ANDROID CHROME. The page constructor is
+ * disabled there on purpose — Android requires every web notification to go
+ * through a service worker registration's `showNotification()`, full stop.
+ * Before this function existed, `showNativeNotification` only knew the page
+ * path, so on Android the `catch` below was reached on every single arrival
+ * and the toast silently never appeared — which is the bug #222 exists to
+ * fix. Trying the page constructor FIRST and falling back to the SW would
+ * "work" on every desktop browser and never once fire on Android, so the
+ * order here is not a preference, it is the fix.
+ *
+ * =============================================================================
+ * WHY `getRegistration()` AND NOT `navigator.serviceWorker.ready`
+ * =============================================================================
+ *
+ * `.ready` is a promise that resolves once a service worker controls the
+ * page — and NEVER RESOLVES AT ALL if that never happens. This app's SW
+ * self-registers via `vite-plugin-pwa`'s auto-injected register script (see
+ * `vite.config.ts`'s `injectRegister: 'auto'`), but nothing here guarantees
+ * that registration has completed, or ever will (registration can fail, be
+ * disabled by the browser, or simply not have run yet on this page load).
+ * Awaiting `.ready` in that situation would hang this function's `await`
+ * forever, and a notification path that can hang forever is worse than one
+ * that occasionally falls back to the page path. `getRegistration()` instead
+ * resolves immediately either way — with a registration, or with
+ * `undefined` — which is the only shape compatible with "never throws, never
+ * hangs".
+ *
+ * =============================================================================
+ * WHY THE PAGE PATH STAYS, AS A FALLBACK
+ * =============================================================================
+ *
+ * Desktop Safari has no bar against `new Notification(...)` and this app does
+ * not currently register a service worker there in every configuration; more
+ * generally, any browser where SW registration failed, is still in flight, or
+ * was rejected by the user's settings still deserves a toast if permission is
+ * independently `granted`. Falling back — rather than requiring a SW — keeps
+ * every browser this worked on before #222 working exactly as before.
+ *
+ * @param onClick - invoked when the user activates the toast — see
+ *        `showPageNotification` above for why this ONLY fires on the page
+ *        path, never on the SW path.
+ * @returns which path actually raised the toast (`'sw'` or `'page'`), or
+ *          `'none'` if neither did — including when the SW path found this
+ *          exact tag already showing (#224's cross-tab dedup) and deliberately
+ *          skipped raising a second one. For tests and diagnostics; no caller
+ *          makes a decision from it, because there is no fallback to fall
+ *          back to — the notification is already in the centre.
+ */
+export async function showAppNotification(notification, onClick) {
+    try {
+        if (!isSupported())
+            return 'none';
+        if (window.Notification.permission !== 'granted')
+            return 'none';
+        if ('serviceWorker' in navigator) {
+            try {
+                // NOT `.ready` — see the doc comment above for why that can hang
+                // forever. `getRegistration()` resolves immediately with `undefined`
+                // when there is none.
+                const registration = await navigator.serviceWorker.getRegistration();
+                // Defensive: some unusual embedded WebViews expose `serviceWorker`
+                // and return a registration-shaped object without a working
+                // `showNotification` method. Checking the method itself, rather than
+                // trusting the type, is the same posture `isSupported()` above takes
+                // with `Notification.permission`.
+                if (registration && typeof registration.showNotification === 'function') {
+                    // =====================================================================
+                    // #224 — CROSS-TAB DEDUP, REGISTRATION-WIDE
+                    // =====================================================================
+                    //
+                    // The API publishes to every open connection, so a user with four tabs
+                    // on this origin receives four `notification` stream frames for the
+                    // same event — one per tab — and without this check each tab would
+                    // independently reach this line and raise its own OS toast: four
+                    // popups for one notification.
+                    //
+                    // `getNotifications({ tag })` reads the OS notification tray through
+                    // the SERVICE WORKER REGISTRATION, which is shared by every tab of
+                    // this origin, not the calling tab's own state. So this is not "have
+                    // I shown this before" (which would need per-tab memory this module
+                    // deliberately doesn't keep) — it's "does a toast with this tag exist
+                    // anywhere right now, raised by any tab, including one that is racing
+                    // this one this very instant". `tag` is already the notification's id
+                    // (set below, and on the page path in `showPageNotification`), so an
+                    // existing entry can ONLY be this exact notification.
+                    //
+                    // This is why it beats the alternative the issue's write-up considered
+                    // and rejected — cross-tab leader election: that needs a coordination
+                    // protocol (BroadcastChannel, localStorage locks, a chosen leader tab)
+                    // that itself has failure modes (the leader tab closes mid-election,
+                    // two tabs both think they won a race). Reading the registration's own
+                    // notification list has none of that: there is nothing to coordinate,
+                    // because the browser already maintains one shared list per
+                    // registration and `tag` already collapses entries within it.
+                    //
+                    // Defensive `typeof` check for the same reason `showNotification`
+                    // above gets one: some embedded WebViews expose a registration-shaped
+                    // object with gaps in its method set. A missing `getNotifications`
+                    // degrades to "no dedup this call", not a thrown error — silent
+                    // degradation is this file's whole contract (see the header comment).
+                    if (typeof registration.getNotifications === 'function') {
+                        const existing = await registration.getNotifications({ tag: notification.id });
+                        if (existing.length > 0)
+                            return 'none';
+                    }
+                    await registration.showNotification(notification.title, {
+                        body: notification.body,
+                        tag: notification.id,
+                        icon: '/icons/icon-192.png',
+                        badge: '/icons/badge-96.png',
+                        // Not read by anything yet. This is forward-prep for issue #223's
+                        // `notificationclick` handler inside the service worker, which
+                        // needs the id (to tell the centre what was clicked) and the link
+                        // (to navigate) and has no other way to get either — a SW toast
+                        // carries no JS closure the way `showPageNotification`'s does.
+                        data: { id: notification.id, link: notification.link },
+                    });
+                    return 'sw';
+                }
+            }
+            catch {
+                // Fall through to the page path below. A SW that exists but rejects
+                // `showNotification` (e.g. mid-update, or a browser bug) is not a
+                // reason to lose the toast entirely when the page path might still
+                // work.
+            }
+        }
+        return showPageNotification(notification, onClick) ? 'page' : 'none';
+    }
+    catch {
+        // Belt-and-braces: this function must never throw, no matter what a
+        // future edit above does.
+        return 'none';
+    }
+}
+//# sourceMappingURL=browserNotifications.js.map

package/dist/notifications/headless/browserNotifications.js.map

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

package/dist/notifications/headless/index.d.ts

@@ -0,0 +1,15 @@
+export { configureNotificationsWeb } from './api.js';
+export type { NotificationsApiClient, NotificationsRequestOptions, NotificationsWebConfig } from './api.js';
+export type { SseConnection, SseFrame, SseOptions, SseState } from './sse.js';
+export { NotificationProvider, useNotifications } from './NotificationContext.js';
+export type { NotificationContextValue } from './NotificationContext.js';
+export { useNotificationChannels } from './useNotificationChannels.js';
+export type { UseNotificationChannelsReturn } from './useNotificationChannels.js';
+export { usePushSubscriptionSync } from './usePushSubscriptionSync.js';
+export type { UsePushSubscriptionSyncResult } from './usePushSubscriptionSync.js';
+export type { NotificationCapability } from './useNotificationCapability.js';
+export { removePushSubscription, requestPermissionAndSyncPush } from './pushSubscription.js';
+export type { AppNotification, NotificationChannel, NotificationChannelDescriptor, NotificationChannelPreferences, NotificationChannelSwitch, NotificationChannelPreferencesPatch, NotificationConfigResponse, NotificationEventDef, NotificationListResponse, NotificationPreferences, NotificationPreferencesPatch, NotificationStreamEvent, NotificationsSystemSettingsDocument, NotificationsUserSettingsDocument, NotificationsUserSettingsUpdate, PushSubscriptionPayload, PushSubscriptionResponse, SystemNotificationSettings, UnreadCountResponse, } from './types.js';
+export { handleNotificationClick, handlePushEvent, handlePushSubscriptionChange, registerNotificationServiceWorkerHandlers, } from './service-worker.js';
+export type { NotificationAction, NotificationPushPayload, NotificationServiceWorkerOptions, NotificationsClickEvent, NotificationsExtendableEvent, NotificationsPushEvent, NotificationsPushSubscriptionChangeEvent, NotificationsServiceWorkerClient, NotificationsServiceWorkerScope, NotificationsShowOptions, } from './service-worker.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/notifications/headless/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/notifications/headless/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AACrD,YAAY,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAC5G,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAE9E,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAClF,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,YAAY,EAAE,6BAA6B,EAAE,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,YAAY,EAAE,6BAA6B,EAAE,MAAM,8BAA8B,CAAC;AAClF,YAAY,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAE7F,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,6BAA6B,EAC7B,8BAA8B,EAC9B,yBAAyB,EACzB,mCAAmC,EACnC,0BAA0B,EAC1B,oBAAoB,EACpB,wBAAwB,EACxB,uBAAuB,EACvB,4BAA4B,EAC5B,uBAAuB,EACvB,mCAAmC,EACnC,iCAAiC,EACjC,+BAA+B,EAC/B,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,4BAA4B,EAC5B,yCAAyC,GAC1C,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,gCAAgC,EAChC,uBAAuB,EACvB,4BAA4B,EAC5B,sBAAsB,EACtB,wCAAwC,EACxC,gCAAgC,EAChC,+BAA+B,EAC/B,wBAAwB,GACzB,MAAM,qBAAqB,CAAC"}

package/dist/notifications/headless/index.js

@@ -0,0 +1,15 @@
+// `@marinoscar/platform-web/notifications/headless`: the notifications web
+// slice's configuration, provider, hooks, services, wire types and the
+// service-worker helpers (issue #738, PP-8.5), with no component. Documented
+// in ../README.md.
+//
+// The service-worker helpers are DOM-free at import time (no React, no
+// `window`), so an app's `sw.ts` imports them from here without pulling the
+// page's code into the worker bundle (the package is `sideEffects: false`).
+export { configureNotificationsWeb } from './api.js';
+export { NotificationProvider, useNotifications } from './NotificationContext.js';
+export { useNotificationChannels } from './useNotificationChannels.js';
+export { usePushSubscriptionSync } from './usePushSubscriptionSync.js';
+export { removePushSubscription, requestPermissionAndSyncPush } from './pushSubscription.js';
+export { handleNotificationClick, handlePushEvent, handlePushSubscriptionChange, registerNotificationServiceWorkerHandlers, } from './service-worker.js';
+//# sourceMappingURL=index.js.map

package/dist/notifications/headless/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/notifications/headless/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,uEAAuE;AACvE,6EAA6E;AAC7E,mBAAmB;AACnB,EAAE;AACF,uEAAuE;AACvE,4EAA4E;AAC5E,4EAA4E;AAE5E,OAAO,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAIrD,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAElF,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,OAAO,EAAE,sBAAsB,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAwB7F,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,4BAA4B,EAC5B,yCAAyC,GAC1C,MAAM,qBAAqB,CAAC"}

package/dist/notifications/headless/internalLink.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Is this string safe to hand to the router as an in-app destination?
+ *
+ * Issue #127, epic #109. Used everywhere a notification's `link` turns into
+ * navigation: the row click in `components/navigation/NotificationBell.tsx`,
+ * the native toast click in `contexts/NotificationContext.tsx`, and — since
+ * issue #223 — the `notificationclick` handler in `sw.ts`, which re-validates
+ * the SAME value the service worker will hand to `clients.openWindow()`.
+ *
+ * =============================================================================
+ * THE SERVER ALREADY GUARANTEES THIS. CHECKING AGAIN IS THE POINT.
+ * =============================================================================
+ *
+ * `AppNotification.link` is validated by the API's `sanitizeLink` BEFORE the row
+ * is written, so by contract it is always a single leading `/` with no scheme
+ * and no protocol-relative `//`. This function re-checks that contract at the
+ * point of use, for two reasons:
+ *
+ *   1. The guarantee is kept on the WRITE side, which means it holds for rows
+ *      written by today's code. It says nothing about a row written by an older
+ *      build, seeded by hand, or restored from a backup taken before the
+ *      sanitiser existed.
+ *   2. The cost is one comparison and the failure it prevents is open redirect
+ *      — `javascript:` reaching a navigation, or `//evil.example` being read by
+ *      the browser as a protocol-relative URL to another origin and rendering a
+ *      convincing login page. A defence-in-depth check whose entire cost is two
+ *      `startsWith` calls does not need to justify itself further.
+ *
+ * WHAT IT ACCEPTS: exactly root-relative paths — `/settings`, `/admin/users?tab=1`.
+ * WHAT IT REJECTS: everything else, including `//host` (protocol-relative),
+ * `https://…`, `javascript:…`, and bare relative paths like `settings`, which
+ * would resolve against whatever route the user happens to be on and so mean
+ * something different depending on where they clicked from.
+ */
+export declare function isInternalLink(link: string | null | undefined): link is string;
+//# sourceMappingURL=internalLink.d.ts.map

package/dist/notifications/headless/internalLink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internalLink.d.ts","sourceRoot":"","sources":["../../../src/notifications/headless/internalLink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,IAAI,MAAM,CAM9E"}

package/dist/notifications/headless/internalLink.js

@@ -0,0 +1,43 @@
+/**
+ * Is this string safe to hand to the router as an in-app destination?
+ *
+ * Issue #127, epic #109. Used everywhere a notification's `link` turns into
+ * navigation: the row click in `components/navigation/NotificationBell.tsx`,
+ * the native toast click in `contexts/NotificationContext.tsx`, and — since
+ * issue #223 — the `notificationclick` handler in `sw.ts`, which re-validates
+ * the SAME value the service worker will hand to `clients.openWindow()`.
+ *
+ * =============================================================================
+ * THE SERVER ALREADY GUARANTEES THIS. CHECKING AGAIN IS THE POINT.
+ * =============================================================================
+ *
+ * `AppNotification.link` is validated by the API's `sanitizeLink` BEFORE the row
+ * is written, so by contract it is always a single leading `/` with no scheme
+ * and no protocol-relative `//`. This function re-checks that contract at the
+ * point of use, for two reasons:
+ *
+ *   1. The guarantee is kept on the WRITE side, which means it holds for rows
+ *      written by today's code. It says nothing about a row written by an older
+ *      build, seeded by hand, or restored from a backup taken before the
+ *      sanitiser existed.
+ *   2. The cost is one comparison and the failure it prevents is open redirect
+ *      — `javascript:` reaching a navigation, or `//evil.example` being read by
+ *      the browser as a protocol-relative URL to another origin and rendering a
+ *      convincing login page. A defence-in-depth check whose entire cost is two
+ *      `startsWith` calls does not need to justify itself further.
+ *
+ * WHAT IT ACCEPTS: exactly root-relative paths — `/settings`, `/admin/users?tab=1`.
+ * WHAT IT REJECTS: everything else, including `//host` (protocol-relative),
+ * `https://…`, `javascript:…`, and bare relative paths like `settings`, which
+ * would resolve against whatever route the user happens to be on and so mean
+ * something different depending on where they clicked from.
+ */
+export function isInternalLink(link) {
+    if (typeof link !== 'string' || link === '')
+        return false;
+    // `//` is checked SECOND but rejects first in effect: a protocol-relative URL
+    // also starts with a single `/`, so testing only the leading slash would let
+    // `//evil.example` through as "root-relative".
+    return link.startsWith('/') && !link.startsWith('//');
+}
+//# sourceMappingURL=internalLink.js.map

package/dist/notifications/headless/internalLink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internalLink.js","sourceRoot":"","sources":["../../../src/notifications/headless/internalLink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,cAAc,CAAC,IAA+B;IAC5D,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC1D,8EAA8E;IAC9E,6EAA6E;IAC7E,+CAA+C;IAC/C,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACxD,CAAC"}

package/dist/notifications/headless/notificationStream.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The notification stream — `GET /api/notifications/stream`, over the
+ * fetch-based SSE client.
+ *
+ * Issue #127, epic #109. Thin by design: everything about SSE framing,
+ * reconnection and backoff lives in core's `connectSse` (`core/http/sse.ts`), and everything about
+ * what a notification IS lives in `types/index.ts`. What is left here is the
+ * three things that are specific to this one stream — its URL, its frame name,
+ * and how a frame's `data` becomes something the notification centre can hold.
+ *
+ * =============================================================================
+ * ⚠️ THE STREAM IS NOT A DELIVERY GUARANTEE. READ THIS BEFORE RELYING ON IT.
+ * =============================================================================
+ *
+ * There is no replay. The API buffers nothing, honours no `Last-Event-ID`, and
+ * keeps no log — anything published while this connection is down is simply
+ * never seen by this tab. `NotificationStreamService`'s own header says so, and
+ * it is a design decision rather than a gap to be filled later: the
+ * `notifications` TABLE is the source of truth, and one indexed query after a
+ * gap is strictly more reliable than any cursor built on top of a stream.
+ *
+ * Two consequences, and the second is the one that gets forgotten:
+ *
+ *   1. THE CALLER MUST REFETCH THE LIST AND THE UNREAD COUNT ON EVERY `onOpen`,
+ *      not merely on mount. `onOpen` fires on the first connection AND on every
+ *      reconnection, which is exactly the signal "there may have been a gap;
+ *      re-read the truth". `NotificationProvider` does this — see its
+ *      `handleOpen`. Delete that and the bell goes stale after the first
+ *      network blip, permanently, with nothing in any log to say why.
+ *
+ *   2. Even a connection that never drops can miss events. The API's stream
+ *      registry is PER PROCESS: with more than one API replica, a tab connected
+ *      to pod A receives nothing for an event published on pod B. The
+ *      notification is not lost — the row was written before the publish — but
+ *      the live nudge is. The same refetch-on-connect covers this, which is why
+ *      no separate mechanism exists for it.
+ *
+ * So: a missed frame is a missing TOAST, never a missing notification. Keep it
+ * that way. Anything that makes the centre's contents depend on having received
+ * a frame turns a degradation into a defect.
+ */
+import { type SseConnection, type SseState } from './sse.js';
+import type { AppNotification, NotificationStreamEvent } from './types.js';
+/**
+ * The `event:` name the API publishes notifications under.
+ *
+ * MUST MATCH `NOTIFICATION_SSE_EVENT` in
+ * `apps/api/src/notifications/notification-stream.service.ts`. The API names its
+ * frames rather than using the default `message` precisely so this client can
+ * ignore anything else the stream ever carries; the cost is that the string is
+ * declared in two repositories-worth of code and a rename must touch both. A
+ * mismatch fails SILENTLY — frames arrive, no listener matches, the bell simply
+ * never updates live — which is why it is a named constant here and compared
+ * explicitly rather than inlined into a condition.
+ */
+export declare const NOTIFICATION_SSE_EVENT = "notification";
+/** The stream's URL, resolved against the same base as every other API call. */
+export declare function notificationStreamUrl(): string;
+/**
+ * Parse one frame's `data` into a stream event, or `null` if it is not one.
+ *
+ * VALIDATED, NOT CAST. `JSON.parse` returns `any`, and a bare
+ * `as NotificationStreamEvent` would let a malformed or truncated frame through
+ * to a component that then renders `undefined` as a title — or worse, calls
+ * `new Notification(undefined)`. The check is cheap and this is untrusted input
+ * in the only sense that matters: it arrived over a socket and this code cannot
+ * see what produced it.
+ *
+ * Returns `null` rather than throwing, because a bad frame must not kill the
+ * read loop. One unparseable event should cost one notification, not the
+ * connection.
+ *
+ * Exported for tests: the framing is verifiable without a network.
+ */
+export declare function parseNotificationEvent(data: string): NotificationStreamEvent | null;
+/**
+ * Widen a streamed event into a full notification row.
+ *
+ * TWO DIFFERENCES, AND BOTH ARE RECONCILED HERE. `readAt: null` is not a guess:
+ * the API omits the field from the stream because a notification is unread BY
+ * DEFINITION at the instant it is published. And `toast` is DROPPED: it is an
+ * instruction about this one live delivery ("may the OS bubble be raised?"),
+ * not a property of the stored row, and the same notification fetched from
+ * `GET /api/notifications` has no such field.
+ *
+ * Keeping it would make a streamed notification and a fetched one two subtly
+ * different objects in the same list — precisely the divergence the API avoided
+ * by giving the stream the row's shape in the first place. `pushed` (#625) is
+ * dropped for the same reason. A caller that needs
+ * the flags reads them off the stream event, before this conversion; `onFrame`
+ * below holds both.
+ */
+export declare function streamEventToNotification(event: NotificationStreamEvent): AppNotification;
+export interface NotificationStreamHandlers {
+    /**
+     * A notification arrived live.
+     *
+     * Called only for well-formed `event: notification` frames. Heartbeat
+     * comments never reach here — they are consumed by the parser, which is what
+     * they are for.
+     *
+     * TWO ARGUMENTS, DELIBERATELY NOT ONE OBJECT (#227). `notification` is the
+     * stored-row shape — `toast`-free, per `streamEventToNotification`'s own
+     * documented boundary above — and `toast` is the raw frame's live-delivery
+     * instruction, passed alongside rather than folded back in. Re-attaching
+     * `toast` to `notification` here would undo the exact separation
+     * `streamEventToNotification` exists to make: the STORED shape must stay
+     * `toast`-free (it is not a property of the row, and a caller that persists
+     * or compares `notification` objects must never see a field that varies by
+     * delivery), while the LIVE delivery decision — may the OS bubble fire for
+     * THIS arrival? — still needs the flag. Two arguments keep both true at once.
+     *
+     * `pushed` (#625) is the third argument for the same reason: whether this
+     * arrival is also going out over Web Push to this user. `false` when the
+     * server did not say.
+     */
+    onNotification: (notification: AppNotification, toast: boolean, pushed: boolean) => void;
+    /**
+     * ⚠️ THE REFETCH SIGNAL. Fires on the first connect and on EVERY reconnect.
+     *
+     * The caller must re-read the list and the unread count here. See this file's
+     * header for why nothing else recovers a gap.
+     */
+    onOpen: () => void;
+    /** Connection state, for rendering. Optional. */
+    onStateChange?: (state: SseState) => void;
+}
+/**
+ * Connect to this user's notification stream.
+ *
+ * NO USER ID ARGUMENT, and there is no way to add one: the recipient is the
+ * bearer of the token, resolved server-side. That is the isolation property the
+ * whole feature rests on — a stream selected by a client-supplied id would be
+ * an IDOR, and the API deliberately exposes no parameter that could carry one.
+ *
+ * Credentials are read through `api` on every attempt rather than captured, so
+ * a connection that outlives its 15-minute access token reconnects with the
+ * current one; a 401 renews through the same `refreshToken` path every other
+ * request uses, so the stream and the REST calls can never disagree about
+ * whether the session is alive.
+ */
+export declare function connectNotificationStream(handlers: NotificationStreamHandlers): SseConnection;
+export type { SseConnection, SseState };
+//# sourceMappingURL=notificationStream.d.ts.map

package/dist/notifications/headless/notificationStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notificationStream.d.ts","sourceRoot":"","sources":["../../../src/notifications/headless/notificationStream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAGH,OAAO,EAAc,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE3E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AAErD,gFAAgF;AAChF,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,uBAAuB,GAAG,IAAI,CAiDnF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,uBAAuB,GAC7B,eAAe,CAIjB;AAED,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,cAAc,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzF;;;;;OAKG;IACH,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,iDAAiD;IACjD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;CAC3C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,0BAA0B,GACnC,aAAa,CAmCf;AAED,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC"}