feat(engagement): the in-app channel, core and web (engagement Phase 7)

ENGAGEMENT.md Phase 7. `user_notifications`, the in-app DeliveryChannel, the
four inbox routes, and the web surface — plus the two pieces earlier phases
assigned here that Phase 7's own acceptance line omits.

Four decisions settled by the org lead before any code:

1. `inapp` defaults to `instant` — the only channel that does. Push wakes a
   device somebody is holding and email leaves the building, so both are asked
   for; an inbox item is a row on a page the user chose to open. Left `off` the
   channel ships dead.
2. The phase takes push's `deliver` (§2603) and the web per-channel preferences
   screen (Phase 3's as-built), neither of which its own bullets mention.
3. The inbox takes `/auth/me/notifications` and `/account/notifications`; the
   preferences screen moves to `…/settings`. The plain word belongs to the
   content, which is what the bell opens.
4. `ctx.inbox.push` honours the user's in-app preference when `triggerId` names
   a registered trigger, and writes when it does not.

Server
- `user_notifications` + `model/userNotifications/`. The dedupe UNIQUE is scoped
  to the USER, narrower than the outbox's `(rule, user, channel)`: an inbox has
  no channel dimension, so two rows for one event would be one item shown twice.
- `engagement/inappChannel.js` — renders by block ROLE (first heading → title,
  first button → url, the rest → body) and inserts. `pushChannel.js` — a
  content-free `{stream, ref}` tickle whose ref deep-links the inbox row.
- `engine.liveChannels` orders `inapp` first (`CHANNEL_ORDER`) so that ref
  resolves on the first sweep. An ordering, not a dependency.
- `templates.renderInappByKey` + `resolveTemplate` extracted from `renderByKey`,
  so both channels take the same fallback chain.
- `inapp.event` seed → seedVersion 2: it named `body`/`url`, which nothing
  supplies. Renamed to the structural vocabulary the projection fills in.
- `utils/userNotificationsPrune.js` — nightly, READ items only, horizon in
  `settings.user_notifications_retain_days` (default 90).
- `GET /auth/me/notifications`, `…/unread-count`, `POST …/:id/read`,
  `POST …/read-all`. Swagger + route manifest + four component schemas.

Web
- `NotificationBell` in all three headers, polling its badge once a minute and
  pausing while the tab is hidden. `PlayerInbox` at `/account/notifications`.
- The preferences screen becomes a channel matrix over
  `/auth/me/notifications/channels` — a strict superset of the push-only stream
  list it replaces. The two legacy endpoints are untouched, so the shipped
  Android app keeps its wire shape.
- Staff get the same two screens at `/admin/notifications…`: `RequirePlayer`
  keeps them out of `/account`, so without this the inbox was unreachable for
  every non-player account. `lib/notificationPaths.js` is the one mapping.

Verified: 28 new server tests (5 of them against a real MariaDB, for the three
index/statement properties that are a server contract rather than a reading of
this code) + 3 client. Server suite green, client 327 green. A live rig walked
the whole path: two rules on one event produced three outbox rows and exactly
one inbox item, the tickle carried `ref: notification:2`, and the retention
sweep dropped an aged read row while keeping an equally aged unread one.

Docs: RunicGateway/docs#TBD, RunicGateway/runicgateway.com#TBD

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

client/src/components/NotificationBell.jsx

@@ -0,0 +1,353 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { Link, useLocation, useNavigate } from 'react-router-dom'
+import { useAuth } from '../contexts/AuthContext.jsx'
+import { api } from '../api/client.js'
+import { inboxPath } from '../lib/notificationPaths.js'
+
+// The in-app inbox's header surface (ENGAGEMENT.md Phase 7): a bell with an
+// unread badge, and a panel with the most recent items.
+//
+// **The badge is polled, not pushed**, and the reason is that there is nothing
+// to push over. The site's two SSE streams are the shard's; neither is
+// per-user, and adding a third authenticated stream to carry an integer would
+// mean one open connection per signed-in tab for the rest of the deployment's
+// life. A minute-granular badge on a page somebody is already looking at is the
+// same answer for a fraction of that. The poll pauses while the tab is hidden —
+// a background tab has nobody to show a badge to — and refreshes the moment it
+// comes back, which is also the moment it would be most wrong.
+//
+// **The panel shows a handful and links out.** Paging belongs on the page; a
+// dropdown that scrolls is a list in the wrong place.
+//
+// Dismissal follows `NavDropdown`'s contract exactly — Escape closes and
+// returns focus, an outside `mousedown` closes, navigating closes — because
+// this sits beside it in the same header and two menus that dismiss differently
+// is a bug nobody files.
+
+const POLL_MS = 60_000
+const PANEL_ITEMS = 6
+
+function BellIcon({ size = 17 }) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+    >
+      <path d="M18 8a6 6 0 10-12 0c0 7-3 9-3 9h18s-3-2-3-9" />
+      <path d="M13.7 21a2 2 0 01-3.4 0" />
+    </svg>
+  )
+}
+
+// "3m", "4h", "6d" — a relative stamp, because the only question a reader has
+// about an inbox item's time is how fresh it is.
+function ago(iso) {
+  const then = new Date(iso).getTime()
+  if (!Number.isFinite(then)) return ''
+  const secs = Math.max(0, Math.round((Date.now() - then) / 1000))
+  if (secs < 60) return 'now'
+  if (secs < 3600) return `${Math.floor(secs / 60)}m`
+  if (secs < 86400) return `${Math.floor(secs / 3600)}h`
+  return `${Math.floor(secs / 86400)}d`
+}
+
+export default function NotificationBell() {
+  const { user } = useAuth()
+  const [unread, setUnread] = useState(0)
+  const [items, setItems] = useState([])
+  const [open, setOpen] = useState(false)
+  const [error, setError] = useState('')
+  const wrapRef = useRef(null)
+  const triggerRef = useRef(null)
+  const location = useLocation()
+  const navigate = useNavigate()
+
+  // Every read here swallows its failure. A count that could not be fetched is
+  // a bell with no badge, which is what a bell with nothing to report looks
+  // like anyway — the alternative is an error banner in the site header for a
+  // number nobody asked for.
+  const refreshCount = useCallback(async () => {
+    if (!user) return
+    try {
+      const res = await api.notificationsUnreadCount()
+      setUnread(res.unread || 0)
+    } catch {
+      /* leave the badge as it was */
+    }
+  }, [user])
+
+  useEffect(() => {
+    if (!user) return undefined
+    refreshCount()
+    const timer = setInterval(() => {
+      if (document.visibilityState === 'visible') refreshCount()
+    }, POLL_MS)
+    const onVisible = () => {
+      if (document.visibilityState === 'visible') refreshCount()
+    }
+    document.addEventListener('visibilitychange', onVisible)
+    return () => {
+      clearInterval(timer)
+      document.removeEventListener('visibilitychange', onVisible)
+    }
+  }, [user, refreshCount])
+
+  // The panel's items are fetched when it opens, never kept warm: a list nobody
+  // has asked to see is a request per minute for content nobody is reading.
+  const load = useCallback(async () => {
+    setError('')
+    try {
+      const res = await api.notifications({ limit: PANEL_ITEMS })
+      setItems(res.items || [])
+      setUnread(res.unread || 0)
+    } catch (err) {
+      setError(err.message || 'Could not load notifications')
+    }
+  }, [])
+
+  useEffect(() => setOpen(false), [location.pathname])
+
+  useEffect(() => {
+    if (!open) return undefined
+    const onKey = (e) => {
+      if (e.key !== 'Escape') return
+      setOpen(false)
+      triggerRef.current?.focus()
+    }
+    const onOutside = (e) => {
+      if (!wrapRef.current?.contains(e.target)) setOpen(false)
+    }
+    document.addEventListener('keydown', onKey)
+    document.addEventListener('mousedown', onOutside)
+    return () => {
+      document.removeEventListener('keydown', onKey)
+      document.removeEventListener('mousedown', onOutside)
+    }
+  }, [open])
+
+  if (!user) return null
+
+  const toggle = () => {
+    const next = !open
+    setOpen(next)
+    if (next) load()
+  }
+
+  // Opening an item marks it read and then goes where it points. The mark is
+  // awaited rather than fired off, so the badge the next screen renders is the
+  // one this click produced; a failed mark still navigates, because the item's
+  // link is the thing the user asked for.
+  const openItem = async (item) => {
+    setOpen(false)
+    if (!item.read) {
+      try {
+        const res = await api.markNotificationRead(item.id)
+        setUnread(res.unread ?? Math.max(0, unread - 1))
+      } catch {
+        /* the link still works */
+      }
+    }
+    navigate(item.url || inboxPath(user))
+  }
+
+  const markAll = async () => {
+    try {
+      await api.markAllNotificationsRead()
+      setUnread(0)
+      setItems((list) => list.map((i) => ({ ...i, read: true })))
+    } catch (err) {
+      setError(err.message || 'Could not mark them read')
+    }
+  }
+
+  return (
+    <div ref={wrapRef} style={{ position: 'relative' }}>
+      <button
+        ref={triggerRef}
+        type="button"
+        className="pill"
+        aria-haspopup="true"
+        aria-expanded={open}
+        // The count is in the label, not only in the badge: a screen reader gets
+        // "Notifications, 3 unread" rather than "Notifications" and a number it
+        // has no way to relate to it.
+        aria-label={unread ? `Notifications, ${unread} unread` : 'Notifications'}
+        onClick={toggle}
+        style={{
+          display: 'inline-flex',
+          alignItems: 'center',
+          gap: 6,
+          position: 'relative',
+          ...(open ? { background: 'var(--accent)', color: 'var(--bg-deep)', borderColor: 'var(--accent)' } : {}),
+        }}
+      >
+        <BellIcon />
+        {unread > 0 && (
+          <span
+            aria-hidden="true"
+            className="sans"
+            style={{
+              minWidth: 17,
+              height: 17,
+              padding: '0 4px',
+              borderRadius: 9,
+              background: 'var(--accent)',
+              color: 'var(--bg-deep)',
+              fontSize: '0.68rem',
+              fontWeight: 700,
+              lineHeight: '17px',
+              textAlign: 'center',
+            }}
+          >
+            {unread > 99 ? '99+' : unread}
+          </span>
+        )}
+      </button>
+
+      {open && (
+        <div
+          role="menu"
+          aria-label="Notifications"
+          style={{
+            position: 'absolute',
+            top: 'calc(100% + 6px)',
+            right: 0,
+            width: 320,
+            maxWidth: 'calc(100vw - 24px)',
+            padding: 6,
+            borderRadius: 'var(--radius-card)',
+            border: '1px solid var(--line)',
+            background: 'var(--panel-flat)',
+            boxShadow: 'var(--shadow-card)',
+            zIndex: 40,
+          }}
+        >
+          <div
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'space-between',
+              gap: 10,
+              padding: '4px 8px 8px',
+            }}
+          >
+            <strong className="sans" style={{ fontSize: '0.82rem', color: 'var(--head)' }}>
+              Notifications
+            </strong>
+            {unread > 0 && (
+              <button
+                type="button"
+                onClick={markAll}
+                className="sans"
+                style={{
+                  background: 'none',
+                  border: 'none',
+                  padding: 0,
+                  cursor: 'pointer',
+                  color: 'var(--accent)',
+                  fontSize: '0.78rem',
+                }}
+              >
+                Mark all read
+              </button>
+            )}
+          </div>
+
+          {error && (
+            <p className="sans" style={{ margin: '0 8px 8px', fontSize: '0.8rem', color: '#d98b84' }}>
+              {error}
+            </p>
+          )}
+
+          {!error && items.length === 0 && (
+            <p className="sans dim" style={{ margin: '0 8px 10px', fontSize: '0.82rem' }}>
+              Nothing here yet.
+            </p>
+          )}
+
+          {items.map((item) => (
+            <button
+              key={item.id}
+              type="button"
+              role="menuitem"
+              onClick={() => openItem(item)}
+              className="sans"
+              style={{
+                display: 'block',
+                width: '100%',
+                textAlign: 'left',
+                padding: '8px 10px',
+                borderRadius: 'var(--radius-input)',
+                border: 'none',
+                cursor: 'pointer',
+                background: item.read ? 'transparent' : 'var(--panel)',
+              }}
+            >
+              <span
+                style={{
+                  display: 'block',
+                  fontSize: '0.85rem',
+                  color: item.read ? 'var(--muted)' : 'var(--head)',
+                  fontWeight: item.read ? 400 : 600,
+                }}
+              >
+                {item.title}
+              </span>
+              {item.body && (
+                <span
+                  className="dim"
+                  style={{
+                    fontSize: '0.78rem',
+                    marginTop: 2,
+                    // The body is stored and rendered as TEXT, never as markup —
+                    // `white-space: pre-line` is what keeps the template's own
+                    // line breaks without ever interpreting anything.
+                    whiteSpace: 'pre-line',
+                    // Two lines, then an ellipsis. `-webkit-box` is the only
+                    // clamp with real support; it is also why there is no second
+                    // `display: block` above it.
+                    display: '-webkit-box',
+                    overflow: 'hidden',
+                    WebkitLineClamp: 2,
+                    WebkitBoxOrient: 'vertical',
+                  }}
+                >
+                  {item.body}
+                </span>
+              )}
+              <span className="dim" style={{ display: 'block', fontSize: '0.72rem', marginTop: 3 }}>
+                {ago(item.createdAt)}
+              </span>
+            </button>
+          ))}
+
+          <Link
+            to={inboxPath(user)}
+            role="menuitem"
+            onClick={() => setOpen(false)}
+            className="sans"
+            style={{
+              display: 'block',
+              marginTop: 4,
+              padding: '8px 10px',
+              borderTop: '1px solid var(--line-soft)',
+              fontSize: '0.8rem',
+              color: 'var(--accent)',
+              textDecoration: 'none',
+            }}
+          >
+            See all notifications →
+          </Link>
+        </div>
+      )}
+    </div>
+  )
+}

client/src/components/SiteHeader.jsx

@@ -5,6 +5,7 @@ import BrandLogo from './BrandLogo.jsx'
 import { useAuth } from '../contexts/AuthContext.jsx'
 import { useSite } from '../contexts/SiteContext.jsx'
 import NavDropdown from './NavDropdown.jsx'
+import NotificationBell from './NotificationBell.jsx'
 import { buildPublicNav, pruneNav } from '../lib/navOverrides.js'
 import { parseJsonSetting } from '../lib/settingsJson.js'
 import { withModuleNav } from '../modules/nav.js'
@@ -107,6 +108,10 @@ export default function SiteHeader() {
               </NavLink>
             ),
           )}
+          {/* Renders nothing when signed out, so the header keeps its shape for
+              a visitor. It is here rather than only in the portal because an
+              inbox item is worth seeing from the page you are already on. */}
+          {!loading && <NotificationBell />}
           {!loading && (
             <NavLink
               to={account.to}