swarm-ui: header links menu for swarm-wide services (hyperhive#3289)

Single 🔗 button in the Shell header (direction 1 of 3 proposed on the
issue) — one fixed element regardless of link count, so it can't
clutter as the list grows, and visible on every route since Shell
wraps all of them. Opens a popover listing whatever GET /api/links
returns (icon + label, opens in a new tab); hidden entirely when the
list is empty, same "don't render a dead affordance" rule the old
dashboard's H0M3 tiles follow for Forge/Matrix.

Docs: docs/swarm/ui.md gets a short section on the feature + the
contribute-your-own-entry idiom.

Verified: npm run build + npm run typecheck clean, headless-chromium
screenshots of both the closed and (temporarily forced open for the
screenshot only) open states, pixel-sampled to confirm the popover is
actually using the dark theme vars and not just looking that way in a
downscaled preview.

docs/swarm/ui.md

@@ -89,6 +89,24 @@ parent — no CA in the hierarchy issues for it implicitly. Left out, the
 vhost falls back to the hive leaf and the swarm's front page opens with a
 name mismatch.
 
+## Quick links
+
+The swarm UI's header carries a single 🔗 button, visible on every route,
+opening a popover of links to other swarm-wide services — authelia,
+matrix, forge, this UI's own swagger docs. Backed by `GET /api/links`
+(swarm-controller), which serves `services.hyperhive.swarm.controller.links`
+(a `listOf { label, icon, url }`, same shape as the per-agent
+`hyperhive.dashboardLinks`).
+
+Rather than one central hardcoded list, each service's own module
+contributes its own entry when it's actually enabled on the controller's
+host — `swarm-authelia.nix`, `hive-matrix.nix` and `hive-forge/default.nix`
+all do, the same list-merge idiom `gateway.localNames` uses above. Adding a
+link for a new service is a nix-only change to that service's own module
+(or an operator adding an entry directly); no swarm-controller or swarm-ui
+change needed. Empty list hides the button rather than showing an empty
+popover.
+
 ## Cross-references
 
 - [`sso.md`](sso.md) — the authelia instance itself, and the user store.

frontend/packages/swarm-ui/src/shell/LinksMenu.css

@@ -0,0 +1,54 @@
+/* <LinksMenu> — a single header icon-button + popover. Kept visually
+   quiet (no border/fill until interacted with) so it reads as chrome,
+   not another nav item. */
+.links-menu {
+  position: relative;
+  margin-left: auto;
+}
+.links-menu-button {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 2em;
+  height: 2em;
+  padding: 0;
+  border: 1px solid transparent;
+  border-radius: 0.4em;
+  background: none;
+  color: var(--fg);
+  font-size: 1em;
+  line-height: 1;
+  cursor: pointer;
+}
+.links-menu-button:hover,
+.links-menu-button[aria-expanded='true'] {
+  border-color: var(--border);
+  background: var(--bg-elev);
+}
+.links-menu-popover {
+  position: absolute;
+  top: calc(100% + 0.4em);
+  right: 0;
+  z-index: 10;
+  display: flex;
+  flex-direction: column;
+  min-width: 10em;
+  padding: 0.4em;
+  border: 1px solid var(--border);
+  border-radius: 0.5em;
+  background: var(--bg-elev);
+  box-shadow: 0 0.25em 0.75em rgba(0, 0, 0, 0.3);
+}
+.links-menu-item {
+  display: flex;
+  align-items: center;
+  gap: 0.5em;
+  padding: 0.4em 0.6em;
+  border-radius: 0.35em;
+  color: var(--fg);
+  text-decoration: none;
+  white-space: nowrap;
+}
+.links-menu-item:hover {
+  background: var(--bg);
+}

frontend/packages/swarm-ui/src/shell/LinksMenu.tsx

@@ -0,0 +1,87 @@
+// <LinksMenu> — the "accessible from every screen" affordance for
+// swarm-wide services (authelia, matrix, forge, this UI's own API
+// docs, …): one fixed header button that never grows the header
+// itself as the list grows, opening a popover with everything
+// `GET /api/links` returns. Lives in `Shell` (not `ui/`) because it
+// owns its own fetch — every other `ui/` primitive is presentational
+// only, this one genuinely isn't reusable outside this one job.
+//
+// The list is entirely server-driven (see swarm-controller's
+// `services.hyperhive.swarm.controller.links` option) — 0 entries
+// hides the button rather than showing an empty popover, same "don't
+// render a dead affordance" rule the old dashboard's H0M3 tiles follow
+// for Forge/Matrix.
+import { useEffect, useRef, useState } from 'preact/hooks';
+import './LinksMenu.css';
+
+interface ServiceLink {
+  label: string;
+  icon: string;
+  url: string;
+}
+
+export function LinksMenu() {
+  const [links, setLinks] = useState<ServiceLink[] | null>(null);
+  const [open, setOpen] = useState(false);
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    fetch('/api/links')
+      .then((r) => (r.ok ? (r.json() as Promise<ServiceLink[]>) : Promise.reject(new Error(`http ${r.status}`))))
+      .then(setLinks)
+      .catch(() => setLinks([])); // best-effort: no button beats a broken one
+  }, []);
+
+  // Close on an outside click or Escape — only listens while open, so
+  // this costs nothing on every other render.
+  useEffect(() => {
+    if (!open) return;
+    function onPointerDown(e: MouseEvent) {
+      if (rootRef.current && !rootRef.current.contains(e.target as Node)) setOpen(false);
+    }
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.key === 'Escape') setOpen(false);
+    }
+    document.addEventListener('pointerdown', onPointerDown);
+    document.addEventListener('keydown', onKeyDown);
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown);
+      document.removeEventListener('keydown', onKeyDown);
+    };
+  }, [open]);
+
+  if (!links || links.length === 0) return null;
+
+  return (
+    <div class="links-menu" ref={rootRef}>
+      <button
+        type="button"
+        class="links-menu-button"
+        aria-haspopup="true"
+        aria-expanded={open}
+        aria-label="swarm services"
+        onClick={() => setOpen((v) => !v)}
+      >
+        🔗
+      </button>
+      {open ? (
+        <div class="links-menu-popover" role="menu">
+          {links.map((link) => (
+            <a
+              key={link.url}
+              class="links-menu-item"
+              href={link.url}
+              target="_blank"
+              rel="noreferrer"
+              role="menuitem"
+              onClick={() => setOpen(false)}
+            >
+              {link.icon ? <span aria-hidden="true">{link.icon}</span> : null}
+              {link.label}
+            </a>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}

frontend/packages/swarm-ui/src/shell/Shell.tsx

@@ -14,6 +14,7 @@
 // is next); no speculative entries.
 import type { ComponentChildren } from 'preact';
 import { Link, useRoute } from 'wouter-preact';
+import { LinksMenu } from './LinksMenu.js';
 import './Shell.css';
 
 const NAV_ITEMS: { href: string; label: string }[] = [
@@ -40,6 +41,7 @@ export function Shell({ children }: { children: ComponentChildren }) {
             <NavLink key={item.href} href={item.href} label={item.label} />
           ))}
         </nav>
+        <LinksMenu />
       </header>
       <div class="shell-body">{children}</div>
     </div>