feat(dashboard): offline web push — service worker, subscribe flow, deep-link

Notifications phase 2: a /push-sw.js service worker shows a system notification
on push and, on click, focuses an open CRM tab (or opens one) and deep-links to
the thread. usePushNotifications registers the SW, requests permission, subscribes
with IIOS's VAPID key, and stores the subscription via the be-crm door. The topbar
bell becomes a real enable/disable control (hidden when push is unsupported/demo).
Dashboard listens for the SW's notif-click message + a ?thread= deep link.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

package-lock.json

@@ -12,7 +12,7 @@
         "@huggingface/transformers": "^4.2.0",
         "@imgly/background-removal": "^1.7.0",
         "@insignia/iios-kernel-client": "^0.1.4",
-        "@insignia/iios-messaging-ui": "^0.1.6",
+        "@insignia/iios-messaging-ui": "^0.1.7",
         "@photo-gallery/sdk": "file:./vendor/photo-gallery-sdk",
         "@tensorflow-models/coco-ssd": "^2.2.3",
         "@tensorflow/tfjs": "^4.22.0",
@@ -1087,9 +1087,9 @@
       }
     },
     "node_modules/@insignia/iios-messaging-ui": {
-      "version": "0.1.6",
+      "version": "0.1.7",
-      "resolved": "https://git.lynkedup.cloud/api/packages/insignia/npm/%40insignia%2Fiios-messaging-ui/-/0.1.6/iios-messaging-ui-0.1.6.tgz",
+      "resolved": "https://git.lynkedup.cloud/api/packages/insignia/npm/%40insignia%2Fiios-messaging-ui/-/0.1.7/iios-messaging-ui-0.1.7.tgz",
-      "integrity": "sha512-q/PhJDZJWrXIDAMnVuTWJrWdwO+4jU8BNvIFWz7XRJAWc7F5PrQC1FCfMxOJrKSaLUNpZL64C3/pRWTJa+kFPg==",
+      "integrity": "sha512-ZE4fLeSTSa5AFZnvSRT7G/TEaw+Jm5qH8rWaDjns6Vu9zBnDTVYdF8CMEisBrtgSDj+jDQBo9xlwZmr++5qehw==",
       "peerDependencies": {
         "@insignia/iios-kernel-client": "*",
         "react": ">=18",

package.json

@@ -14,7 +14,7 @@
     "@huggingface/transformers": "^4.2.0",
     "@imgly/background-removal": "^1.7.0",
     "@insignia/iios-kernel-client": "^0.1.4",
-    "@insignia/iios-messaging-ui": "^0.1.6",
+    "@insignia/iios-messaging-ui": "^0.1.7",
     "@photo-gallery/sdk": "file:./vendor/photo-gallery-sdk",
     "@tensorflow-models/coco-ssd": "^2.2.3",
     "@tensorflow/tfjs": "^4.22.0",

public/push-sw.js

@@ -0,0 +1,50 @@
+/* Web Push service worker for CRM offline notifications.
+ *
+ * Receives push payloads from IIOS (WebPushDelivery), shows a system notification, and on click
+ * focuses an open CRM tab (or opens one) and posts the thread to deep-link to. The payload shape is
+ * IIOS's NotificationPayload: { title, body, data: { threadId, interactionId? } }.
+ *
+ * Served from /public at /push-sw.js → root scope ('/'), so it controls the whole app.
+ */
+
+self.addEventListener("push", (event) => {
+  let payload = {};
+  try {
+    payload = event.data ? event.data.json() : {};
+  } catch {
+    payload = { title: "New notification", body: event.data ? event.data.text() : "" };
+  }
+  const title = payload.title || "New message";
+  const threadId = payload.data && payload.data.threadId;
+  event.waitUntil(
+    self.registration.showNotification(title, {
+      body: payload.body || "",
+      // Coalesce repeated pings for the same thread into one notification.
+      tag: threadId ? `thread:${threadId}` : undefined,
+      renotify: Boolean(threadId),
+      data: payload.data || {},
+      icon: "/icons/i_bell.svg",
+    }),
+  );
+});
+
+self.addEventListener("notificationclick", (event) => {
+  event.notification.close();
+  const threadId = event.notification.data && event.notification.data.threadId;
+  event.waitUntil(
+    (async () => {
+      const all = await self.clients.matchAll({ type: "window", includeUncontrolled: true });
+      // Prefer an already-open CRM tab: focus it and tell the app which thread to open.
+      for (const client of all) {
+        if ("focus" in client) {
+          await client.focus();
+          client.postMessage({ type: "notif-click", threadId: threadId || null });
+          return;
+        }
+      }
+      // No tab open — launch one deep-linked via the query string.
+      const url = threadId ? `/dashboard?thread=${encodeURIComponent(threadId)}` : "/dashboard";
+      if (self.clients.openWindow) await self.clients.openWindow(url);
+    })(),
+  );
+});

src/app/dashboard/dashboard.css

@@ -1272,3 +1272,6 @@
   .dash-root .gs-snippet em { color: var(--orange); font-style: normal; font-weight: 600; }
   .dash-root .gs-surface { flex: 0 0 auto; font-size: 10.5px; font-weight: 700; letter-spacing: 0.04em; text-transform: uppercase; color: var(--faint); }
   @media (max-width: 720px) { .dash-root .gs-field { width: 160px; } }
+
+  .dash-root .ds-toast.is-clickable .ds-toast-body { cursor: pointer; }
+  .dash-root .ds-toast.is-clickable .ds-toast-body:hover .ds-toast-title { color: var(--orange); }

src/components/dashboard/dashboard.tsx

@@ -18,6 +18,8 @@ import { TeamManagement } from "./team-management";
 import { MessengerSdk } from "./messenger-sdk";
 import { InboxSdk } from "./inbox-sdk";
 import { Settings } from "./settings";
+import { NotificationCenter } from "./notification-center";
+import { RealtimeProvider } from "@/lib/realtime";
 import { SmartGallery } from "./smart-gallery";
 import "../../app/dashboard/dashboard.css";
 
@@ -37,6 +39,25 @@ export function Dashboard() {
     // eslint-disable-next-line react-hooks/set-state-in-effect
     try { const t = localStorage.getItem("lup_dash_theme"); if (t === "light" || t === "dark") setTheme(t); } catch {}
   }, []);
+
+  // Deep-link from a clicked push notification. Two paths from the service worker:
+  //  - a tab was already open → it postMessages { type: 'notif-click', threadId } to focus here
+  //  - no tab was open → it opens /dashboard?thread=<id>, which we read once on mount
+  useEffect(() => {
+    try {
+      const t = new URLSearchParams(window.location.search).get("thread");
+      if (t) {
+        navigateToConversation("messenger", t);
+        window.history.replaceState({}, "", window.location.pathname);
+      }
+    } catch {}
+    if (!("serviceWorker" in navigator)) return;
+    const onMessage = (e: MessageEvent) => {
+      if (e.data?.type === "notif-click" && e.data.threadId) navigateToConversation("messenger", e.data.threadId);
+    };
+    navigator.serviceWorker.addEventListener("message", onMessage);
+    return () => navigator.serviceWorker.removeEventListener("message", onMessage);
+  }, []);
   function toggle() {
     setTheme((t) => { const n = t === "dark" ? "light" : "dark"; try { localStorage.setItem("lup_dash_theme", n); } catch {} return n; });
   }
@@ -47,11 +68,13 @@ export function Dashboard() {
 
   return (
     <div className="dash-root" data-theme={theme}>
+      <RealtimeProvider>
       <Sidebar active={active} onSelect={setActive} />
       <div className="dash-main">
         <Topbar theme={theme} onToggle={toggle} title={title} subtitle={subtitle} onNavigate={navigateToConversation} />
         <div className="dash-content">
           <ToastProvider>
+            <NotificationCenter active={active} onNavigate={navigateToConversation} />
             {active === "profile" ? <Profile />
               : active === "support" ? <Support />
               : active === "rules" ? <Rules />
@@ -65,6 +88,7 @@ export function Dashboard() {
           </ToastProvider>
         </div>
       </div>
+      </RealtimeProvider>
     </div>
   );
 }

src/components/dashboard/messenger-sdk.tsx

@@ -5,36 +5,15 @@
 // UI + messaging logic lives in the SDK. Live path = the be-crm data door (CrmMessagingAdapter);
 // demo path = the SDK's own MockAdapter.
 
-import { useEffect, useMemo, useState } from "react";
+import { useMemo } from "react";
-import { useAppShell, useAuth, useQuery } from "@abe-kap/appshell-sdk/react";
+import { useAppShell, useAuth } from "@abe-kap/appshell-sdk/react";
-import { MessageSocket } from "@insignia/iios-kernel-client";
 import { MessagingProvider, Messenger as SdkMessenger, type MessagingAdapter } from "@insignia/iios-messaging-ui";
 import { MockAdapter } from "@insignia/iios-messaging-ui/adapters/mock";
 import "@insignia/iios-messaging-ui/styles.css";
 import { isShellConfigured } from "@/lib/appshell";
+import { useRealtime } from "@/lib/realtime";
 import { CrmMessagingAdapter, type DataDoor } from "@/lib/crm-messaging-adapter";
 
-interface RealtimeDTO { url: string; audience: string; token?: string }
-
-/** Open the IIOS message socket with the delegated token the BFF mints (crm.messenger.realtime). */
-function useRealtimeSocket(): MessageSocket | null {
-  const rt = useQuery<RealtimeDTO>("crm.messenger.realtime", {});
-  const [socket, setSocket] = useState<MessageSocket | null>(null);
-  const url = rt.data?.url;
-  const token = rt.data?.token;
-  useEffect(() => {
-    if (!url || !token) return;
-    const s = new MessageSocket({ serviceUrl: url, token, autoConnect: false });
-    s.connect();
-    setSocket(s);
-    return () => {
-      s.disconnect();
-      setSocket(null);
-    };
-  }, [url, token]);
-  return socket;
-}
-
 const SHELL = isShellConfigured();
 
 export function MessengerSdk({ focusThreadId }: { focusThreadId?: string | null } = {}) {
@@ -74,7 +53,7 @@ function DemoHost({ focusThreadId }: { focusThreadId?: string | null }) {
 function LiveHost({ focusThreadId }: { focusThreadId?: string | null }) {
   const { sdk } = useAppShell();
   const { user } = useAuth();
-  const socket = useRealtimeSocket();
+  const socket = useRealtime();
   // Rebuilds once the socket connects: the first adapter (no socket) polls; the second runs live.
   const adapter = useMemo<MessagingAdapter | null>(
     () => (user?.id ? new CrmMessagingAdapter(sdk as unknown as DataDoor, user.id, socket ?? undefined) : null),

src/components/dashboard/notification-bell.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+// Topbar bell → offline-notification control. Click opens a small popover to enable/disable Web Push
+// for this browser. The dot is lit when this browser is subscribed. Hidden entirely when push isn't
+// available (demo mode, or a browser without ServiceWorker/PushManager).
+
+import { useState } from "react";
+import { Icon } from "./ui";
+import { usePushNotifications } from "@/lib/push-notifications";
+
+export function NotificationBell() {
+  const push = usePushNotifications();
+  const [open, setOpen] = useState(false);
+
+  if (!push.supported) return null;
+
+  const denied = push.permission === "denied";
+
+  return (
+    <div style={{ position: "relative" }}>
+      <button
+        className="ic-btn"
+        aria-label="Notifications"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        style={{ position: "relative" }}
+        onClick={() => setOpen((o) => !o)}
+      >
+        <Icon name="bell" size={18} />
+        <span
+          style={{
+            position: "absolute",
+            top: 9,
+            right: 10,
+            width: 7,
+            height: 7,
+            borderRadius: 99,
+            background: push.subscribed ? "var(--orange)" : "var(--border)",
+            border: "2px solid var(--panel)",
+          }}
+        />
+      </button>
+      {open && (
+        <>
+          <div className="tm-menu-scrim" onClick={() => setOpen(false)} />
+          <div className="tm-menu-pop" role="menu" style={{ width: 260, padding: 14 }}>
+            <div style={{ fontWeight: 700, fontSize: 13, marginBottom: 4 }}>Offline notifications</div>
+            <p style={{ fontSize: 12, color: "var(--muted)", margin: "0 0 12px", lineHeight: 1.4 }}>
+              {push.subscribed
+                ? "You'll get push notifications for new direct messages and mentions, even when this tab is closed."
+                : "Get notified about direct messages and mentions when the CRM isn't open."}
+            </p>
+
+            {denied ? (
+              <p style={{ fontSize: 12, color: "var(--danger, #c0392b)", margin: 0 }}>
+                Notifications are blocked in your browser settings. Allow them for this site, then try again.
+              </p>
+            ) : push.subscribed ? (
+              <button className="ds-btn v-ghost full" disabled={push.busy} onClick={() => push.disable()}>
+                {push.busy ? "Turning off…" : "Turn off notifications"}
+              </button>
+            ) : (
+              <button className="ds-btn v-primary full" disabled={push.busy} onClick={() => push.enable()}>
+                {push.busy ? "Enabling…" : "Enable notifications"}
+              </button>
+            )}
+
+            {push.error && <p style={{ fontSize: 11.5, color: "var(--danger, #c0392b)", margin: "10px 0 0" }}>{push.error}</p>}
+          </div>
+        </>
+      )}
+    </div>
+  );
+}

src/components/dashboard/notification-center.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+// App-wide in-app notifications. Uses the shared dashboard socket to watch activity across ALL of
+// the user's threads (via the adapter's subscribeActivity) and shows a clickable toast when a new
+// message arrives — unless you're already on the Messenger tab (you'd see it live there). Clicking
+// deep-links to the conversation. Renders nothing.
+
+import { useEffect, useMemo, useRef } from "react";
+import { useAppShell, useAuth } from "@abe-kap/appshell-sdk/react";
+import type { MessagingAdapter } from "@insignia/iios-messaging-ui";
+import { isShellConfigured } from "@/lib/appshell";
+import { useRealtime } from "@/lib/realtime";
+import { CrmMessagingAdapter, type DataDoor } from "@/lib/crm-messaging-adapter";
+import { useToast } from "./ui";
+
+const SHELL = isShellConfigured();
+
+export function NotificationCenter({ active, onNavigate }: { active: string; onNavigate: (surface: "messenger" | "inbox", threadId: string) => void }) {
+  const socket = useRealtime();
+  const { sdk } = useAppShell();
+  const { user } = useAuth();
+  const toast = useToast();
+  const me = user?.id;
+
+  // Keep the current tab readable inside the (stable) subscription callback.
+  const activeRef = useRef(active);
+  activeRef.current = active;
+
+  const adapter = useMemo<MessagingAdapter | null>(
+    () => (me && socket ? new CrmMessagingAdapter(sdk as unknown as DataDoor, me, socket) : null),
+    [sdk, me, socket],
+  );
+
+  useEffect(() => {
+    if (!SHELL || !adapter?.subscribeActivity) return;
+    return adapter.subscribeActivity(({ threadId, message }) => {
+      if (message.actorId === me) return; // never notify me about my own message
+      if (activeRef.current === "messenger") return; // already watching chat live
+      toast.push({
+        tone: "info",
+        title: "New message",
+        desc: message.text?.slice(0, 90) || "You have a new message",
+        onClick: () => onNavigate("messenger", threadId),
+      });
+    });
+  }, [adapter, me, toast, onNavigate]);
+
+  return null;
+}

src/components/dashboard/topbar.tsx

@@ -4,8 +4,8 @@ import { useState } from "react";
 import { useRouter } from "next/navigation";
 import { Sun, Moon, ChevronDown, LogOut } from "lucide-react";
 import { useAuth } from "@abe-kap/appshell-sdk/react";
-import { Icon } from "./ui";
 import { GlobalSearch } from "./global-search";
+import { NotificationBell } from "./notification-bell";
 import { user } from "./account-data";
 
 function initialsOf(name: string): string {
@@ -40,10 +40,7 @@ export function Topbar({ theme, onToggle, title, subtitle, onNavigate }: { theme
         <button className="ic-btn" aria-label="Toggle theme" onClick={onToggle}>
           {theme === "dark" ? <Moon size={18} /> : <Sun size={18} />}
         </button>
-        <button className="ic-btn" aria-label="Notifications" style={{ position: "relative" }}>
+        <NotificationBell />
-          <Icon name="bell" size={18} />
-          <span style={{ position: "absolute", top: 9, right: 10, width: 7, height: 7, borderRadius: 99, background: "var(--orange)", border: "2px solid var(--panel)" }} />
-        </button>
         <div className="top-user-wrap" style={{ position: "relative" }}>
           <button className="top-user" onClick={() => setMenuOpen((o) => !o)} aria-haspopup="menu" aria-expanded={menuOpen}>
             <span className="av" style={{ background: user.avatarGradient, display: "grid", placeItems: "center", color: "#fff", fontWeight: 700, fontSize: 12 }}>{initials}</span>

src/components/dashboard/ui.tsx

@@ -265,7 +265,7 @@ export function Modal({ open, onClose, title, subtitle, icon, children, footer,
 /* Toast                                                       */
 /* ---------------------------------------------------------- */
 
-type Toast = { id: number; tone: "success" | "info" | "error"; title: string; desc?: string };
+type Toast = { id: number; tone: "success" | "info" | "error"; title: string; desc?: string; onClick?: () => void };
 type ToastCtx = { push: (t: Omit<Toast, "id">) => void };
 const ToastContext = createContext<ToastCtx | null>(null);
 
@@ -288,9 +288,12 @@ export function ToastProvider({ children }: { children: ReactNode }) {
       {children}
       <div className="ds-toasts">
         {items.map((t) => (
-          <div key={t.id} className={`ds-toast tone-${t.tone}`}>
+          <div key={t.id} className={`ds-toast tone-${t.tone}${t.onClick ? " is-clickable" : ""}`}>
             <Icon name={t.tone === "success" ? "check-circle" : t.tone === "error" ? "alert" : "info"} size={18} />
-            <div className="ds-toast-body">
+            <div
+              className="ds-toast-body"
+              {...(t.onClick ? { role: "button", tabIndex: 0, onClick: () => { t.onClick?.(); setItems((s) => s.filter((x) => x.id !== t.id)); } } : {})}
+            >
               <div className="ds-toast-title">{t.title}</div>
               {t.desc && <div className="ds-toast-desc">{t.desc}</div>}
             </div>

src/lib/crm-messaging-adapter.ts

@@ -45,6 +45,8 @@ export class CrmMessagingAdapter implements MessagingAdapter {
   private readonly listeners = new Map<string, Set<(e: MessageEvent) => void>>();
   private readonly polls = new Map<string, Poll>();
   private readonly joined = new Set<string>();
+  /** Cross-thread activity listeners (live unread + in-app notifications). */
+  private readonly activity = new Set<(e: { threadId: string; message: Message }) => void>();
   /** messageId → emoji → userSet, so a single annotation delta can be re-emitted as a full set. */
   private readonly reactions = new Map<string, Map<string, Set<string>>>();
 
@@ -59,7 +61,10 @@ export class CrmMessagingAdapter implements MessagingAdapter {
     if (socket) {
       socket.on("message", (m) => {
         this.ingestReactions(m);
-        void this.toKernelMessage(m).then((message) => this.emit(m.threadId, { kind: "message", message }));
+        void this.toKernelMessage(m).then((message) => {
+          this.emit(m.threadId, { kind: "message", message });
+          for (const cb of this.activity) cb({ threadId: m.threadId, message });
+        });
       });
       socket.on("typing", (e) => this.emit(e.threadId, { kind: "typing", userId: e.userId }));
       // Receipts carry no threadId → fan to all open threads; the UI filters by messageId.
@@ -79,6 +84,37 @@ export class CrmMessagingAdapter implements MessagingAdapter {
     return this.me;
   }
 
+  /** Report the foregrounded thread to IIOS presence (suppresses push for what you're viewing). */
+  setFocus(threadId: string | null): void {
+    this.socket?.focus(threadId);
+  }
+
+  /** Fire `cb` for every incoming message across ALL the caller's threads (live unread + toasts). */
+  subscribeActivity(cb: (e: { threadId: string; message: Message }) => void): Unsubscribe {
+    this.activity.add(cb);
+    void this.joinAllThreads();
+    return () => {
+      this.activity.delete(cb);
+    };
+  }
+
+  /** Join every thread the user belongs to so their messages arrive over the socket, not just the
+   *  open one. Idempotent (the `joined` set guards re-joins). */
+  private async joinAllThreads(): Promise<void> {
+    if (!this.socket) return;
+    try {
+      const convs = await this.sdk.query<ConversationDTO[]>("crm.messenger.conversation.list", {});
+      for (const c of convs) {
+        if (!this.joined.has(c.threadId)) {
+          this.joined.add(c.threadId);
+          void this.socket.openThread(c.threadId).catch(() => this.joined.delete(c.threadId));
+        }
+      }
+    } catch {
+      /* best-effort — activity just won't cover un-joined threads */
+    }
+  }
+
   async listConversations(): Promise<Conversation[]> {
     const [convs, names] = await Promise.all([
       this.sdk.query<ConversationDTO[]>("crm.messenger.conversation.list", {}),

src/lib/push-notifications.ts

@@ -0,0 +1,138 @@
+"use client";
+
+// Offline notifications data layer (Web Push). Registers the service worker, subscribes the browser
+// with IIOS's VAPID key, and hands the subscription to the be-crm door so IIOS can reach this user
+// while no CRM tab is open. Push needs a real backend (VAPID key + delivery), so it is only offered
+// when the Shell is configured (live); demo mode reports it unsupported.
+//
+// Live contract (be-crm data door → IIOS /v1/notifications/*):
+//   query  crm.messenger.push.vapidKey    {}                          -> { key }   ('' = push disabled server-side)
+//   cmd    crm.messenger.push.subscribe   { endpoint, keys, userAgent } -> { ok }
+//   cmd    crm.messenger.push.unsubscribe { endpoint }                 -> { ok }
+
+import { useCallback, useEffect, useState } from "react";
+import { useAppShell } from "@abe-kap/appshell-sdk/react";
+import { isShellConfigured } from "./appshell";
+
+const SHELL = isShellConfigured();
+const SW_URL = "/push-sw.js";
+
+export type PushPermission = "default" | "granted" | "denied";
+
+export interface PushState {
+  /** Browser can do Web Push AND we have a live backend to deliver it. */
+  supported: boolean;
+  /** OS/browser permission for notifications. */
+  permission: PushPermission;
+  /** This browser currently has an active push subscription registered with the backend. */
+  subscribed: boolean;
+  /** A subscribe/unsubscribe round-trip is in flight. */
+  busy: boolean;
+  error: string | null;
+  enable: () => Promise<void>;
+  disable: () => Promise<void>;
+}
+
+/** VAPID keys travel as URL-safe base64; PushManager wants raw bytes. */
+function urlBase64ToUint8Array(base64: string): Uint8Array {
+  const padding = "=".repeat((4 - (base64.length % 4)) % 4);
+  const normalized = (base64 + padding).replace(/-/g, "+").replace(/_/g, "/");
+  const raw = atob(normalized);
+  const out = new Uint8Array(raw.length);
+  for (let i = 0; i < raw.length; i++) out[i] = raw.charCodeAt(i);
+  return out;
+}
+
+function browserSupportsPush(): boolean {
+  return typeof window !== "undefined" && "serviceWorker" in navigator && "PushManager" in window && "Notification" in window;
+}
+
+/** Serialize a PushSubscription into the door's { endpoint, keys } shape. */
+function toSubscribeBody(sub: PushSubscription): { endpoint: string; keys: { p256dh: string; auth: string }; userAgent: string } {
+  const json = sub.toJSON();
+  return {
+    endpoint: sub.endpoint,
+    keys: { p256dh: json.keys?.p256dh ?? "", auth: json.keys?.auth ?? "" },
+    userAgent: typeof navigator !== "undefined" ? navigator.userAgent.slice(0, 400) : "",
+  };
+}
+
+export function usePushNotifications(): PushState {
+  const { sdk } = useAppShell();
+  const [supported] = useState<boolean>(() => SHELL && browserSupportsPush());
+  const [permission, setPermission] = useState<PushPermission>("default");
+  const [subscribed, setSubscribed] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Reflect the current OS permission + whether a subscription already exists (e.g. across reloads).
+  useEffect(() => {
+    if (!supported) return;
+    setPermission(Notification.permission as PushPermission);
+    let cancelled = false;
+    navigator.serviceWorker.ready
+      .then((reg) => reg.pushManager.getSubscription())
+      .then((sub) => {
+        if (!cancelled) setSubscribed(Boolean(sub));
+      })
+      .catch(() => {});
+    return () => {
+      cancelled = true;
+    };
+  }, [supported]);
+
+  const enable = useCallback(async () => {
+    if (!supported) return;
+    setBusy(true);
+    setError(null);
+    try {
+      const perm = await Notification.requestPermission();
+      setPermission(perm as PushPermission);
+      if (perm !== "granted") throw new Error("Notifications permission was not granted.");
+
+      const reg = await navigator.serviceWorker.register(SW_URL);
+      await navigator.serviceWorker.ready;
+
+      const { key } = await sdk.query<{ key: string }>("crm.messenger.push.vapidKey", {});
+      if (!key) throw new Error("Push is not enabled on the server (no VAPID key).");
+
+      const existing = await reg.pushManager.getSubscription();
+      const sub =
+        existing ??
+        (await reg.pushManager.subscribe({
+          userVisibleOnly: true,
+          // Cast: this lib's BufferSource type pins ArrayBuffer, but a plain Uint8Array is valid here.
+          applicationServerKey: urlBase64ToUint8Array(key) as BufferSource,
+        }));
+
+      await sdk.command("crm.messenger.push.subscribe", toSubscribeBody(sub));
+      setSubscribed(true);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Could not enable notifications.");
+    } finally {
+      setBusy(false);
+    }
+  }, [supported, sdk]);
+
+  const disable = useCallback(async () => {
+    if (!supported) return;
+    setBusy(true);
+    setError(null);
+    try {
+      const reg = await navigator.serviceWorker.ready;
+      const sub = await reg.pushManager.getSubscription();
+      if (sub) {
+        // Tell the backend first (still has the endpoint), then drop the local subscription.
+        await sdk.command("crm.messenger.push.unsubscribe", { endpoint: sub.endpoint }).catch(() => {});
+        await sub.unsubscribe();
+      }
+      setSubscribed(false);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Could not disable notifications.");
+    } finally {
+      setBusy(false);
+    }
+  }, [supported, sdk]);
+
+  return { supported, permission, subscribed, busy, error, enable, disable };
+}

src/lib/realtime.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+// One shared IIOS message socket for the whole dashboard, so the messenger tab AND the app-wide
+// notification center use a single connection (not one each). Opened at the dashboard level and
+// kept alive across tab switches; the messenger tab reuses it via useRealtime().
+
+import { createContext, useContext, useEffect, useState, type ReactNode } from "react";
+import { useQuery } from "@abe-kap/appshell-sdk/react";
+import { MessageSocket } from "@insignia/iios-kernel-client";
+import { isShellConfigured } from "./appshell";
+
+const RealtimeContext = createContext<MessageSocket | null>(null);
+interface RealtimeDTO { url: string; audience: string; token?: string }
+const SHELL = isShellConfigured();
+
+function LiveRealtimeProvider({ children }: { children: ReactNode }) {
+  const rt = useQuery<RealtimeDTO>("crm.messenger.realtime", {});
+  const [socket, setSocket] = useState<MessageSocket | null>(null);
+  const url = rt.data?.url;
+  const token = rt.data?.token;
+  useEffect(() => {
+    if (!url || !token) return;
+    const s = new MessageSocket({ serviceUrl: url, token, autoConnect: false });
+    s.connect();
+    setSocket(s);
+    return () => {
+      s.disconnect();
+      setSocket(null);
+    };
+  }, [url, token]);
+  return <RealtimeContext.Provider value={socket}>{children}</RealtimeContext.Provider>;
+}
+
+export function RealtimeProvider({ children }: { children: ReactNode }) {
+  // SHELL is a build-time constant, so the same branch runs every render (Rules-of-Hooks safe).
+  if (!SHELL) return <>{children}</>;
+  return <LiveRealtimeProvider>{children}</LiveRealtimeProvider>;
+}
+
+/** The shared socket, or null (demo mode / not yet connected). */
+export function useRealtime(): MessageSocket | null {
+  return useContext(RealtimeContext);
+}