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>

nix/host-modules/hive-forge/default.nix

@@ -409,6 +409,16 @@ in
     # vhost nor answer DNS for it.
     services.hyperhive.gateway.localNames = lib.optional cfg.behindGateway cfg.domain;
 
+    # This swarm-ui quick-links entry, same `behindGateway` guard as the
+    # vhost/DNS name above — with it off, this host doesn't actually
+    # serve `cfg.domain`, so linking to it would be dead. See
+    # `services.hyperhive.swarm.controller.links`'s description.
+    services.hyperhive.swarm.controller.links = lib.optional cfg.behindGateway {
+      label = "Forge";
+      icon = "⚒";
+      url = "https://${cfg.domain}/";
+    };
+
     # `server_name = forge.domain`, proxies all `/` → forgejo. Tuned for
     # git: `client_max_body_size 1G`, `proxy_read_timeout 1h` (multi-GB
     # clones). SSH stays direct on `forge.sshPort`. See

nix/host-modules/hive-matrix.nix

@@ -508,6 +508,20 @@ in
     # every clause below carries that guard.
     services.hyperhive.gateway.localNames = lib.optional (cfg.gatewayHost != null) cfg.gatewayHost;
 
+    # This swarm-ui quick-links entry. Gated on `gui.enable` too, not just
+    # `gatewayHost != null`: `/` on that vhost only serves fluffychat
+    # (below) when the GUI is on — otherwise the link would 404, the same
+    # reason the old dashboard's H0M3 page hides its Matrix tile on
+    # `state.matrix_gui_enabled` rather than `gatewayHost` alone. See
+    # `services.hyperhive.swarm.controller.links`'s description.
+    services.hyperhive.swarm.controller.links =
+      lib.optional (cfg.gatewayHost != null && cfg.gui.enable)
+        {
+          label = "Matrix";
+          icon = "💬";
+          url = "https://${cfg.gatewayHost}/";
+        };
+
     # Accept-header SPA map, used only by the `/` location below (see
     # docs/gateway.md "SPA fallback"): text/html → index.html, else a
     # sentinel so `try_files` falls through to 404. `appendHttpConfig`

nix/host-modules/swarm-authelia.nix

@@ -485,6 +485,18 @@ in
     # bridge at that wrong answer.
     services.hyperhive.gateway.localNames = [ cfg.domain ];
 
+    # This swarm-ui quick-links entry, same guard as the vhost/DNS name
+    # above (only the host actually running the container claims it —
+    # see `services.hyperhive.swarm.controller.links`'s description for
+    # the contribute-your-own-entry idiom).
+    services.hyperhive.swarm.controller.links = [
+      {
+        label = "Authelia";
+        icon = "🔑";
+        url = "https://${cfg.domain}/";
+      }
+    ];
+
     # `server_name = authelia.domain`, all of `/` → authelia.
     #
     # ⚠️ The server name must be exactly `cfg.domain`, not a near-miss:

nix/host-modules/swarm-controller.nix

@@ -112,6 +112,53 @@ in
         new directory, not just the daemon.
       '';
     };
