feat: homeserver status banner from Uptime Kuma (#124)

When the homeserver, voice calls or sign-in break, or maintenance is under way, say so in the app — driven by the Kuma status page (isitup.lotusguild.org/status/matrix), managed from Kuma's UI. The client asks Kuma directly (not via our servers) so it still hears "the server is down" when our servers can't tell it. - config.json `statusPages`, keyed by homeserver: users of other servers never contact Kuma. - utils/kumaStatus.ts (pure, unit-tested): parse Kuma 2.x's public JSON; a group is down when any monitor fails two checks in a row (down+down or pending+down); maintenance = windows under way; announcements = incidents. One strip at a time: server down (connection lost AND Kuma confirms) > server having problems > maintenance > calls down > announcement; sign-in problems on the login screen only. - Wording about the user's own connection: "Connection lost … our status checks say the server is up, so it may be your internet connection" ONLY when Kuma checked the server after this client's connection dropped and it passed; a stale "up" (Kuma needs a minute or two to notice an outage) keeps the plain "Connection Lost!". - useServerStatus: polls only while visible; 5 min, 60 s while something is wrong or the connection is lost, at once when it drops; backoff; any failure = no banner (Kuma being unreachable never looks like Matrix being down); GET only, no cookies. - UI in the existing banner slot and style (ContainerColor/Line like the sync and clock banners); Details expands; dismiss for calls-down and announcements (an edited announcement comes back); calls-down note above Join; phone: one line + Details. Needs the CSP connect-src to allow https://isitup.lotusguild.org (matrix repo) before it can fetch in production; until then it fails quiet. Tests: 15 unit tests (live page layout, two-check rule, any-monitor rule, unknown/garbage, UTC beat times, stale-vs-fresh "up", priorities, login vs client, maintenance, announcements + dismiss/edit); e2e (fixtures for Kuma): calls-down strip + dismiss across reload, other homeservers make no requests, Kuma 500 → nothing, lost connection + Kuma down → critical strip instead of "Connection Lost", + fresh "up" → "may be your connection", + stale "up" → plain "Connection Lost". Unit 1315, Playwright 26 passed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PPmy3tPq869XDW4njjVaKA
2026-09-29 12:08:08 -04:00
parent d6548c56fd
commit 6ae0087213
12 changed files with 1180 additions and 86 deletions
@@ -0,0 +1,262 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  DEFAULT_GROUPS,
+  kumaBeatTime,
+  kumaUrls,
+  parseKumaStatus,
+  pickBanner,
+  resolveStatusPage,
+  serverConfirmedUpSince,
+  ServerStatus,
+} from './kumaStatus';
+
+// The live `matrix` status page's groups (captured 2026-09-29).
+const PAGE = {
+  publicGroupList: [
+    { name: 'Homeserver', monitorList: [{ id: 30, name: 'Synapse HTTP' }] },
+    {
+      name: 'Voice calls',
+      monitorList: [
+        { id: 37, name: 'Matrix: LiveKit (public /rtc)' },
+        { id: 38, name: 'Matrix: call tokens (public /sfu/get)' },
+        { id: 39, name: 'Matrix: call page (call.chat)' },
+      ],
+    },
+    { name: 'Login', monitorList: [{ id: 15, name: 'Authentication Server' }] },
+  ],
+  maintenanceList: [],
+  incidents: [],
+};
+const UP = 1;
+const DOWN = 0;
+const PENDING = 2;
+/** Kuma's beat format: "YYYY-MM-DD HH:MM:SS.mmm" in UTC, oldest first. */
+const beats = (...statuses: number[]) =>
+  statuses.map((status, i) => ({
+    status,
+    time: `2026-09-29 14:${String(10 + i).padStart(2, '0')}:00.000`,
+    msg: '',
+  }));
+const hb = (over: Record<number, number[]> = {}) => ({
+  heartbeatList: {
+    30: beats(...(over[30] ?? [UP, UP, UP])),
+    37: beats(...(over[37] ?? [UP, UP])),
+    38: beats(...(over[38] ?? [UP, UP])),
+    39: beats(...(over[39] ?? [UP, UP])),
+    15: beats(...(over[15] ?? [UP, UP])),
+  },
+  uptimeList: {},
+});
+const parse = (page: unknown, heartbeat: unknown) =>
+  parseKumaStatus(page, heartbeat, DEFAULT_GROUPS);
+
+test('config: only a valid page for the listed homeserver', () => {
+  const cfg = {
+    'matrix.lotusguild.org': { url: 'https://isitup.lotusguild.org/', slug: 'matrix' },
+  };
+  const page = resolveStatusPage(cfg, 'matrix.lotusguild.org');
+  assert.deepEqual(page, {
+    url: 'https://isitup.lotusguild.org',
+    slug: 'matrix',
+    groups: DEFAULT_GROUPS,
+  });
+  assert.deepEqual(kumaUrls(page!), {
+    page: 'https://isitup.lotusguild.org/api/status-page/matrix',
+    heartbeat: 'https://isitup.lotusguild.org/api/status-page/heartbeat/matrix',
+  });
+  assert.equal(resolveStatusPage(cfg, 'matrix.org'), undefined, 'other homeservers: nothing');
+  assert.equal(resolveStatusPage(cfg, undefined), undefined);
+  assert.equal(resolveStatusPage(undefined, 'matrix.lotusguild.org'), undefined);
+  for (const bad of [
+    { url: 'http://isitup.lotusguild.org', slug: 'matrix' },
+    { url: ['javascript', 'alert(1)'].join(':'), slug: 'matrix' },
+    { url: 'https://isitup.lotusguild.org', slug: '../admin' },
+    { url: 'https://isitup.lotusguild.org', slug: '' },
+    { url: 'not a url', slug: 'matrix' },
+  ]) {
+    assert.equal(resolveStatusPage({ hs: bad }, 'hs'), undefined, JSON.stringify(bad));
+  }
+  assert.equal(
+    resolveStatusPage({ hs: { url: 'http://localhost:3001', slug: 'm' } }, 'hs')?.url,
+    'http://localhost:3001',
+    'http allowed for local development',
+  );
+});
+
+test('all green on the live page layout', () => {
+  const s = parse(PAGE, hb());
+  assert.equal(s.homeserver, 'up');
+  assert.equal(s.calls, 'up');
+  assert.equal(s.login, 'up');
+  assert.equal(pickBanner(s, { syncLost: false, where: 'client' }), undefined);
+  assert.equal(pickBanner(s, { syncLost: true, where: 'client' }), undefined);
+});
+
+test('down needs two failing checks: down+down or pending+down; one blip is not down', () => {
+  assert.equal(parse(PAGE, hb({ 30: [UP, UP, DOWN] })).homeserver, 'up', 'single failure');
+  assert.equal(parse(PAGE, hb({ 30: [UP, PENDING] })).homeserver, 'up', 'pending only');
+  assert.equal(parse(PAGE, hb({ 30: [UP, DOWN, DOWN] })).homeserver, 'down');
+  assert.equal(parse(PAGE, hb({ 30: [UP, PENDING, DOWN] })).homeserver, 'down');
+  assert.equal(parse(PAGE, hb({ 30: [DOWN, DOWN, UP] })).homeserver, 'up', 'recovered');
+});
+
+test('any failing monitor takes its group down (one piece breaks calls)', () => {
+  const s = parse(PAGE, hb({ 38: [DOWN, DOWN] }));
+  assert.equal(s.calls, 'down');
+  assert.equal(s.homeserver, 'up');
+});
+
+test('unknown when the group or its beats are missing, and unknown shows nothing', () => {
+  const s = parse({ publicGroupList: [] }, hb());
+  assert.deepEqual([s.homeserver, s.calls, s.login], ['unknown', 'unknown', 'unknown']);
+  assert.equal(parse(PAGE, { heartbeatList: {} }).homeserver, 'unknown');
+  assert.equal(pickBanner(s, { syncLost: true, where: 'client' }), undefined);
+});
+
+test('garbage from Kuma never throws and never shows a banner', () => {
+  for (const [page, heartbeat] of [
+    [null, null],
+    ['<html>', 42],
+    [{ publicGroupList: 'x', maintenanceList: {}, incidents: 7 }, { heartbeatList: [] }],
+    [{ publicGroupList: [{ name: 'Homeserver', monitorList: [{ id: {} }] }] }, hb()],
+  ]) {
+    const s = parse(page, heartbeat);
+    assert.equal(pickBanner(s, { syncLost: true, where: 'client' }), undefined);
+  }
+  assert.equal(pickBanner(null, { syncLost: true, where: 'client' }), undefined);
+});
+
+test('beat times are read as UTC; checkedAt is the oldest latest beat', () => {
+  assert.equal(kumaBeatTime('2026-09-29 14:16:11.804'), Date.UTC(2026, 8, 29, 14, 16, 11, 804));
+  assert.equal(kumaBeatTime('nope'), undefined);
+  const s = parse(PAGE, hb());
+  assert.equal(s.homeserverCheckedAt, Date.UTC(2026, 8, 29, 14, 12));
+});
+
+test('"your connection" only when Kuma checked AFTER the drop and the server was up', () => {
+  const s = parse(PAGE, hb());
+  const checked = s.homeserverCheckedAt!;
+  assert.equal(serverConfirmedUpSince(s, checked - 60_000), true, 'checked after the drop');
+  assert.equal(serverConfirmedUpSince(s, checked + 1), false, 'stale: checked before the drop');
+  assert.equal(serverConfirmedUpSince(s, null), false, 'not disconnected');
+  const down = parse(PAGE, hb({ 30: [UP, DOWN, DOWN] }));
+  assert.equal(serverConfirmedUpSince(down, checked - 60_000), false);
+  assert.equal(serverConfirmedUpSince(null, 1), false);
+});
+
+test('server down vs having problems depends on this client’s own connection', () => {
+  const s = parse(PAGE, hb({ 30: [DOWN, DOWN] }));
+  assert.equal(pickBanner(s, { syncLost: true, where: 'client' })?.kind, 'server-down');
+  assert.equal(pickBanner(s, { syncLost: true, where: 'client' })?.tone, 'Critical');
+  assert.equal(pickBanner(s, { syncLost: false, where: 'client' })?.kind, 'server-problems');
+  assert.equal(pickBanner(s, { syncLost: false, where: 'login' })?.kind, 'server-down');
+  assert.equal(pickBanner(s, { syncLost: true, where: 'client' })?.dismissable, false);
+});
+
+test('priority: server > maintenance > calls > announcement; one strip only', () => {
+  const s: ServerStatus = {
+    ...parse(PAGE, hb({ 30: [DOWN, DOWN], 37: [DOWN, DOWN] })),
+    maintenance: [{ id: '1', title: 'Upgrade', description: '' }],
+    incidents: [{ id: '2', title: 'Heads up', content: '', style: 'info', updated: 'x' }],
+  };
+  assert.equal(pickBanner(s, { syncLost: true, where: 'client' })?.kind, 'server-down');
+  assert.equal(
+    pickBanner({ ...s, homeserver: 'up' }, { syncLost: false, where: 'client' })?.kind,
+    'maintenance',
+  );
+  assert.equal(
+    pickBanner({ ...s, homeserver: 'up', maintenance: [] }, { syncLost: false, where: 'client' })
+      ?.kind,
+    'calls-down',
+  );
+  assert.equal(
+    pickBanner(
+      { ...s, homeserver: 'up', maintenance: [], calls: 'up' },
+      { syncLost: false, where: 'client' },
+    )?.kind,
+    'announcement',
+  );
+});
+
+test('calls-down is not shown on the login screen or when the whole server is down', () => {
+  const calls = parse(PAGE, hb({ 37: [DOWN, DOWN] }));
+  assert.equal(pickBanner(calls, { syncLost: false, where: 'login' }), undefined);
+  const both = parse(PAGE, hb({ 30: [DOWN, DOWN], 37: [DOWN, DOWN] }));
+  assert.equal(pickBanner(both, { syncLost: false, where: 'client' })?.kind, 'server-problems');
+});
+
+test('login-down only on the login screen', () => {
+  const s = parse(PAGE, hb({ 15: [DOWN, DOWN] }));
+  assert.equal(pickBanner(s, { syncLost: false, where: 'login' })?.kind, 'login-down');
+  assert.equal(pickBanner(s, { syncLost: false, where: 'client' }), undefined);
+});
+
+test('maintenance: title, end time and plain-text description', () => {
+  const end = '2026-09-29T22:15:00.000Z';
+  const s = parse(
+    {
+      ...PAGE,
+      maintenanceList: [
+        {
+          id: 7,
+          title: 'Homeserver upgrade',
+          description: '**Synapse 1.160**, see [notes](https://x)',
+          status: 'under-maintenance',
+          timeslotList: [{ startDate: '2026-09-29T22:00:00.000Z', endDate: end }],
+        },
+        { id: 8, title: 'Later', status: 'scheduled' },
+      ],
+    },
+    hb(),
+  );
+  assert.equal(s.maintenance.length, 1, 'only windows under maintenance');
+  assert.equal(s.maintenance[0].end, Date.parse(end));
+  const b = pickBanner(s, { syncLost: false, where: 'client' })!;
+  assert.equal(b.kind, 'maintenance');
+  assert.match(b.text, /^Maintenance in progress until .+: Homeserver upgrade\. /);
+  assert.equal(b.detail, 'Synapse 1.160, see notes');
+  assert.equal(b.dismissable, false);
+});
+
+test('announcements: tone from style, dismissable, a new edit comes back', () => {
+  const incident = {
+    id: 3,
+    style: 'danger',
+    title: 'Planned maintenance tonight',
+    content: 'Calls will drop briefly.',
+    active: true,
+    createdDate: '2026-09-29 15:00:00',
+    lastUpdatedDate: null,
+  };
+  const s = parse({ ...PAGE, incidents: [incident] }, hb());
+  const b = pickBanner(s, { syncLost: false, where: 'client' })!;
+  assert.equal(b.kind, 'announcement');
+  assert.equal(b.tone, 'Critical');
+  assert.equal(b.dismissable, true);
+  const dismissed = new Set([b.key]);
+  assert.equal(pickBanner(s, { syncLost: false, where: 'client', dismissed }), undefined);
+  const edited = parse(
+    { ...PAGE, incidents: [{ ...incident, lastUpdatedDate: '2026-09-29 16:00:00' }] },
+    hb(),
+  );
+  assert.equal(
+    pickBanner(edited, { syncLost: false, where: 'client', dismissed })?.kind,
+    'announcement',
+  );
+  const inactive = parse({ ...PAGE, incidents: [{ ...incident, active: false }] }, hb());
+  assert.equal(pickBanner(inactive, { syncLost: false, where: 'client' }), undefined);
+  const info = parse({ ...PAGE, incidents: [{ ...incident, style: 'info' }] }, hb());
+  assert.equal(pickBanner(info, { syncLost: false, where: 'client' })?.tone, 'Primary');
+});
+
+test('a dismissed calls-down banner lets the next one through, never hides server-down', () => {
+  const s = parse(PAGE, hb({ 37: [DOWN, DOWN] }));
+  const dismissed = new Set(['calls-down', 'server-down', 'server-problems']);
+  assert.equal(pickBanner(s, { syncLost: false, where: 'client', dismissed }), undefined);
+  const down = parse(PAGE, hb({ 30: [DOWN, DOWN] }));
+  assert.equal(
+    pickBanner(down, { syncLost: true, where: 'client', dismissed })?.kind,
+    'server-down',
+  );
+});
@@ -0,0 +1,332 @@
+/**
+ * [Gitea #124] Homeserver status from an Uptime Kuma status page.
+ *
+ * config.json maps a homeserver to a Kuma status page:
+ *   "statusPages": { "matrix.lotusguild.org": { "url": "https://isitup.lotusguild.org",
+ *     "slug": "matrix", "groups": { "homeserver": "Homeserver", "calls": "Voice calls",
+ *     "login": "Login" } } }
+ * Users of any other homeserver never contact Kuma.
+ *
+ * Kuma 2.x public JSON:
+ * - GET /api/status-page/<slug>: publicGroupList[{name, monitorList[{id}]}],
+ *   maintenanceList (only windows UNDER maintenance right now), incidents
+ *   (announcements posted on the page).
+ * - GET /api/status-page/heartbeat/<slug>: heartbeatList{<monitorId>: [{status, time}]},
+ *   status 0 down, 1 up, 2 pending, 3 maintenance.
+ *
+ * Everything here is pure and defensive: anything unexpected reads as
+ * "unknown", and unknown never shows a banner.
+ */
+
+export type StatusGroups = { homeserver?: string; calls?: string; login?: string };
+export type StatusPageConfig = { url: string; slug: string; groups: StatusGroups };
+
+export type ServiceState = 'up' | 'down' | 'unknown';
+export type KumaMaintenance = { id: string; title: string; description: string; end?: number };
+export type KumaIncident = {
+  id: string;
+  title: string;
+  content: string;
+  style: string;
+  updated: string;
+};
+export type ServerStatus = {
+  homeserver: ServiceState;
+  /**
+   * When Kuma last checked every homeserver monitor (the OLDEST of their
+   * latest beats, ms). Lets the client tell "Kuma has looked since my
+   * connection dropped and the server was fine" from a stale "up".
+   */
+  homeserverCheckedAt?: number;
+  calls: ServiceState;
+  login: ServiceState;
+  maintenance: KumaMaintenance[];
+  incidents: KumaIncident[];
+};
+
+export const DEFAULT_GROUPS: Required<StatusGroups> = {
+  homeserver: 'Homeserver',
+  calls: 'Voice calls',
+  login: 'Login',
+};
+
+const obj = (v: unknown): Record<string, unknown> | undefined =>
+  v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;
+const str = (v: unknown): string => (typeof v === 'string' ? v : '');
+
+/** The status page for `serverName`, if config.json names a valid one. */
+export const resolveStatusPage = (
+  statusPages: unknown,
+  serverName: string | undefined,
+): StatusPageConfig | undefined => {
+  if (!serverName) return undefined;
+  const entry = obj(obj(statusPages)?.[serverName]);
+  if (!entry) return undefined;
+  const slug = str(entry.slug);
+  if (!/^[a-z0-9-]{1,64}$/i.test(slug)) return undefined;
+  try {
+    const url = new URL(str(entry.url));
+    const local = url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local)) return undefined;
+    const g = obj(entry.groups) ?? {};
+    return {
+      url: url.origin,
+      slug,
+      groups: {
+        homeserver: str(g.homeserver) || DEFAULT_GROUPS.homeserver,
+        calls: str(g.calls) || DEFAULT_GROUPS.calls,
+        login: str(g.login) || DEFAULT_GROUPS.login,
+      },
+    };
+  } catch {
+    return undefined;
+  }
+};
+
+export const kumaUrls = (page: StatusPageConfig) => ({
+  page: `${page.url}/api/status-page/${page.slug}`,
+  heartbeat: `${page.url}/api/status-page/heartbeat/${page.slug}`,
+});
+
+const DOWN = 0;
+
+const PENDING = 2;
+
+/** Kuma beat time ("2026-09-29 14:16:11.804", UTC) → ms. */
+export const kumaBeatTime = (time: unknown): number | undefined => {
+  const t = Date.parse(`${str(time).trim().replace(' ', 'T')}Z`);
+  return Number.isFinite(t) ? t : undefined;
+};
+
+const sortedBeats = (list: unknown): Record<string, unknown>[] =>
+  (Array.isArray(list) ? list : [])
+    .map((b) => obj(b))
+    .filter((b): b is Record<string, unknown> => !!b && typeof b.status === 'number')
+    .sort((a, b) => str(a.time).localeCompare(str(b.time)));
+
+/**
+ * A group is down when ANY of its monitors is failing across two checks in a
+ * row: its latest beat is down and the one before is down or pending (Kuma
+ * marks a first failure "pending" when the monitor has a retry). One piece
+ * down, say the call token service, already breaks the feature; two checks so
+ * a single blip doesn't flash a banner. Up when every monitor we have beats
+ * for is fine; unknown when the group or its beats are missing.
+ */
+const groupState = (
+  groupName: string | undefined,
+  groups: Map<string, string[]>,
+  beats: Record<string, unknown>,
+): ServiceState => {
+  if (!groupName) return 'unknown';
+  const ids = groups.get(groupName);
+  if (!ids || ids.length === 0) return 'unknown';
+  let known = 0;
+  let down = false;
+  ids.forEach((id) => {
+    const statuses = sortedBeats(beats[id]).map((b) => b.status as number);
+    if (statuses.length === 0) return;
+    known += 1;
+    const [prev, last] = statuses.slice(-2);
+    if (statuses.length >= 2 && last === DOWN && (prev === DOWN || prev === PENDING)) down = true;
+  });
+  if (down) return 'down';
+  return known > 0 ? 'up' : 'unknown';
+};
+
+export const parseKumaStatus = (
+  pageJson: unknown,
+  heartbeatJson: unknown,
+  groupNames: StatusGroups,
+): ServerStatus => {
+  const page = obj(pageJson) ?? {};
+  const groups = new Map<string, string[]>();
+  (Array.isArray(page.publicGroupList) ? page.publicGroupList : []).forEach((g) => {
+    const group = obj(g);
+    if (!group) return;
+    const ids = (Array.isArray(group.monitorList) ? group.monitorList : [])
+      .map((m) => obj(m)?.id)
+      .filter((id): id is number | string => typeof id === 'number' || typeof id === 'string')
+      .map(String);
+    groups.set(str(group.name), ids);
+  });
+  const beats = obj(obj(heartbeatJson)?.heartbeatList) ?? {};
+
+  const maintenance: KumaMaintenance[] = (
+    Array.isArray(page.maintenanceList) ? page.maintenanceList : []
+  )
+    .map((m) => obj(m))
+    .filter((m): m is Record<string, unknown> => !!m && str(m.title) !== '')
+    .filter((m) => !m.status || m.status === 'under-maintenance')
+    .map((m) => {
+      const slot = obj((Array.isArray(m.timeslotList) ? m.timeslotList : [])[0]);
+      const end = Date.parse(str(slot?.endDate));
+      return {
+        id: String(m.id ?? str(m.title)),
+        title: str(m.title),
+        description: str(m.description),
+        ...(Number.isFinite(end) ? { end } : {}),
+      };
+    });
+
+  const incidents: KumaIncident[] = (Array.isArray(page.incidents) ? page.incidents : [])
+    .map((i) => obj(i))
+    .filter((i): i is Record<string, unknown> => !!i && str(i.title) !== '' && i.active !== false)
+    .map((i) => ({
+      id: String(i.id ?? str(i.title)),
+      title: str(i.title),
+      content: str(i.content),
+      style: str(i.style) || 'info',
+      updated: str(i.lastUpdatedDate) || str(i.createdDate),
+    }));
+
+  const hsIds = (groupNames.homeserver && groups.get(groupNames.homeserver)) || [];
+  const hsLatest = hsIds.map((id) => kumaBeatTime(sortedBeats(beats[id]).slice(-1)[0]?.time));
+  const homeserverCheckedAt =
+    hsLatest.length > 0 && hsLatest.every((t): t is number => t !== undefined)
+      ? Math.min(...hsLatest)
+      : undefined;
+
+  return {
+    homeserver: groupState(groupNames.homeserver, groups, beats),
+    ...(homeserverCheckedAt !== undefined ? { homeserverCheckedAt } : {}),
+    calls: groupState(groupNames.calls, groups, beats),
+    login: groupState(groupNames.login, groups, beats),
+    maintenance,
+    incidents,
+  };
+};
+
+/**
+ * Kuma checked the homeserver AFTER this client lost its connection, and it
+ * was fine: the problem is more likely on the user's side. A stale "up" from
+ * before the drop proves nothing (Kuma takes a minute or two to notice an
+ * outage), so it doesn't count.
+ */
+export const serverConfirmedUpSince = (
+  status: ServerStatus | null | undefined,
+  lostAt: number | null | undefined,
+): boolean =>
+  !!status &&
+  !!lostAt &&
+  status.homeserver === 'up' &&
+  status.homeserverCheckedAt !== undefined &&
+  status.homeserverCheckedAt > lostAt;
+
+export type BannerTone = 'Critical' | 'Warning' | 'Primary';
+export type BannerKind =
+  | 'server-down'
+  | 'server-problems'
+  | 'maintenance'
+  | 'calls-down'
+  | 'announcement'
+  | 'login-down';
+export type StatusBanner = {
+  kind: BannerKind;
+  /** Stable id for dismissing (announcements come back when edited). */
+  key: string;
+  tone: BannerTone;
+  text: string;
+  detail?: string;
+  dismissable: boolean;
+};
+
+const formatTime = (ms: number): string =>
+  new Date(ms).toLocaleTimeString(undefined, { hour: 'numeric', minute: '2-digit' });
+
+const incidentTone = (style: string): BannerTone => {
+  if (style === 'danger') return 'Critical';
+  if (style === 'warning') return 'Warning';
+  return 'Primary';
+};
+
+/** Markdown-ish incident text as plain text for the Details line. */
+const plain = (s: string): string =>
+  s
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/[*_`#>]/g, '')
+    .replace(/\s+\n/g, '\n')
+    .trim();
+
+/**
+ * The one strip to show, highest priority first. `syncLost`: this client's
+ * connection is reconnecting/erroring. `where`: the logged-in app or the
+ * login screen.
+ */
+export const pickBanner = (
+  status: ServerStatus | null | undefined,
+  opts: { syncLost: boolean; where: 'client' | 'login'; dismissed?: ReadonlySet<string> },
+): StatusBanner | undefined => {
+  if (!status) return undefined;
+  const dismissed = opts.dismissed ?? new Set<string>();
+  const candidates: StatusBanner[] = [];
+
+  if (status.homeserver === 'down') {
+    if (opts.syncLost || opts.where === 'login') {
+      candidates.push({
+        kind: 'server-down',
+        key: 'server-down',
+        tone: 'Critical',
+        text:
+          opts.where === 'login'
+            ? "Lotus Chat's server is down. We're on it."
+            : "Lotus Chat's server is down. We're on it, reconnecting…",
+        dismissable: false,
+      });
+    } else {
+      candidates.push({
+        kind: 'server-problems',
+        key: 'server-problems',
+        tone: 'Warning',
+        text: "Lotus Chat's server is having problems. Messages may be slow to send or arrive.",
+        dismissable: false,
+      });
+    }
+  }
+
+  const maint = status.maintenance[0];
+  if (maint) {
+    const until = maint.end ? ` until ${formatTime(maint.end)}` : '';
+    candidates.push({
+      kind: 'maintenance',
+      key: `maintenance:${maint.id}`,
+      tone: 'Warning',
+      text: `Maintenance in progress${until}: ${maint.title}. Messages and calls may be interrupted.`,
+      detail: plain(maint.description) || undefined,
+      dismissable: false,
+    });
+  }
+
+  if (opts.where === 'login' && status.login === 'down') {
+    candidates.push({
+      kind: 'login-down',
+      key: 'login-down',
+      tone: 'Warning',
+      text: "Sign-in is having problems right now. If it doesn't work, try again in a few minutes.",
+      dismissable: false,
+    });
+  }
+
+  if (opts.where === 'client' && status.calls === 'down' && status.homeserver !== 'down') {
+    candidates.push({
+      kind: 'calls-down',
+      key: 'calls-down',
+      tone: 'Warning',
+      text: 'Voice calls are down right now. Messages still work.',
+      dismissable: true,
+    });
+  }
+
+  status.incidents.forEach((i) => {
+    candidates.push({
+      kind: 'announcement',
+      key: `announcement:${i.id}:${i.updated}`,
+      tone: incidentTone(i.style),
+      text: i.title,
+      detail: plain(i.content) || undefined,
+      dismissable: true,
+    });
+  });
+
+  return candidates.find((b) => !(b.dismissable && dismissed.has(b.key)));
+};