bugfix meshdisco

Dockerfile

@@ -39,7 +39,7 @@ COPY packages/meta-fuse-core/src/ ./src/
 RUN npm run build
 
 # Stage 3: Build FUSE Driver
-FROM rust:1.86-bookworm AS fuse-builder
+FROM rust:1.89-bookworm AS fuse-builder
 
 WORKDIR /build
 

packages/meta-fuse-core/src/api/APIServer.ts

@@ -91,9 +91,9 @@ export class APIServer {
     this.app.post('/api/fuse/rules/validate', this.handleValidateRule.bind(this));
     this.app.get('/api/fuse/rules/variables', this.handleGetVariables.bind(this));
 
-    // Service discovery — proxies to meta-core's /api/services, resolving the
+    // meta-discovery v1: neighbours heard over UDP, from this service's own
-    // current leader's URL via LeaderClient (no hardcoded hostname).
+    // map — no meta-core needed, so the nav renders even when the core is down.
-    this.app.get('/api/services', this.handleServices.bind(this));
+    this.app.get('/api/neighbors', this.handleNeighbors.bind(this));
 
     // WebDAV access tokens (per-device basic-auth passwords for /webdav).
     this.app.get('/api/webdav-tokens', this.handleListTokens.bind(this));
@@ -134,36 +134,27 @@ export class APIServer {
   }
 
   /**
-   * Proxy handler that forwards /api/services to meta-core's canonical
+   * meta-discovery v1 neighbours, served from this service's own UDP map.
-   * registry endpoint using LeaderClient for discovery.
+   * `services` is an alias kept while older dashboard builds are around.
    */
-  private async handleServices(_req: FastifyRequest, reply: FastifyReply): Promise<void> {
+  private async handleNeighbors(_request: FastifyRequest, reply: FastifyReply): Promise<void> {
-    try {
+    const leaderClient = this.kvManager?.getLeaderClient();
-      const leaderClient = this.kvManager?.getLeaderClient();
+    if (!leaderClient) {
-      if (!leaderClient) {
+      void reply.send({ current: 'meta-fuse', enabled: false, count: 0, neighbors: [] });
-        reply.status(503).send({ error: 'KVManager not initialized' });
+      return;
-        return;
-      }
-      const apiUrl = await leaderClient.getApiUrl();
-      if (!apiUrl) {
-        reply.status(503).send({ error: 'Leader not available yet' });
-        return;
-      }
-      const response = await fetch(`${apiUrl}/api/services`, {
-        signal: AbortSignal.timeout(5000),
-      });
-      if (!response.ok) {
-        reply.status(response.status).send({
-          error: `Upstream ${apiUrl} returned ${response.status}`,
-        });
-        return;
-      }
-      reply.send(await response.json());
-    } catch (err: any) {
-      reply.status(502).send({ error: err?.message ?? String(err) });
     }
+    const neighbors = leaderClient.getNeighbors();
+    void reply.send({
+      current: 'meta-fuse',
+      enabled: true,
+      count: neighbors.length,
+      neighbors,
+      services: neighbors,
+      self: leaderClient.self(),
+    });
   }
 
+
   /**
    * Start the server
    */

packages/meta-fuse-core/src/discovery/meshdisco.ts

@@ -0,0 +1,441 @@
+/**
+ * meta-discovery v1 — UDP multicast service discovery.
+ *
+ * Replaces the two file-based mechanisms that required a shared /meta-core
+ * volume: `locks/kv-leader.info` (locating meta-core at boot) and
+ * `services/<name>-<host>.json` (the dashboard nav registry). Both answered the
+ * same question — where is meta-core, and who else is on this network — so one
+ * announce packet answers both, and discovery scope becomes the docker network
+ * rather than the mounted volume.
+ *
+ * The normative spec is docs/project-architecture/service-discovery.md.
+ *
+ * ⚠ MIRRORED FILE. Byte-identical copies live in meta-sort-core, meta-fuse-core
+ * and meta-dup-core. They cannot share a package: meta-fuse-core and
+ * meta-dup-core do not depend on @metazla/meta-interface at all, and each
+ * submodule is its own Docker build context, so a workspace dep resolves
+ * outside the build. Edit one copy → edit all three, and
+ * `scripts/check-mirrors.sh` will tell you if you forgot.
+ */
+
+import dgram from 'dgram';
+import { hostname, networkInterfaces } from 'os';
+
+export const PROTOCOL_VERSION = 1;
+export const DEFAULT_GROUP = '239.255.77.1';
+export const DEFAULT_PORT = 9399;
+export const DEFAULT_INTERVAL_MS = 10_000;
+/** A neighbour unseen for interval × this is dropped. Replaces the reaper. */
+export const LIVENESS_FACTOR = 3;
+
+export const TYPE_DISCOVERY = 'discovery';
+export const TYPE_ANNOUNCE = 'announce';
+export const ROLE_CORE = 'core';
+export const ROLE_SERVICE = 'service';
+
+/** Mirrors meta-core's GET /urls response minus redisUrl (retired). */
+export interface MeshUrls {
+    hostname: string;
+    baseUrl: string;
+    apiUrl: string;
+    webdavUrl: string;
+    webdavUrlInternal: string;
+}
+
+export interface MeshMessage {
+    v: number;
+    type: string;
+    name?: string;
+    instance?: string;
+    role?: string;
+    version?: string;
+    status?: string;
+    baseUrl?: string;
+    /** Present only when role === 'core'. */
+    urls?: MeshUrls;
+    /** Reserved for a future HMAC; v1 ignores it. */
+    token?: string;
+}
+
+export interface MeshNeighbor extends MeshMessage {
+    /** Source address taken from the packet, never from the payload. */
+    addr: string;
+    lastSeen: number;
+}
+
+export interface MeshNodeConfig {
+    name: string;
+    instance?: string;
+    role?: string;
+    version?: string;
+    group?: string;
+    port?: number;
+    intervalMs?: number;
+    enabled?: boolean;
+    /** Rebuilt on every announce so the payload never goes stale. */
+    payload?: () => { baseUrl?: string; status?: string; urls?: MeshUrls };
+}
+
+/** IPv4 addresses of every up, non-internal interface. */
+function localInterfaceAddresses(): string[] {
+    const out: string[] = [];
+    const nets = networkInterfaces();
+    for (const name of Object.keys(nets)) {
+        for (const ni of nets[name] ?? []) {
+            // Node has flip-flopped between 'IPv4' and 4 for `family`.
+            const isV4 = (ni as { family: string | number }).family === 'IPv4' ||
+                (ni as { family: string | number }).family === 4;
+            if (isV4 && !ni.internal && ni.address) out.push(ni.address);
+        }
+    }
+    return out;
+}
+
+/** First non-internal IPv4 address, or the hostname. Matches the Go helper. */
+export function localIPv4(): string {
+    return localInterfaceAddresses()[0] ?? hostname();
+}
+
+/**
+ * One participant in the mesh: announces itself, answers probes, and keeps a
+ * TTL map of everyone else.
+ */
+export class MeshNode {
+    private cfg: Required<Omit<MeshNodeConfig, 'payload'>> & Pick<MeshNodeConfig, 'payload'>;
+    private socket: dgram.Socket | null = null;
+    private timer: NodeJS.Timeout | null = null;
+    private neighbors = new Map<string, MeshNeighbor>();
+    private ifaceAddrs: string[] = [];
+    private listeners: ((n: MeshNeighbor) => void)[] = [];
+    private started = false;
+
+    constructor(config: MeshNodeConfig) {
+        this.cfg = {
+            name: config.name,
+            instance: config.instance ?? hostname(),
+            role: config.role ?? ROLE_SERVICE,
+            version: config.version ?? '',
+            group: config.group ?? DEFAULT_GROUP,
+            port: config.port ?? DEFAULT_PORT,
+            intervalMs: config.intervalMs ?? DEFAULT_INTERVAL_MS,
+            enabled: config.enabled ?? true,
+            payload: config.payload,
+        };
+    }
+
+    async start(): Promise<void> {
+        if (this.started || !this.cfg.enabled) {
+            if (!this.cfg.enabled) console.log('[meshdisco] Disabled by configuration');
+            return;
+        }
+        this.started = true;
+
+        await new Promise<void>((resolve) => {
+            const socket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
+            this.socket = socket;
+
+            socket.on('message', (buf, rinfo) => this.onMessage(buf, rinfo));
+            socket.on('error', (err) => {
+                // Never fatal: a host that blocks multicast must degrade, not
+                // take the service down.
+                console.error('[meshdisco] Socket error:', err.message);
+            });
+
+            socket.bind(this.cfg.port, '0.0.0.0', () => {
+                try {
+                    socket.setMulticastTTL(1); // link-local only
+                } catch (e) {
+                    console.warn('[meshdisco] Could not set multicast TTL:', e);
+                }
+
+                // Join on EVERY interface. A container on two docker networks
+                // that joins only the default route silently sees one network.
+                this.ifaceAddrs = localInterfaceAddresses();
+                let joined = 0;
+                for (const addr of this.ifaceAddrs) {
+                    try {
+                        socket.addMembership(this.cfg.group, addr);
+                        joined++;
+                    } catch (e) {
+                        console.warn(`[meshdisco] Join ${this.cfg.group} on ${addr} failed:`, e);
+                    }
+                }
+                console.log(
+                    `[meshdisco] Listening on ${this.cfg.group}:${this.cfg.port} as ` +
+                    `${this.cfg.name}/${this.cfg.instance} (joined ${joined} of ${this.ifaceAddrs.length} interfaces)`
+                );
+                resolve();
+            });
+        });
+
+        this.announce();
+        this.probe();
+        this.timer = setInterval(() => this.announce(), this.cfg.intervalMs);
+        // Don't hold the event loop open on shutdown.
+        this.timer.unref?.();
+    }
+
+    async stop(): Promise<void> {
+        if (!this.started) return;
+        this.started = false;
+        if (this.timer) { clearInterval(this.timer); this.timer = null; }
+        // Final "stopping" announce so neighbours drop us immediately rather
+        // than waiting out the staleness window.
+        this.announce('stopping');
+        await new Promise<void>((resolve) => {
+            if (!this.socket) return resolve();
+            try { this.socket.close(() => resolve()); } catch { resolve(); }
+        });
+        this.socket = null;
+        this.listeners = [];
+    }
+
+    /** Multicast a probe; every listener replies immediately. */
+    probe(): void {
+        this.send({ v: PROTOCOL_VERSION, type: TYPE_DISCOVERY });
+    }
+
+    /** Everyone heard from inside the staleness window, sorted by name. */
+    getNeighbors(): MeshNeighbor[] {
+        const cutoff = Date.now() - this.cfg.intervalMs * LIVENESS_FACTOR;
+        const out: MeshNeighbor[] = [];
+        for (const [key, nb] of this.neighbors) {
+            if (nb.lastSeen < cutoff) { this.neighbors.delete(key); continue; }
+            out.push(nb);
+        }
+        return out.sort((a, b) => (a.name ?? '').localeCompare(b.name ?? ''));
+    }
+
+    /** One row per service name, most recently seen instance wins. */
+    getNeighborsByName(): MeshNeighbor[] {
+        const best = new Map<string, MeshNeighbor>();
+        for (const nb of this.getNeighbors()) {
+            const cur = best.get(nb.name ?? '');
+            if (!cur || nb.lastSeen > cur.lastSeen) best.set(nb.name ?? '', nb);
+        }
+        return [...best.values()].sort((a, b) => (a.name ?? '').localeCompare(b.name ?? ''));
+    }
+
+    /** Cores only — what a locator filters on. */
+    getCores(): MeshNeighbor[] {
+        return this.getNeighbors().filter((n) => n.role === ROLE_CORE && n.urls);
+    }
+
+    /** This node's own announce, so a UI can render itself without waiting. */
+    self(): MeshNeighbor {
+        return { ...this.buildAnnounce('running'), addr: '', lastSeen: Date.now() };
+    }
+
+    /** Fires for every announce received (after the self-echo filter). */
+    onAnnounce(cb: (n: MeshNeighbor) => void): void {
+        this.listeners.push(cb);
+    }
+
+    private onMessage(buf: Buffer, rinfo: dgram.RemoteInfo): void {
+        let msg: MeshMessage;
+        try {
+            msg = JSON.parse(buf.toString('utf8')) as MeshMessage;
+        } catch {
+            return; // foreign traffic on the group
+        }
+        if (msg.v !== PROTOCOL_VERSION) return;
+        // Drop our own multicast echo.
+        if (msg.instance && msg.instance === this.cfg.instance && msg.name === this.cfg.name) return;
+
+        if (msg.type === TYPE_DISCOVERY) {
+            this.replyTo(rinfo);
+            return;
+        }
+        if (msg.type !== TYPE_ANNOUNCE || !msg.name) return;
+
+        const key = msg.instance ? `${msg.name}|${msg.instance}` : msg.name;
+        if (msg.status === 'stopping') { this.neighbors.delete(key); return; }
+
+        const nb: MeshNeighbor = { ...msg, addr: rinfo.address, lastSeen: Date.now() };
+        this.neighbors.set(key, nb);
+        for (const cb of this.listeners) {
+            try { cb(nb); } catch (e) { console.error('[meshdisco] Listener threw:', e); }
+        }
+    }
+
+    private buildAnnounce(status: string): MeshMessage {
+        const msg: MeshMessage = {
+            v: PROTOCOL_VERSION,
+            type: TYPE_ANNOUNCE,
+            name: this.cfg.name,
+            instance: this.cfg.instance,
+            role: this.cfg.role,
+            version: this.cfg.version,
+            status,
+        };
+        if (this.cfg.payload) {
+            const p = this.cfg.payload();
+            if (p.baseUrl) msg.baseUrl = p.baseUrl;
+            if (p.status && status === 'running') msg.status = p.status;
+            // Only a core may carry a URLs block — a service announcing one
+            // would let any container impersonate meta-core.
+            if (this.cfg.role === ROLE_CORE && p.urls) msg.urls = p.urls;
+        }
+        return msg;
+    }
+
+    private announce(status = 'running'): void {
+        this.send(this.buildAnnounce(status));
+    }
+
+    private replyTo(rinfo: dgram.RemoteInfo): void {
+        const body = Buffer.from(JSON.stringify(this.buildAnnounce('running')));
+        try {
+            this.socket?.send(body, rinfo.port, rinfo.address);
+        } catch (e) {
+            console.warn('[meshdisco] Reply failed:', e);
+        }
+    }
+
+    /** Writes once per interface — the default route alone reaches one network. */
+    private send(msg: MeshMessage): void {
+        const socket = this.socket;
+        if (!socket) return;
+        const body = Buffer.from(JSON.stringify(msg));
+        for (const addr of this.ifaceAddrs) {
+            try {
+                socket.setMulticastInterface(addr);
+                socket.send(body, this.cfg.port, this.cfg.group);
+            } catch (e) {
+                console.warn(`[meshdisco] Send on ${addr} failed:`, e);
+            }
+        }
+    }
+}
+
+export interface MetaCoreLocatorConfig {
+    /** This service's name, for its own announce. */
+    serviceName: string;
+    /** Browser-facing URL for the nav menu. */
+    baseUrl?: string;
+    version?: string;
+    /**
+     * Explicit meta-core API URL. When set this ALWAYS wins and the wire is
+     * never consulted for core selection — see the spec's "the pin always
+     * wins". This is what stops a client box from latching onto a gateway
+     * box's core when both are reachable on a shared network.
+     */
+    metaCoreUrl?: string;
+    group?: string;
+    port?: number;
+    intervalMs?: number;
+    enabled?: boolean;
+}
+
+/**
+ * Locates meta-core over UDP, replacing the read of
+ * /meta-core/locks/kv-leader.info.
+ */
+export class MetaCoreLocator {
+    private node: MeshNode;
+    private cfg: MetaCoreLocatorConfig;
+    private current: MeshUrls | null = null;
+    private changeCallbacks: (() => void)[] = [];
+
+    constructor(config: MetaCoreLocatorConfig) {
+        this.cfg = config;
+        this.node = new MeshNode({
+            name: config.serviceName,
+            role: ROLE_SERVICE,
+            version: config.version,
+            group: config.group,
+            port: config.port,
+            intervalMs: config.intervalMs,
+            enabled: config.enabled,
+            payload: () => ({ baseUrl: config.baseUrl ?? `http://${localIPv4()}` }),
+        });
+
+        this.node.onAnnounce((nb) => {
+            if (nb.role !== ROLE_CORE || !nb.urls) return;
+            if (this.cfg.metaCoreUrl) return; // pinned: the wire cannot move us
+
+            const prev = this.current;
+            if (!prev) {
+                this.current = nb.urls;
+                console.log(`[meshdisco] meta-core discovered at ${nb.urls.apiUrl} (${nb.addr})`);
+                this.notifyChange();
+                return;
+            }
+            if (prev.apiUrl === nb.urls.apiUrl) {
+                this.current = nb.urls; // refresh the rest of the fields
+                return;
+            }
+            // A second, different core is announcing. Do not flap between
+            // them — keep the first and say so loudly, because on a PCS box
+            // this means a client container can see the gateway's core.
+            console.warn(
+                `[meshdisco] Ignoring a second meta-core at ${nb.urls.apiUrl} (${nb.addr}); ` +
+                `staying with ${prev.apiUrl}. Set META_CORE_URL to pin this explicitly.`
+            );
+        });
+    }
+
+    async start(): Promise<void> {
+        if (this.cfg.metaCoreUrl) {
+            console.log(`[meshdisco] meta-core pinned to ${this.cfg.metaCoreUrl}; discovery is advisory`);
+        }
+        await this.node.start();
+    }
+
+    async stop(): Promise<void> {
+        await this.node.stop();
+        this.changeCallbacks = [];
+    }
+
+    /** The pin if set, else whatever discovery elected. */
+    getApiUrl(): string | null {
+        if (this.cfg.metaCoreUrl) return this.cfg.metaCoreUrl;
+        return this.current?.apiUrl ?? null;
+    }
+
+    /** Full URLs block. null when pinned and /urls has not been fetched yet. */
+    getUrls(): MeshUrls | null {
+        return this.current;
+    }
+
+    /**
+     * Block until meta-core is located. Probes immediately and re-probes every
+     * 500ms — the same loop shape as the old LeaderClient.waitForLeader, so the
+     * 30s boot timeout semantics are preserved exactly.
+     */
+    async waitForCore(timeoutMs = 30_000): Promise<string> {
+        const deadline = Date.now() + timeoutMs;
+        let logged = false;
+        while (Date.now() < deadline) {
+            const url = this.getApiUrl();
+            if (url) return url;
+            if (!logged) { console.log('[meshdisco] Waiting for meta-core...'); logged = true; }
+            this.node.probe();
+            await new Promise((r) => setTimeout(r, 500));
+        }
+        throw new Error(`[meshdisco] No meta-core found within ${timeoutMs}ms`);
+    }
+
+    /** Fires when the elected core's apiUrl changes. Replaces the fs.watch. */
+    onChange(cb: () => void): void {
+        this.changeCallbacks.push(cb);
+    }
+
+    getNeighbors(): MeshNeighbor[] {
+        return this.node.getNeighborsByName();
+    }
+
+    self(): MeshNeighbor {
+        return this.node.self();
+    }
+
+    probe(): void {
+        this.node.probe();
+    }
+
+    private notifyChange(): void {
+        for (const cb of this.changeCallbacks) {
+            try { cb(); } catch (e) { console.error('[meshdisco] Change callback threw:', e); }
+        }
+    }
+}

packages/meta-fuse-core/src/index.ts

@@ -70,6 +70,9 @@ async function main(): Promise<void> {
         serviceName: 'meta-fuse',
         apiPort: config.apiPort,
         baseUrl: config.baseUrl,
+        // Pin: when META_CORE_URL is set, UDP discovery never overrides it.
+        // See docs/project-architecture/service-discovery.md.
+        metaCoreUrl: process.env.META_CORE_URL,
         redisPrefix: config.redisPrefix,
     });
 

packages/meta-fuse-core/src/kv/IKVClient.ts

@@ -58,7 +58,7 @@ export interface IKVClient {
 }
 
 /**
- * Leader lock file content format (kv-leader.info)
+ * meta-core's identity and URL set (from its UDP announce, or /urls)
  * Written by meta-core leader, read by other services
  */
 export interface LeaderLockInfo {

packages/meta-fuse-core/src/kv/KVManager.ts

@@ -2,7 +2,7 @@
  * KV Manager for meta-fuse (FOLLOWER-only)
  *
  * Simplified KV manager that:
- * 1. Discovers the leader via LeaderClient (reads kv-leader.info)
+ * 1. Locates meta-core via LeaderClient (UDP announce, meta-discovery v1)
  * 2. Creates Redis client connection
  * 3. Handles reconnection on leader failure
  *
@@ -13,7 +13,6 @@
 import { hostname } from 'os';
 import { Logger } from 'tslog';
 import { LeaderClient } from './LeaderClient.js';
-import { ServiceRegistration } from './ServiceRegistration.js';
 import { RedisClient } from './RedisClient.js';
 import type { LeaderLockInfo } from './IKVClient.js';
 
@@ -48,7 +47,6 @@ interface KVManagerConfig {
 export class KVManager {
     private config: Required<KVManagerConfig>;
     private leaderClient: LeaderClient | null = null;
-    private serviceRegistration: ServiceRegistration | null = null;
     private redisClient: RedisClient | null = null;
     private isStarted = false;
     private isShuttingDown = false;
@@ -80,14 +78,15 @@ export class KVManager {
 
         logger.info(`Starting KVManager for ${this.config.serviceName}...`);
 
-        // Initialize and start service registration for heartbeat
+        // No separate service registration step any more: the LeaderClient's
-        const apiUrl = this.config.baseUrl || `http://${hostname()}:${this.config.apiPort}`;
+        // discovery node announces this service on the same UDP group it
-        this.serviceRegistration = new ServiceRegistration({
+        // listens on, so being discoverable and discovering are one thing.
-            metaCorePath: this.config.metaCorePath,
+        // Browser-facing URL for the nav menu, in the order the spec requires:
-            serviceName: this.config.serviceName,
+        // PUBLIC_URL (reachable when there is no Caddy perimeter in front — a
-            apiUrl
+        // debug-direct port) -> BASE_URL (the Caddy URL) -> container host.
-        });
+        // Announcing a Caddy URL on a stack with no Caddy running is what puts
-        await this.serviceRegistration.start();
+        // dead links in every neighbour's menu.
+        const apiUrl = process.env.PUBLIC_URL || this.config.baseUrl || `http://${hostname()}:${this.config.apiPort}`;
 
         // If direct Redis URL provided, skip leader discovery
         if (this.config.redisUrl) {
@@ -99,8 +98,9 @@ export class KVManager {
 
         // Use leader client
         this.leaderClient = new LeaderClient({
-            metaCorePath: this.config.metaCorePath,
+            metaCoreUrl: this.config.metaCoreUrl || undefined,
-            metaCoreUrl: this.config.metaCoreUrl || undefined
+            serviceName: this.config.serviceName,
+            baseUrl: apiUrl,
         });
 
         // Set up leader change callback
@@ -163,10 +163,6 @@ export class KVManager {
         }
 
         // Stop service registration (if it was started)
-        if (this.serviceRegistration) {
-            await this.serviceRegistration.stop();
-            this.serviceRegistration = null;
-        }
 
         // Disconnect Redis
         await this.disconnectRedis();
@@ -351,9 +347,6 @@ export class KVManager {
     /**
      * Get service registration instance
      */
-    getServiceRegistration(): ServiceRegistration | null {
-        return this.serviceRegistration;
-    }
 
     /**
      * Get configured paths

packages/meta-fuse-core/src/kv/LeaderClient.ts

@@ -1,29 +1,48 @@
 /**
- * LeaderClient - Client for reading leader info from meta-core
+ * LeaderClient - locates meta-core and exposes its URLs.
  *
- * This replaces the old LeaderDiscovery.ts by delegating leader election
+ * Since meta-discovery v1 this is a thin adapter over MetaCoreLocator
- * to meta-core (Go sidecar) and just reading the results.
+ * (../discovery/meshdisco.js): meta-core is found by UDP announce instead of by
+ * reading /meta-core/locks/kv-leader.info, which means this service no longer
+ * needs the /meta-core volume mounted at all.
  *
- * Features:
+ * The public surface is deliberately unchanged so KVManager and its callers did
- * - Reads kv-leader.info file for leader URLs
+ * not have to move: getLeaderInfo / getUrls / getApiUrl / getWebdavUrl*,
- * - Calls meta-core /urls API for current leader URLs
+ * waitForLeader (same 30s default), startWatching / onChange (the fs.watch on
- * - Watches for leader changes via file system watcher
+ * the lock dir became "an announce arrived carrying a different apiUrl").
+ *
+ * Precedence is the pin: when metaCoreUrl (META_CORE_URL) is set it always
+ * wins and the wire is never consulted for core selection. See
+ * docs/project-architecture/service-discovery.md.
+ *
+ * The name "leader" is legacy: meta-core's flock election is vestigial, and
+ * redisUrl has been empty since the api-mediated-access lockdown.
  */
 
-import { promises as fs } from 'fs';
-import { watch, FSWatcher } from 'fs';
-import { dirname } from 'path';
 import { Logger } from 'tslog';
+import { MetaCoreLocator, type MeshNeighbor } from '../discovery/meshdisco.js';
 import type { LeaderLockInfo } from './IKVClient.js';
 
 const logger = new Logger({ name: 'LeaderClient' });
 
 export interface LeaderClientConfig {
-    /** Path to META_CORE_VOLUME (e.g., /meta-core) */
+    /**
-    metaCorePath: string;
+     * @deprecated Unused since meta-discovery v1. Kept so existing callers
+     * compile unchanged; nothing reads the volume any more.
+     */
+    metaCorePath?: string;
 
-    /** meta-core API URL (e.g., http://meta-core:9000 or http://localhost:9000) */
+    /** meta-core API URL. When set, discovery never overrides it. */
     metaCoreUrl?: string;
+
+    /** This service's name, used for its own announce. */
+    serviceName?: string;
+
+    /** Browser-facing URL announced for the nav menu. */
+    baseUrl?: string;
+
+    /** Service version, display only. */
+    version?: string;
 }
 
 export interface URLsResponse {
@@ -38,73 +57,74 @@ export interface URLsResponse {
 
 export class LeaderClient {
     private config: LeaderClientConfig;
-    private infoFilePath: string;
+    private locator: MetaCoreLocator;
     private leaderInfo: LeaderLockInfo | null = null;
-    private watcher: FSWatcher | null = null;
     private onChangeCallbacks: (() => void)[] = [];
+    private started = false;
 
-    // URL caching
+    // Only used on the pinned path, where URLs still come from GET /urls.
+    // A discovered core carries them in the announce itself.
     private cachedUrls: URLsResponse | null = null;
     private urlsCacheTime: number = 0;
-    private readonly urlsCacheTTL: number = 5000; // 5 seconds
+    private readonly urlsCacheTTL: number = 5000;
 
     constructor(config: LeaderClientConfig) {
         this.config = config;
-        this.infoFilePath = `${config.metaCorePath}/locks/kv-leader.info`;
+        this.locator = new MetaCoreLocator({
+            serviceName: config.serviceName ?? 'meta-fuse',
+            baseUrl: config.baseUrl,
+            version: config.version,
+            metaCoreUrl: config.metaCoreUrl,
+            enabled: process.env.ENABLE_UDP_DISCOVERY !== 'false' &&
+                process.env.ENABLE_UDP_DISCOVERY !== '0',
+        });
+        this.locator.onChange(() => {
+            this.cachedUrls = null;
+            this.urlsCacheTime = 0;
+            this.notifyChange();
+        });
+    }
+
+    private async ensureStarted(): Promise<void> {
+        if (this.started) return;
+        this.started = true;
+        await this.locator.start();
     }
 
     /**
-     * Read API URL from file (plain text format)
+     * Guard against a rollback reintroducing direct Redis exposure.
+     * api-mediated-access PR D removed redisUrl; ALLOW_LEGACY_REDIS_URL=1
+     * downgrades this to a warning during a deliberate temporary rollback.
      */
-    private async getApiUrlFromFile(): Promise<string | null> {
+    private assertNoRedisUrl(redisUrl: string | undefined): void {
-        try {
+        if (!redisUrl) return;
-            const content = await fs.readFile(this.infoFilePath, 'utf-8');
+        const msg =
-            return content.trim() || null;
+            'meta-core still publishes redisUrl; direct Redis access was retired ' +
-        } catch (error: any) {
+            'by the api-mediated-access lockdown. Verify meta-core version.';
-            logger.error(`Failed to read API URL from file: ${error.message}`);
+        if (process.env.ALLOW_LEGACY_REDIS_URL === '1') {
-            return null;
+            logger.warn('WARNING: ' + msg);
+        } else {
+            throw new Error(msg);
         }
     }
 
-    /**
-     * Fetch URLs from meta-core /urls API with caching
-     */
     private async fetchUrls(apiUrl: string): Promise<URLsResponse | null> {
-        // Check cache
         const now = Date.now();
         if (this.cachedUrls && (now - this.urlsCacheTime) < this.urlsCacheTTL) {
             return this.cachedUrls;
         }
-
         try {
             const response = await fetch(`${apiUrl}/urls`, {
                 method: 'GET',
                 headers: { 'Accept': 'application/json' },
                 signal: AbortSignal.timeout(5000)
             });
-
             if (!response.ok) {
                 logger.error(`Failed to fetch URLs: ${response.status} ${response.statusText}`);
                 return null;
             }
-
             const parsed = await response.json() as URLsResponse;
-            // api-mediated-access PR D: redisUrl is no longer published by
+            this.assertNoRedisUrl(parsed.redisUrl);
-            // meta-core. If it shows up, an older build snuck back in —
-            // fail loudly so the rollback can't go unnoticed. Set
-            // ALLOW_LEGACY_REDIS_URL=1 to downgrade to a warning during a
-            // deliberate temporary rollback.
-            if (parsed.redisUrl) {
-                const msg =
-                    'meta-core still publishes redisUrl; direct Redis access ' +
-                    'was retired by the api-mediated-access lockdown. Verify ' +
-                    'meta-core version.';
-                if (process.env.ALLOW_LEGACY_REDIS_URL === '1') {
-                    logger.warn('WARNING: ' + msg);
-                } else {
-                    throw new Error(msg);
-                }
-            }
             this.cachedUrls = parsed;
             this.urlsCacheTime = now;
             return this.cachedUrls;
@@ -115,23 +135,37 @@ export class LeaderClient {
     }
 
     /**
-     * Read leader info from file and /urls API
+     * Resolve meta-core's URLs — straight from the announce when discovered
+     * (no HTTP hop needed), or over HTTP when pinned.
      */
+    async getUrls(): Promise<URLsResponse | null> {
+        await this.ensureStarted();
+
+        const wire = this.locator.getUrls();
+        if (wire && !this.config.metaCoreUrl) {
+            return {
+                hostname: wire.hostname,
+                baseUrl: wire.baseUrl,
+                apiUrl: wire.apiUrl,
+                redisUrl: '',
+                webdavUrl: wire.webdavUrl,
+                webdavUrlInternal: wire.webdavUrlInternal,
+                isLeader: true,
+            };
+        }
+
+        const apiUrl = this.locator.getApiUrl();
+        if (!apiUrl) {
+            logger.error('No meta-core API URL available');
+            return null;
+        }
+        return this.fetchUrls(apiUrl);
+    }
+
     async getLeaderInfo(): Promise<LeaderLockInfo | null> {
         try {
-            // Read API URL from file (plain text)
+            const urls = await this.getUrls();
-            const apiUrl = await this.getApiUrlFromFile();
+            if (!urls) return null;
-            if (!apiUrl) {
-                return null;
-            }
-
-            // Fetch full info from /urls API
-            const urls = await this.fetchUrls(apiUrl);
-            if (!urls) {
-                return null;
-            }
-
-            // Convert URLsResponse to LeaderLockInfo
             this.leaderInfo = {
                 hostname: urls.hostname,
                 baseUrl: urls.baseUrl,
@@ -140,7 +174,7 @@ export class LeaderClient {
                 webdavUrl: urls.webdavUrl,
                 webdavUrlInternal: urls.webdavUrlInternal,
                 timestamp: Date.now(),
-                pid: 0 // Unknown for remote leader
+                pid: 0
             };
             return this.leaderInfo;
         } catch (error: any) {
@@ -149,138 +183,64 @@ export class LeaderClient {
         }
     }
 
-    /**
-     * Get Redis URL from leader info
-     */
     async getRedisUrl(): Promise<string | null> {
-        const info = await this.getLeaderInfo();
+        return (await this.getLeaderInfo())?.redisUrl ?? null;
-        return info?.redisUrl ?? null;
     }
 
-    /**
-     * Get WebDAV URL from leader info (external, via nginx/HTTPS)
-     */
     async getWebdavUrl(): Promise<string | null> {
-        const info = await this.getLeaderInfo();
+        return (await this.getLeaderInfo())?.webdavUrl ?? null;
-        return info?.webdavUrl ?? null;
     }
 
-    /**
+    /** Internal WebDAV URL — use for container-to-container access. */
-     * Get internal WebDAV URL from leader info (direct to port 9000)
-     * Use this for container-to-container communication
-     */
     async getWebdavUrlInternal(): Promise<string | null> {
-        const info = await this.getLeaderInfo();
+        return (await this.getLeaderInfo())?.webdavUrlInternal ?? null;
-        return info?.webdavUrlInternal ?? null;
     }
 
-    /**
-     * Get meta-core API URL from leader info
-     */
     async getApiUrl(): Promise<string | null> {
-        const info = await this.getLeaderInfo();
+        return (await this.getLeaderInfo())?.apiUrl ?? null;
-        return info?.apiUrl ?? null;
     }
 
     /**
-     * Call meta-core /urls API to get current URLs
+     * Block until meta-core is reachable. Probes immediately then every 500ms,
-     * Useful for getting URLs when you don't want to read the file directly
+     * matching the previous file-polling loop's timing exactly.
-     */
-    async getUrls(): Promise<URLsResponse | null> {
-        // First try using configured metaCoreUrl
-        let apiUrl: string | null = this.config.metaCoreUrl ?? null;
-
-        // Fall back to reading from file
-        if (!apiUrl) {
-            apiUrl = await this.getApiUrlFromFile();
-        }
-
-        if (!apiUrl) {
-            logger.error('No meta-core API URL available');
-            return null;
-        }
-
-        return this.fetchUrls(apiUrl);
-    }
-
-    /**
-     * Wait for leader info to be available
      */
     async waitForLeader(timeoutMs: number = 30000): Promise<LeaderLockInfo> {
-        const startTime = Date.now();
+        await this.ensureStarted();
-        const pollInterval = 500;
+        const deadline = Date.now() + timeoutMs;
 
-        while (Date.now() - startTime < timeoutMs) {
+        await this.locator.waitForCore(timeoutMs);
+
+        while (Date.now() < deadline) {
             const info = await this.getLeaderInfo();
             if (info) {
-                logger.info(`Leader found: ${info.hostname} at ${info.redisUrl}`);
+                logger.info(`meta-core found: ${info.hostname} at ${info.apiUrl}`);
                 return info;
             }
-
+            logger.debug('Waiting for meta-core...');
-            logger.debug('Waiting for leader...');
+            await new Promise(resolve => setTimeout(resolve, 500));
-            await new Promise(resolve => setTimeout(resolve, pollInterval));
         }
-
+        throw new Error(`No meta-core found within ${timeoutMs}ms`);
-        throw new Error(`No leader found within ${timeoutMs}ms`);
     }
 
     /**
-     * Start watching for leader changes
+     * Previously an fs.watch on the lock directory. Discovery is always
+     * listening, so this only has to make sure the node is running.
      */
     startWatching(): void {
-        if (this.watcher) {
+        void this.ensureStarted();
-            return; // Already watching
-        }
-
-        const lockDir = dirname(this.infoFilePath);
-
-        try {
-            this.watcher = watch(lockDir, (eventType, filename) => {
-                if (filename === 'kv-leader.info') {
-                    logger.debug(`Lock file ${eventType}, invalidating cache...`);
-                    // Invalidate cache to force fresh API call
-                    this.cachedUrls = null;
-                    this.urlsCacheTime = 0;
-
-                    this.getLeaderInfo().then(() => {
-                        this.notifyChange();
-                    }).catch((err) => logger.error(`Error reloading leader info: ${err.message}`));
-                }
-            });
-
-            this.watcher.on('error', (error: any) => {
-                logger.warn(`File watcher error: ${error.message}`);
-            });
-
-            logger.info(`Watching for leader changes in ${lockDir}`);
-        } catch (error: any) {
-            logger.error(`Failed to start watching: ${error.message}`);
-        }
     }
 
-    /**
-     * Stop watching for leader changes
-     */
     stopWatching(): void {
-        if (this.watcher) {
+        // No-op: the locator keeps listening until close().
-            this.watcher.close();
-            this.watcher = null;
-            logger.debug('Stopped watching for leader changes');
-        }
     }
 
-    /**
-     * Register callback for leader changes
-     */
     onChange(callback: () => void): this {
         this.onChangeCallbacks.push(callback);
         return this;
     }
 
-    /**
-     * Notify all change callbacks
-     */
     private notifyChange(): void {
+        logger.debug('meta-core changed, invalidating cache...');
         for (const callback of this.onChangeCallbacks) {
             try {
                 callback();
@@ -290,18 +250,23 @@ export class LeaderClient {
         }
     }
 
-    /**
-     * Get cached leader info (without re-reading file)
-     */
     getCachedLeaderInfo(): LeaderLockInfo | null {
         return this.leaderInfo;
     }
 
-    /**
+    /** Neighbours for the nav menu (one row per service name). */
-     * Clean up resources
+    getNeighbors(): MeshNeighbor[] {
-     */
+        return this.locator.getNeighbors();
+    }
+
+    /** This service's own announce, so the menu can show itself. */
+    self(): MeshNeighbor {
+        return this.locator.self();
+    }
+
     close(): void {
-        this.stopWatching();
         this.onChangeCallbacks = [];
+        void this.locator.stop();
+        this.started = false;
     }
 }

packages/meta-fuse-core/src/kv/ServiceRegistration.ts

@@ -1,211 +0,0 @@
-/**
- * Service Registration using shared filesystem
- *
- * Each service registers itself in /meta-core/services/{service-name}-{hostname}.json
- * with its base URL, status, and heartbeat timestamp.
- *
- * Service discovery is centralized in meta-core - this class only handles registration.
- * For service discovery, use the /api/services endpoint (proxied to meta-core via nginx).
- *
- * Each service must call start() to register itself and begin heartbeat updates.
- * meta-core runs a cleanup process that removes services with stale heartbeats.
- */
-
-import { promises as fs } from 'fs';
-import { hostname } from 'os';
-import { Logger } from 'tslog';
-import type { ServiceInfo } from './IKVClient.js';
-
-const logger = new Logger({ name: 'ServiceRegistration' });
-
-interface ServiceRegistrationConfig {
-    /** Path to META_CORE_VOLUME (e.g., /meta-core) */
-    metaCorePath: string;
-
-    /** Service name */
-    serviceName: string;
-
-    /** Base URL for the service */
-    apiUrl: string;
-
-    /** Heartbeat interval in ms (default: 30000) */
-    heartbeatInterval?: number;
-
-    /** Stale threshold in ms (default: 60000) */
-    staleThreshold?: number;
-}
-
-export class ServiceRegistration {
-    private config: ServiceRegistrationConfig;
-    private servicesDir: string;
-    private serviceFilePath: string;
-    private heartbeatTimer: NodeJS.Timeout | null = null;
-    private isShuttingDown = false;
-    private isStarted = false;
-    private currentHostname: string;
-
-    constructor(config: ServiceRegistrationConfig) {
-        this.config = {
-            heartbeatInterval: 30000,
-            staleThreshold: 60000,
-            ...config
-        };
-
-        this.currentHostname = hostname();
-        this.servicesDir = `${this.config.metaCorePath}/services`;
-        // Use hostname-based file naming
-        this.serviceFilePath = `${this.servicesDir}/${this.config.serviceName}-${this.currentHostname}.json`;
-    }
-
-    /**
-     * Ensure services directory exists
-     */
-    private async ensureServicesDir(): Promise<void> {
-        await fs.mkdir(this.servicesDir, { recursive: true });
-    }
-
-    /**
-     * Build service info for this service
-     */
-    private buildServiceInfo(status: ServiceInfo['status']): ServiceInfo {
-        return {
-            name: this.config.serviceName,
-            hostname: this.currentHostname,
-            baseUrl: this.config.apiUrl,
-            status,
-            lastHeartbeat: new Date().toISOString()
-        };
-    }
-
-    /**
-     * Register this service by writing service info to the shared filesystem.
-     * meta-core's cleanup process monitors these files and removes stale entries.
-     */
-    async register(): Promise<void> {
-        await this.ensureServicesDir();
-
-        const info = this.buildServiceInfo('running');
-        await fs.writeFile(this.serviceFilePath, JSON.stringify(info, null, 2));
-
-        logger.info(`Registered ${this.config.serviceName}-${this.currentHostname}`);
-    }
-
-    /**
-     * Update service status
-     */
-    async updateStatus(status: ServiceInfo['status']): Promise<void> {
-        try {
-            const content = await fs.readFile(this.serviceFilePath, 'utf-8');
-            const info = JSON.parse(content) as ServiceInfo;
-
-            info.status = status;
-            info.lastHeartbeat = new Date().toISOString();
-
-            await fs.writeFile(this.serviceFilePath, JSON.stringify(info, null, 2));
-        } catch (error) {
-            logger.error('Failed to update status:', error);
-        }
-    }
-
-    /**
-     * Send heartbeat (update lastHeartbeat timestamp)
-     */
-    async heartbeat(): Promise<void> {
-        try {
-            const content = await fs.readFile(this.serviceFilePath, 'utf-8');
-            const info = JSON.parse(content) as ServiceInfo;
-
-            info.lastHeartbeat = new Date().toISOString();
-
-            await fs.writeFile(this.serviceFilePath, JSON.stringify(info, null, 2));
-        } catch (error: any) {
-            // If file was deleted, re-register
-            if (error.code === 'ENOENT') {
-                await this.register();
-            } else {
-                logger.error('Heartbeat failed:', error);
-            }
-        }
-    }
-
-    /**
-     * Start heartbeat loop
-     */
-    startHeartbeat(): void {
-        this.heartbeatTimer = setInterval(async () => {
-            if (this.isShuttingDown) return;
-            await this.heartbeat();
-        }, this.config.heartbeatInterval);
-    }
-
-    /**
-     * Stop heartbeat loop
-     */
-    stopHeartbeat(): void {
-        if (this.heartbeatTimer) {
-            clearInterval(this.heartbeatTimer);
-            this.heartbeatTimer = null;
-        }
-    }
-
-    /**
-     * Unregister this service (on shutdown)
-     */
-    async unregister(): Promise<void> {
-        this.isShuttingDown = true;
-        this.stopHeartbeat();
-
-        try {
-            // Remove the service file
-            await fs.unlink(this.serviceFilePath);
-            logger.info(`Unregistered ${this.config.serviceName}-${this.currentHostname}`);
-        } catch (error: any) {
-            if (error.code !== 'ENOENT') {
-                logger.error('Failed to unregister:', error);
-            }
-        }
-    }
-
-    // ========================================================================
-    // Lifecycle
-    // ========================================================================
-
-    /**
-     * Full startup sequence: register service and start heartbeat loop.
-     */
-    async start(): Promise<void> {
-        if (this.isStarted) return;
-
-        await this.register();
-        this.startHeartbeat();
-        this.isStarted = true;
-
-        logger.info(`Started ${this.config.serviceName} at ${this.config.apiUrl}`);
-    }
-
-    /**
-     * Full shutdown sequence
-     */
-    async stop(): Promise<void> {
-        if (!this.isStarted) return;
-
-        await this.unregister();
-        this.isStarted = false;
-    }
-
-    // ========================================================================
-    // Getters
-    // ========================================================================
-
-    getServiceFilePath(): string {
-        return this.serviceFilePath;
-    }
-
-    getServicesDir(): string {
-        return this.servicesDir;
-    }
-
-    getIsStarted(): boolean {
-        return this.isStarted;
-    }
-}

packages/meta-fuse-ui/src/components/ServiceNav.tsx

@@ -1,165 +1,54 @@
-import { useState, useEffect } from 'react';
+import { useEffect } from 'react';
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore -- plain ES module, no .d.ts; imported for its side effect
+// of defining the custom element.
+import '../meta-service-menu.js';
 
-interface ServiceInfo {
+/**
-  name: string;
+ * ServiceNav — the neighbouring meta-* services, as a burger menu.
-  hostname: string;
+ *
-  baseUrl: string;
+ * Since meta-discovery v1 this is a thin wrapper around <meta-service-menu>,
-  status: string;
+ * a framework-free custom element shared by every meta-* UI (see
-  lastHeartbeat: string;
+ * scripts/check-mirrors.sh). The old implementation was ~165 lines of React
-}
+ * that existed in four near-identical copies and polled meta-core's
+ * /api/services; the element polls this service's own /api/neighbors instead,
+ * so the nav still renders when meta-core is down.
+ *
+ * The element lives in shadow DOM and cannot see this app's CSS variables, so
+ * the four --mm-nav-* tokens below map our palette onto it.
+ */
 
-interface ServicesResponse {
+declare global {
-  services: ServiceInfo[];
+    // eslint-disable-next-line @typescript-eslint/no-namespace
-  current: string;
+    namespace JSX {
-}
+        interface IntrinsicElements {
-
+            'meta-service-menu': React.DetailedHTMLProps<
-const serviceIcons: Record<string, string> = {
+                React.HTMLAttributes<HTMLElement>,
-  'meta-sort': '📁',
+                HTMLElement
-  'meta-fuse': '🗂️',
+            > & { current?: string; endpoint?: string; label?: string };
-  'meta-stremio': '🎬',
+        }
-  'meta-core': '⚙️',
+    }
-  'meta-dup': '🔍',
-  'meta-orbit': '🌐',
-  'default': '📦'
-};
-
-function formatServiceName(name: string): string {
-  return name.split('-').map(word =>
-    word.charAt(0).toUpperCase() + word.slice(1)
-  ).join(' ');
 }
 
 function ServiceNav() {
-  const [services, setServices] = useState<ServiceInfo[]>([]);
+    useEffect(() => {
-  const [loading, setLoading] = useState(true);
+        // Import above is for the side effect of defining the element; this
-  const currentService = 'meta-fuse';
+        // keeps bundlers from tree-shaking it away in production builds.
+    }, []);
 
-  useEffect(() => {
+    return (
-    const fetchServices = async () => {
+        <>
-      try {
+            <meta-service-menu current="meta-fuse" />
-        const response = await fetch('/api/services');
+            <style>{`
-        if (response.ok) {
+                meta-service-menu {
-          const data: ServicesResponse = await response.json();
+                    --mm-nav-fg: var(--text-primary, #e0e0e0);
-          setServices(data.services || []);
+                    --mm-nav-bg: var(--bg-tertiary, var(--bg-secondary, #1a1a2e));
-        }
+                    --mm-nav-border: var(--border-color, rgba(255,255,255,0.14));
-      } catch (error) {
+                    --mm-nav-accent: var(--accent-primary, #4ecdc4);
-        console.error('Failed to fetch services:', error);
-      } finally {
-        setLoading(false);
-      }
-    };
-
-    fetchServices();
-    const interval = setInterval(fetchServices, 30000);
-    return () => clearInterval(interval);
-  }, []);
-
-  if (loading) return null;
-
-  const sortedServices = [...services].sort((a, b) => a.name.localeCompare(b.name));
-
-  if (sortedServices.length === 0) return null;
-
-  return (
-    <nav className="services-nav">
-      <span className="services-nav-label">Services:</span>
-      <div className="services-nav-items">
-        {sortedServices.map(service => {
-          const icon = serviceIcons[service.name] || serviceIcons.default;
-          const isActive = service.name === currentService;
-          return (
-            <a
-              key={service.name}
-              href={isActive ? '#' : service.baseUrl}
-              className={`service-link${isActive ? ' active' : ''}`}
-              onClick={(e) => {
-                e.preventDefault();
-                if (!isActive) {
-                  window.location.href = service.baseUrl;
                 }
-              }}
+            `}</style>
-            >
+        </>
-              <span className="service-icon">{icon}</span>
+    );
-              <span>{formatServiceName(service.name)}</span>
-              <span className="service-status"></span>
-            </a>
-          );
-        })}
-      </div>
-
-      <style>{`
-        .services-nav {
-          background: var(--bg-secondary, #12121a);
-          border-radius: 12px;
-          padding: 0.5rem;
-          margin-bottom: 1.5rem;
-          display: flex;
-          align-items: center;
-          gap: 0.5rem;
-          flex-wrap: wrap;
-          border: 1px solid var(--border-color, #2a2a3a);
-        }
-
-        .services-nav-label {
-          color: var(--text-secondary, #a0a0a0);
-          font-size: 0.85rem;
-          padding: 0.5rem 0.75rem;
-          white-space: nowrap;
-        }
-
-        .services-nav-items {
-          display: flex;
-          gap: 0.5rem;
-          flex-wrap: wrap;
-        }
-
-        .service-link {
-          display: inline-flex;
-          align-items: center;
-          gap: 0.4rem;
-          padding: 0.5rem 1rem;
-          border-radius: 8px;
-          text-decoration: none;
-          font-size: 0.9rem;
-          font-weight: 500;
-          transition: all 0.2s;
-          color: var(--text-primary, #e0e0e0);
-          background: var(--bg-tertiary, #1a1a2a);
-          border: 1px solid var(--border-color, #2a2a3a);
-        }
-
-        .service-link:hover {
-          background: var(--border-color, #2a2a3a);
-          border-color: rgba(78, 205, 196, 0.5);
-          text-decoration: none;
-        }
-
-        .service-link.active {
-          background: linear-gradient(135deg, rgba(78, 205, 196, 0.2), rgba(68, 160, 141, 0.2));
-          border-color: rgba(78, 205, 196, 0.5);
-        }
-
-        .service-link .service-icon {
-          font-size: 1.1rem;
-        }
-
-        .service-link .service-status {
-          width: 6px;
-          height: 6px;
-          border-radius: 50%;
-          background: var(--accent-primary, #4ecdc4);
-          margin-left: 0.25rem;
-        }
-
-        @media (max-width: 600px) {
-          .services-nav {
-            flex-direction: column;
-            align-items: flex-start;
-          }
-        }
-      `}</style>
-    </nav>
-  );
 }
 
 export default ServiceNav;

packages/meta-fuse-ui/src/meta-service-menu.js

@@ -0,0 +1,303 @@
+/**
+ * <meta-service-menu> — the neighbouring meta-* services, as a burger menu.
+ *
+ * Replaces the eight divergent "services bar" implementations (four copies of
+ * a React `ServiceNav.tsx`, two mirrored `services.js`, two bespoke inline
+ * ones) with a single framework-free custom element. It drops into the React
+ * dashboards as a plain tag — no React dependency — and into the vanilla UIs
+ * as an ES module.
+ *
+ * Data comes from the host service's own `GET /api/neighbors`, same-origin.
+ * Never cross-origin: the dev stack's self-signed certs and the OIDC redirects
+ * make a fetch to a neighbour a dead end. Links are plain navigations.
+ *
+ * ⚠ MIRRORED FILE. Byte-identical copies live in every meta-* UI tree; see
+ * `scripts/check-mirrors.sh`. Edit one → edit all.
+ *
+ * Shadow DOM is not optional here. The eight UIs use four incompatible token
+ * vocabularies, and two of them define *different colours under the same
+ * names* (`--bg-secondary` is #12121a in meta-sort, #16213e in meta-core,
+ * #161b22 in meta-dup). meta-search and meta-share are also the only
+ * light-mode-capable UIs, so a hardcoded dark palette would break them.
+ * The element therefore styles itself from four tokens with dark defaults:
+ *
+ *     --mm-nav-fg, --mm-nav-bg, --mm-nav-border, --mm-nav-accent
+ *
+ * Each host maps its own variables onto those, e.g.
+ *     meta-service-menu { --mm-nav-bg: var(--bg-secondary); }
+ *
+ * Attributes:
+ *   current   name of the host service, so it can be marked and not linked
+ *   endpoint  override the default "/api/neighbors"
+ *   label     button tooltip (default "Services")
+ *
+ * Property:
+ *   rewriteUrl  optional (name, url, neighbour) => url, for hosts that must
+ *               translate internal hostnames into browser-reachable ones
+ *               (meta-gateway does this for its dev/prod split).
+ */
+
+const ICONS = {
+  "meta-core": "⚙️",
+  "meta-sort": "📁",
+  "meta-fuse": "🗂️",
+  "meta-stremio": "🎬",
+  "meta-dup": "🔍",
+  "meta-search": "🔎",
+  "meta-share": "🔗",
+  "meta-gateway": "🌉",
+  "meta-watch": "📺",
+  "meta-listen": "🎧",
+  "meta-read": "📖",
+};
+const DEFAULT_ICON = "📦";
+const POLL_MS = 30000;
+
+function titleCase(name) {
+  return String(name || "")
+    .split("-")
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+const TEMPLATE = `
+<style>
+  :host {
+    --_fg: var(--mm-nav-fg, #e8eaed);
+    --_bg: var(--mm-nav-bg, #1a1a2e);
+    --_border: var(--mm-nav-border, rgba(255, 255, 255, 0.14));
+    --_accent: var(--mm-nav-accent, #4ecdc4);
+    position: relative;
+    display: inline-block;
+    font-family: inherit;
+    font-size: 14px;
+    line-height: 1.4;
+  }
+  button.trigger {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.4rem;
+    width: 2.1rem;
+    height: 2.1rem;
+    padding: 0;
+    cursor: pointer;
+    color: var(--_fg);
+    background: transparent;
+    border: 1px solid var(--_border);
+    border-radius: 8px;
+    font: inherit;
+    transition: border-color 0.15s, background 0.15s;
+  }
+  button.trigger:hover { border-color: var(--_accent); }
+  button.trigger:focus-visible {
+    outline: 2px solid var(--_accent);
+    outline-offset: 2px;
+  }
+  button.trigger[aria-expanded="true"] { border-color: var(--_accent); }
+  .bars { display: block; width: 15px; }
+  .bars span {
+    display: block;
+    height: 2px;
+    margin: 3px 0;
+    border-radius: 2px;
+    background: currentColor;
+  }
+  .panel {
+    position: absolute;
+    top: calc(100% + 6px);
+    right: 0;
+    z-index: 1000;
+    min-width: 13rem;
+    max-height: 70vh;
+    overflow-y: auto;
+    padding: 0.3rem;
+    background: var(--_bg);
+    border: 1px solid var(--_border);
+    border-radius: 10px;
+    box-shadow: 0 10px 30px rgba(0, 0, 0, 0.35);
+  }
+  .panel[hidden] { display: none; }
+  a.item, .item {
+    display: flex;
+    align-items: center;
+    gap: 0.55rem;
+    padding: 0.45rem 0.6rem;
+    border-radius: 6px;
+    color: var(--_fg);
+    text-decoration: none;
+    white-space: nowrap;
+  }
+  a.item:hover { background: color-mix(in srgb, var(--_accent) 18%, transparent); }
+  .item.active { color: var(--_accent); font-weight: 600; cursor: default; }
+  .item.dead { opacity: 0.55; cursor: not-allowed; }
+  .icon { font-size: 1rem; line-height: 1; }
+  .dot {
+    width: 6px;
+    height: 6px;
+    margin-left: auto;
+    border-radius: 50%;
+    background: var(--_accent);
+  }
+  .empty {
+    padding: 0.6rem;
+    opacity: 0.7;
+    font-size: 0.85em;
+    white-space: nowrap;
+  }
+  /* Respect a host that opts out of motion. */
+  @media (prefers-reduced-motion: reduce) {
+    button.trigger { transition: none; }
+  }
+</style>
+<button class="trigger" type="button" aria-haspopup="menu" aria-expanded="false">
+  <span class="bars" aria-hidden="true"><span></span><span></span><span></span></span>
+</button>
+<div class="panel" role="menu" hidden></div>
+`;
+
+class MetaServiceMenu extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: "open" });
+    this.shadowRoot.innerHTML = TEMPLATE;
+    this._btn = this.shadowRoot.querySelector("button.trigger");
+    this._panel = this.shadowRoot.querySelector(".panel");
+    this._neighbors = [];
+    this._timer = null;
+    this._open = false;
+
+    this._onDocClick = (e) => {
+      if (!this._open) return;
+      if (e.composedPath().includes(this)) return;
+      this._setOpen(false);
+    };
+    this._onKey = (e) => {
+      if (e.key === "Escape" && this._open) {
+        this._setOpen(false);
+        this._btn.focus();
+      }
+    };
+  }
+
+  connectedCallback() {
+    this._btn.title = this.getAttribute("label") || "Services";
+    this._btn.setAttribute("aria-label", this._btn.title);
+    this._btn.addEventListener("click", () => this._setOpen(!this._open));
+    document.addEventListener("click", this._onDocClick);
+    document.addEventListener("keydown", this._onKey);
+
+    this.refresh();
+    this._timer = setInterval(() => this.refresh(), POLL_MS);
+  }
+
+  disconnectedCallback() {
+    if (this._timer) clearInterval(this._timer);
+    this._timer = null;
+    document.removeEventListener("click", this._onDocClick);
+    document.removeEventListener("keydown", this._onKey);
+  }
+
+  get endpoint() {
+    return this.getAttribute("endpoint") || "/api/neighbors";
+  }
+
+  get current() {
+    return this.getAttribute("current") || "";
+  }
+
+  async refresh() {
+    try {
+      const res = await fetch(this.endpoint, {
+        headers: { Accept: "application/json" },
+      });
+      if (!res.ok) throw new Error(String(res.status));
+      const data = await res.json();
+      // `services` is the legacy alias some backends still emit.
+      this._neighbors = data.neighbors || data.services || [];
+    } catch {
+      // Silent: the menu is navigation, not a health indicator. Keep whatever
+      // we last had rather than blanking the list on one failed poll.
+    }
+    this._render();
+  }
+
+  _setOpen(open) {
+    this._open = open;
+    this._panel.hidden = !open;
+    this._btn.setAttribute("aria-expanded", String(open));
+    if (open) this.refresh();
+  }
+
+  _render() {
+    const panel = this._panel;
+    panel.textContent = "";
+
+    const seen = new Set();
+    const rows = [];
+    for (const n of this._neighbors) {
+      const name = n.name || "";
+      if (!name || seen.has(name)) continue;
+      seen.add(name);
+      rows.push(n);
+    }
+    // Always show the host itself, even before its own echo comes back.
+    if (this.current && !seen.has(this.current)) {
+      rows.push({ name: this.current, baseUrl: "" });
+    }
+    rows.sort((a, b) => String(a.name).localeCompare(String(b.name)));
+
+    if (rows.length === 0) {
+      const empty = document.createElement("div");
+      empty.className = "empty";
+      empty.textContent = "No services found";
+      panel.appendChild(empty);
+      return;
+    }
+
+    for (const n of rows) {
+      const isActive = n.name === this.current;
+      let url = n.baseUrl || "";
+      if (typeof this.rewriteUrl === "function") {
+        try {
+          url = this.rewriteUrl(n.name, url, n) || "";
+        } catch {
+          /* a bad hook must not blank the menu */
+        }
+      }
+
+      // A neighbour with no reachable URL is shown but not linked — better
+      // than a link that goes nowhere.
+      const el = document.createElement(isActive || !url ? "span" : "a");
+      el.className =
+        "item" + (isActive ? " active" : "") + (!isActive && !url ? " dead" : "");
+      if (el.tagName === "A") {
+        el.href = url;
+        el.setAttribute("role", "menuitem");
+      }
+      if (!isActive && !url) el.title = "No reachable URL announced";
+
+      const icon = document.createElement("span");
+      icon.className = "icon";
+      icon.textContent = ICONS[n.name] || DEFAULT_ICON;
+
+      const label = document.createElement("span");
+      label.textContent = titleCase(n.name);
+
+      el.append(icon, label);
+      if (n.status === "running" || isActive) {
+        const dot = document.createElement("span");
+        dot.className = "dot";
+        dot.title = n.status || "running";
+        el.appendChild(dot);
+      }
+      panel.appendChild(el);
+    }
+  }
+}
+
+if (!customElements.get("meta-service-menu")) {
+  customElements.define("meta-service-menu", MetaServiceMenu);
+}
+
+export default MetaServiceMenu;