+
+    links = lib.mkOption {
+      type = lib.types.listOf (
+        lib.types.submodule {
+          options = {
+            label = lib.mkOption {
+              type = lib.types.str;
+              description = "Display label for the link.";
+            };
+            icon = lib.mkOption {
+              type = lib.types.str;
+              default = "";
+              description = "Optional icon emoji or short glyph.";
+            };
+            url = lib.mkOption {
+              type = lib.types.str;
+              description = "Full URL.";
+            };
+          };
+        }
+      );
+      default = [ ];
+      example = lib.literalExpression ''
+        [ { label = "Wiki"; icon = "📖"; url = "https://wiki.example.com/"; } ]
+      '';
+      description = ''
+        Quick links to swarm-wide services, surfaced by the swarm UI's
+        links menu (`GET /api/links`). Same shape and same
+        zero-code-change-to-extend idea as `hyperhive.dashboardLinks`
+        (`nix/agent-modules/dashboard-links.nix`), one level up: rather
+        than one central hardcoded list, each service's own module
+        contributes its own entry when it is actually enabled on this
+        host — `swarm-authelia.nix`, `hive-matrix.nix` and
+        `hive-forge/default.nix` all do — the same list-merge idiom
+        `services.hyperhive.gateway.localNames` already uses. A future
+        service module can push its own entry the same way, and an
+        operator can add arbitrary extra entries here directly; neither
+        needs a swarm-controller or swarm-ui change.
+
+        Only meaningful on the host that actually runs the controller —
+        entries contributed on any other host are computed but never
+        read. In a swarm that splits `swarm-authelia`/`hive-matrix`/
+        `hive-forge` across hosts other than the controller's, this list
+        only reflects what is enabled locally; see each contributing
+        module's own activation condition.
+      '';
+    };
   };
 
   config = lib.mkIf (config.services.hyperhive.enable && cfg.enable) {
@@ -184,6 +231,10 @@ in
           inherit (h) domain;
         }) config.services.hyperhive.swarm.hives
       );
+      # The merged links list — see `links`' description above for who
+      # contributes to it. Consumed by `GET /api/links`
+      # (swarm-controller/src/main.rs::load_links).
+      environment.SWARM_CONTROLLER_LINKS = builtins.toJSON cfg.links;
     };
   };
 }

nix/host-modules/swarm-ui.nix

@@ -124,6 +124,19 @@ in
     # makes the name resolve at all.
     services.hyperhive.gateway.localNames = [ cfg.domain ];
 
+    # This UI's own swagger docs, always same-origin (`/api/docs/` below)
+    # so — unlike authelia/matrix/forge's entries — this one needs no
+    # host name and is never conditional on anything but this module
+    # being enabled at all. See
+    # `services.hyperhive.swarm.controller.links`'s description.
+    services.hyperhive.swarm.controller.links = [
+      {
+        label = "API docs";
+        icon = "🧬";
+        url = "/api/docs/";
+      }
+    ];
+
     # The swarm's front page, and the FIRST `auth_request` anywhere in
     # this gateway (everything else is `auth_basic` + htpasswd).
     #

swarm-controller/src/main.rs

@@ -65,6 +65,7 @@ fn socket_path() -> PathBuf {
     tags(
         (name = "health", description = "liveness probe"),
         (name = "hives", description = "the swarm's hive directory"),
+        (name = "links", description = "swarm service quick links"),
     )
 )]
 struct ApiDoc;
@@ -97,6 +98,9 @@ struct AppState {
     /// Loaded once at startup (`load_hives`); never mutated, so an
     /// `Arc` clone per request is the whole synchronization story.
     hives: Arc<Vec<HiveEntry>>,
+    /// Loaded once at startup (`load_links`); same synchronization story
+    /// as `hives`.
+    links: Arc<Vec<ServiceLink>>,
 }
 
 /// Env var the controller's NixOS module sets from
@@ -136,6 +140,58 @@ async fn get_hives(State(state): State<AppState>) -> Json<Vec<HiveEntry>> {
     Json((*state.hives).clone())
 }
 
+/// One quick link to a swarm-wide service (authelia, matrix, forge, this
+/// daemon's own swagger UI, …). Deliberately generic rather than named
+/// fields per service: each service's own nix module contributes its own
+/// entry to `services.hyperhive.swarm.controller.links` (same list-merge
+/// idiom `services.hyperhive.gateway.localNames` already uses), so adding
+/// a new one is a nix-only change — no new field here, no swarm-ui change.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, ToSchema)]
+struct ServiceLink {
+    label: String,
+    /// Emoji or short glyph. Empty string, not `Option`, when a
+    /// contributing module has none — one fewer null-vs-absent case for
+    /// the frontend to handle, and every real contributor sets one today.
+    icon: String,
+    url: String,
+}
+
+/// Env var the controller's NixOS module sets from the merged
+/// `services.hyperhive.swarm.controller.links` list, JSON-encoded — same
+/// shape/rationale as [`HIVES_ENV`]. Consumed by `GET /api/links`.
+const LINKS_ENV: &str = "SWARM_CONTROLLER_LINKS";
+
+/// Parses [`LINKS_ENV`] into the swarm's service-link list. Same
+/// fall-back-to-empty rationale as `load_hives`: a daemon that can't yet
+/// see this config should still serve `/health` rather than fail startup.
+fn load_links() -> Vec<ServiceLink> {
+    let Some(raw) = std::env::var_os(LINKS_ENV) else {
+        return Vec::new();
+    };
+    match serde_json::from_str(&raw.to_string_lossy()) {
+        Ok(links) => links,
+        Err(e) => {
+            tracing::warn!(error = %e, env = LINKS_ENV, "failed to parse service links, serving an empty list");
+            Vec::new()
+        }
+    }
+}
+
+/// Quick links to swarm-wide services (authelia, matrix, forge, this
+/// daemon's own swagger UI, …), as contributed by each service's own nix
+/// module. Empty when nothing was configured to contribute — a caller
+/// renders 0 links the same way it renders any other count, no special
+/// "not configured" case.
+#[utoipa::path(
+    get,
+    path = "/api/links",
+    responses((status = 200, description = "swarm service quick links", body = Vec<ServiceLink>)),
+    tag = "links"
+)]
+async fn get_links(State(state): State<AppState>) -> Json<Vec<ServiceLink>> {
+    Json((*state.links).clone())
+}
+
 #[tokio::main]
 async fn main() -> Result<()> {
     tracing_subscriber::fmt()
@@ -176,11 +232,13 @@ async fn main() -> Result<()> {
 
     let state = AppState {
         hives: Arc::new(load_hives()),
+        links: Arc::new(load_links()),
     };
 
     let (router, api) = OpenApiRouter::<AppState>::with_openapi(ApiDoc::openapi())
         .routes(routes!(health))
         .routes(routes!(get_hives))
+        .routes(routes!(get_links))
         .split_for_parts();
     // Just the JSON, not the UI — Swagger UI itself is nginx-hosted from
     // the nix store (see the module doc comment above). `api` is
@@ -199,7 +257,9 @@ async fn main() -> Result<()> {
 
 #[cfg(test)]
 mod tests {
-    use super::{DEFAULT_SOCKET, HIVES_ENV, HiveEntry, load_hives};
+    use super::{
+        DEFAULT_SOCKET, HIVES_ENV, HiveEntry, LINKS_ENV, ServiceLink, load_hives, load_links,
+    };
     use std::path::Path;
 
     /// The socket must not share a directory with anything else, because
@@ -277,4 +337,49 @@ mod tests {
             std::env::remove_var(HIVES_ENV);
         }
     }
+
+    /// Same three-state coverage as `load_hives_covers_missing_malformed_and_valid`,
+    /// same reason for one test rather than three (a shared process env var).
+    ///
+    /// SAFETY: single-threaded mutation of a process env var no other test
+    /// in this crate reads; restored (removed) before returning.
+    #[test]
+    fn load_links_covers_missing_malformed_and_valid() {
+        unsafe {
+            std::env::remove_var(LINKS_ENV);
+        }
+        assert_eq!(
+            load_links(),
+            Vec::<ServiceLink>::new(),
+            "unset env var is an empty list, not a startup failure"
+        );
+
+        unsafe {
+            std::env::set_var(LINKS_ENV, "not json");
+        }
+        assert_eq!(
+            load_links(),
+            Vec::<ServiceLink>::new(),
+            "unparseable env var falls back to empty rather than panicking"
+        );
+
+        unsafe {
+            std::env::set_var(
+                LINKS_ENV,
+                r#"[{"label":"Authelia","icon":"🔑","url":"https://auth.example.com/"}]"#,
+            );
+        }
+        assert_eq!(
+            load_links(),
+            vec![ServiceLink {
+                label: "Authelia".to_string(),
+                icon: "🔑".to_string(),
+                url: "https://auth.example.com/".to_string(),
+            }]
+        );
+
+        unsafe {
+            std::env::remove_var(LINKS_ENV);
+        }
+    }
 }