@celestia-island/plana-rpc-client 0.1.3 → 0.1.6

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@celestia-island/plana-rpc-client",
-  "version": "0.1.3",
+  "version": "0.1.6",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/celestia-island/plana"
+  },
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/client.ts

@@ -39,11 +39,38 @@ export interface RpcNotification {
   params: unknown;
 }
 
+/**
+ * Heartbeat wire protocol (P59-W4). The default preserves shittim-chest's
+ * shape; alternative backends (e.g. erp.celestia.world) speak a different
+ * one and can now adopt the shared client without forking it.
+ */
+export interface HeartbeatProtocol {
+  /**
+   * - "notify" (default): fire-and-forget notification `method`; the server
+   *   answers with an `ackMethod` notification.
+   * - "request": JSON-RPC request `method` (default "ping"); the beat
+   *   completes when the matching id-response arrives.
+   */
+  mode?: "notify" | "request";
+  /** Notify mode: method to send (default "Base.Heartbeat"). */
+  method?: string;
+  /** Notify mode: ack method to listen for (default "Base.HeartbeatAck"). */
+  ackMethod?: string;
+  /**
+   * Server-initiated pings to echo: when a notification named `on`
+   * arrives, reply with a notification named `reply` (e.g. erp's
+   * server "server.ping" → reply "client.pong" to satisfy its idle
+   * timer). Echoes are fire-and-forget.
+   */
+  serverPings?: Array<{ on: string; reply: string }>;
+}
+
 export interface RpcClientOpts {
   baseUrl: string;
   rpcPath?: string;
   getToken: () => string | null;
   onAuthLost?: () => void;
+  heartbeatProtocol?: HeartbeatProtocol;
   /**
    * Called when a request is rejected with 401: return a fresh access token
    * to retry the request once (the callback owns persisting it), or null to
@@ -56,6 +83,14 @@ export interface RpcClientOpts {
   sseMaxRetries?: number;
   pollIntervalMs?: number;
   local?: boolean;
+  /**
+   * Probe-only mode: without a token the client performs a single anonymous
+   * `/api/health` handshake, reports `connected` once it succeeds, then
+   * immediately tears the connection down. Used by status bars to show
+   * backend health for anonymous visitors without holding a long-lived
+   * connection (abuse prevention).
+   */
+  probeOnly?: boolean;
 }
 
 type NotificationHandler = (n: RpcNotification) => void;
@@ -116,6 +151,20 @@ export class RpcClient {
   #hbAckTimer: ReturnType<typeof setTimeout> | null = null;
   #hbSentAt: number | null = null;
   #latencyMs: number | null = null;
+  /** Resolved heartbeat protocol (defaults preserve the chest shape). */
+  readonly #hbProtocol: Required<Pick<HeartbeatProtocol, "mode" | "method" | "ackMethod">> & { serverPings: Map<string, string> };
+  /** Pending request-mode heartbeat ids → completion callbacks. */
+  #hbRequests = new Map<string, () => void>();
+  /** Established-connection loss recovery: delayed re-entry into the
+   *  progressive rounds (exponential backoff, 1.5× → 30s cap + jitter).
+   *  `connect()`/`forceReconnect()` reset it so manual retries are fresh. */
+  #reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  #reconnectDelay = 1_000;
+  #reconnectArmed = false;
+  /** True while a progressive session was entered by the recovery loop —
+   *  exhausting its rounds re-arms recovery instead of parking on
+   *  "failed" (only FIRST-EVER connection attempts park on failed). */
+  #fromRecovery = false;
 
   #notifHandlers = new Set<NotificationHandler>();
   #binaryHandlers = new Set<BinaryHandler>();
@@ -125,6 +174,7 @@ export class RpcClient {
 
   #state: ConnectionState = "disconnected";
   #retryCount = 0;
+  #probeOnly = false;
 
   get state(): ConnectionState { return this.#state; }
   get connected(): boolean { return this.#ws?.readyState === WebSocket.OPEN; }
@@ -140,11 +190,19 @@ export class RpcClient {
     this.#onAuthLost = opts.onAuthLost;
     this.#refreshToken = opts.refreshToken;
     this.#heartbeatInterval = opts.heartbeatInterval ?? HB_INTERVAL;
+    const proto = opts.heartbeatProtocol ?? {};
+    this.#hbProtocol = {
+      mode: proto.mode ?? "notify",
+      method: proto.method ?? (proto.mode === "request" ? "ping" : "Base.Heartbeat"),
+      ackMethod: proto.ackMethod ?? "Base.HeartbeatAck",
+      serverPings: new Map((proto.serverPings ?? []).map(({ on, reply }) => [on, reply])),
+    };
     this.#heartbeatTimeout = opts.heartbeatTimeout ?? HB_TIMEOUT;
     this.#callTimeoutMs = opts.callTimeoutMs ?? CALL_TIMEOUT;
     this.#pollIntervalMs = opts.pollIntervalMs ?? POLL_INTERVAL;
     this.#sessionId = randomSessionId();
     this.#local = opts.local ?? isLocalhost(this.#baseUrl);
+    this.#probeOnly = opts.probeOnly ?? false;
   }
 
   // ── main API ────────────────────────────────────────────
@@ -174,7 +232,12 @@ export class RpcClient {
   connect(): void {
     this.#disposed = false;
     this.#retryCount = 0;
-    if (this.#local) {
+    this.#cancelRecovery();
+    this.#fromRecovery = false;
+    this.#bindResumeTriggers();
+    if (this.#probeOnly) {
+      this.#probeHealthOnce();
+    } else if (this.#local) {
       this.#tier = "local";
       console.info("[RpcClient:local] detected localhost, using direct HTTP");
       this.#setState("connected");
@@ -185,14 +248,26 @@ export class RpcClient {
 
   async disconnect(): Promise<void> {
     this.#disposed = true;
+    this.#cancelRecovery();
     this.#teardownAll();
+    this.#unbindResumeTriggers();
     this.#setState("disconnected");
   }
 
   forceReconnect(): void {
-    if (this.#disposed) return;
+    if (!this.#revivable) return;
     this.#retryCount = 0;
+    this.#cancelRecovery();
+    this.#fromRecovery = false;
     this.#teardownAll();
+    if (this.#probeOnly) {
+      // Anonymous clients park `disposed` right after their one-shot
+      // health probe succeeds; without this revive the status-bar tap
+      // on a red light was a permanent no-op (nothing ever re-probed).
+      this.#disposed = false;
+      this.#probeHealthOnce();
+      return;
+    }
     if (this.#local) {
       this.#tier = "local";
       this.#setState("connected");
@@ -201,6 +276,62 @@ export class RpcClient {
     }
   }
 
+  // ═══════════════════════════════════════════════════════════
+  // Resume triggers: phones suspend timers in the background, so the
+  // recovery loop (exponential backoff up to 30s + jitter) can sit
+  // frozen while the page is hidden and the light stays red long after
+  // connectivity returned. Re-entering the foreground or the network
+  // coming back online forces a prompt reconnect instead of waiting
+  // out a stale countdown.
+  // ═══════════════════════════════════════════════════════════
+
+  #resumeBound = false;
+  #lastResumeAttemptAt = 0;
+
+  /** A host-killed client (logout disconnect()) must never revive;
+   *  a disposed probeOnly client (its one-shot probe parked it) may. */
+  get #revivable(): boolean {
+    return !this.#disposed || this.#probeOnly;
+  }
+
+  readonly #onVisibilityChange = (): void => {
+    if (typeof document === "undefined" || document.visibilityState !== "visible") return;
+    this.#onResumeTrigger();
+  };
+
+  readonly #onOnline = (): void => {
+    // `online` can fire while the page is still hidden (network restored
+    // in the background); leave that resume to visibilitychange so a
+    // foreground return within the debounce window still gets its own
+    // fresh attempt.
+    if (typeof document === "undefined" || document.visibilityState !== "visible") return;
+    this.#onResumeTrigger();
+  };
+
+  #onResumeTrigger(): void {
+    if (!this.#revivable) return;
+    if (this.#state === "connected" || this.#state === "connecting") return;
+    const now = Date.now();
+    // Debounce: visibility flips and online events can burst together.
+    if (now - this.#lastResumeAttemptAt < 5_000) return;
+    this.#lastResumeAttemptAt = now;
+    this.forceReconnect();
+  }
+
+  #bindResumeTriggers(): void {
+    if (this.#resumeBound || typeof window === "undefined" || typeof document === "undefined") return;
+    this.#resumeBound = true;
+    document.addEventListener("visibilitychange", this.#onVisibilityChange);
+    window.addEventListener("online", this.#onOnline);
+  }
+
+  #unbindResumeTriggers(): void {
+    if (!this.#resumeBound) return;
+    this.#resumeBound = false;
+    document.removeEventListener("visibilitychange", this.#onVisibilityChange);
+    window.removeEventListener("online", this.#onOnline);
+  }
+
   on(event: "notification", handler: NotificationHandler): () => void;
   on(event: "binary", handler: BinaryHandler): () => void;
   on(event: "state", handler: StateHandler): () => void;
@@ -258,12 +389,21 @@ export class RpcClient {
         this.#tier = tier;
         if (tier === "ws") this.#startHeartbeat();
         else { this.#eventSource?.close(); this.#eventSource = null; if (this.#ws) { this.#cleanupWs(this.#ws, this.#wsGen); } }
-        this.#setState("connected");
+        // A fresh success also ends any recovery cycle with a clean
+        // backoff for the next drop.
+        if (this.#reconnectArmed || this.#reconnectDelay !== 1_000) this.#cancelRecovery();
+        this.#setState("connected", undefined, this.#tier);
         return;
       }
     }
 
     this.#tier = "poll";
+    if (this.#fromRecovery && !this.#disposed) {
+      // Recovery session exhausted its rounds — keep the loop alive.
+      this.#fromRecovery = false;
+      this.#scheduleRecovery();
+      return;
+    }
     this.#setState("failed", undefined, "poll", undefined, undefined);
   }
 
@@ -307,10 +447,17 @@ export class RpcClient {
       const token = this.#getToken();
       if (!token) { resolve(false); return; }
 
+      // Join the query correctly: rpcPath may already carry a query
+      // string (e.g. "?workspace=<id>" — every webui consumer passes
+      // one). Appending "?token=" to such a path produced
+      // "/api/rpc?workspace=X?token=Y": the server read the token as
+      // part of the workspace value, the upgrade failed with 401, and
+      // the WS tier never connected at all.
+      const tokenJoin = this.#rpcPath.includes("?") ? "&token=" : "?token=";
       const wsUrl =
         this.#baseUrl.replace(/^http/, "ws") +
         this.#rpcPath +
-        "?token=" +
+        tokenJoin +
         encodeURIComponent(token);
       const gen = ++this.#wsGen;
       const ws = new WebSocket(wsUrl);
@@ -341,14 +488,21 @@ export class RpcClient {
       };
 
       ws.onclose = () => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        this.#cleanupWs(ws, gen);
-        if (this.#tier === "ws" && !this.#disposed) {
-          this.#setState("disconnected");
+        if (!settled) {
+          // Attempt-phase close (never opened / failed mid-handshake).
+          settled = true;
+          clearTimeout(timer);
+          this.#cleanupWs(ws, gen);
+          resolve(false);
+          return;
+        }
+        // Established connection lost (server idle-close, heartbeat
+        // timeout's close(4000), network drop): the progressive rounds
+        // only retry before the FIRST success, so without this a single
+        // dropped socket left consumers on a stale green light forever.
+        if (this.#ws === ws && this.#tier === "ws" && !this.#disposed) {
+          this.#scheduleRecovery();
         }
-        resolve(false);
       };
 
       ws.onmessage = (event) => {
@@ -367,22 +521,42 @@ export class RpcClient {
         let data: any;
         try { data = JSON.parse(event.data); } catch { return; }
 
-        if (data.method === "Base.HeartbeatAck") {
-          this.#resetHeartbeatTimeout();
-          if (this.#hbSentAt !== null) {
-            this.#latencyMs = Math.max(0, Math.round(performance.now() - this.#hbSentAt));
-            this.#hbSentAt = null;
-            this.#emitLatency();
-          }
-          this.#heartbeatHandlers.forEach((h) => h());
+        // Upstreams may answer unknown methods with a literal `null`
+        // body (JSON.parse("null") → null). Reading `.method` off it
+        // throws, and the uncaught TypeError is treated as a boot
+        // failure by the shell's fatal-fallback, freezing the whole
+        // page behind a full-screen overlay. Only JSON objects carry
+        // JSON-RPC semantics — drop everything else (null, scalars,
+        // arrays) without touching `.method`/`.id`.
+        if (typeof data !== "object" || data === null) return;
+
+        if (data.method === this.#hbProtocol.ackMethod) {
+          this.#completeHeartbeat();
           return;
         }
 
         if (data.method && data.id === undefined) {
+          // Server-initiated ping → echo the configured reply (if any)
+          // BEFORE fanning the notification out, so idle timers on the
+          // server side are satisfied even if a consumer throws.
+          const echo = this.#hbProtocol.serverPings.get(data.method);
+          if (echo !== undefined) {
+            try { ws.send(JSON.stringify({ jsonrpc: "2.0", method: echo })); } catch { /* closing */ }
+          }
           this.#notifHandlers.forEach((h) => h({ method: data.method, params: data.params }));
           return;
         }
 
+        if (data.id !== undefined) {
+          // Request-mode heartbeat completion (id-correlated response).
+          const hbDone = this.#hbRequests.get(String(data.id));
+          if (hbDone) {
+            this.#hbRequests.delete(String(data.id));
+            hbDone();
+            return;
+          }
+        }
+
         if (data.id !== undefined) {
           const id = String(data.id);
           const entry = this.#pending.get(id);
@@ -484,7 +658,7 @@ export class RpcClient {
           if (data.method && data.params !== undefined) {
             this.#notifHandlers.forEach((h) => h({ method: data.method, params: data.params }));
           }
-          if (data.method === "Base.HeartbeatAck") {
+          if (data.method === this.#hbProtocol.ackMethod) {
             this.#heartbeatHandlers.forEach((h) => h());
           }
         } catch { /* ignore */ }
@@ -528,6 +702,94 @@ export class RpcClient {
     this.#progressiveConnect();
   }
 
+  // ═══════════════════════════════════════════════════════════
+  // Anonymous health probe (probeOnly)
+  // ═══════════════════════════════════════════════════════════
+
+  async #probeHealthOnce(): Promise<void> {
+    // Preferred: one long-connection attempt over the real transport path.
+    // The server replies with a success ack and actively closes the socket,
+    // so the probe validates the WS upgrade + roundtrip without holding an
+    // anonymous connection open (no connection storm on login pages).
+    if (await this.#probeWsOnce(5000)) {
+      this.#tier = "ws";
+      this.#setState("connected");
+      this.#disposed = true;
+      this.#teardownAll();
+      this.#setState("disconnected");
+      return;
+    }
+    // Fallback: plain HTTP GET on the health endpoint.
+    try {
+      const url = this.#baseUrl + "/api/health";
+      const resp = await fetch(url, {
+        method: "GET",
+        credentials: "include",
+        signal: AbortSignal.timeout(5000),
+      });
+      if (!resp.ok) {
+        this.#setState("failed");
+        return;
+      }
+      this.#tier = "poll";
+      this.#setState("connected");
+      // Handshake succeeded — tear down immediately. The status bar only
+      // needs to know the backend is reachable; keeping a connection open
+      // for anonymous visitors would invite abuse.
+      this.#disposed = true;
+      this.#teardownAll();
+      this.#setState("disconnected");
+    } catch {
+      this.#setState("failed");
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════
+  // Anonymous WS probe (single long-connection attempt)
+  // ═══════════════════════════════════════════════════════════
+
+  async #probeWsOnce(timeoutMs: number): Promise<boolean> {
+    return new Promise((resolve) => {
+      let ws: WebSocket | null = null;
+      try {
+        ws = new WebSocket(this.#baseUrl.replace(/^http/, "ws") + this.#rpcPath);
+      } catch {
+        resolve(false);
+        return;
+      }
+      let settled = false;
+      const finish = (ok: boolean): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        try { ws?.close(); } catch { /* ignore */ }
+        resolve(ok);
+      };
+      const timer = setTimeout(() => finish(false), timeoutMs);
+
+      ws.onopen = () => {
+        try {
+          ws?.send(
+            JSON.stringify({
+              jsonrpc: "2.0",
+              id: "probe",
+              method: "system.probe",
+              params: {},
+            }),
+          );
+        } catch {
+          finish(false);
+        }
+      };
+      ws.onmessage = () => finish(true);
+      ws.onerror = () => finish(false);
+      ws.onclose = () => {
+        clearTimeout(timer);
+        if (!settled) resolve(false);
+      };
+    });
+  }
+
   // ═══════════════════════════════════════════════════════════
   // HTTP POST (used by all tiers)
   // ═══════════════════════════════════════════════════════════
@@ -589,6 +851,17 @@ export class RpcClient {
   // Heartbeat (WS only)
   // ═══════════════════════════════════════════════════════════
 
+  /** Shared beat completion: latency bookkeeping + fan-out. */
+  #completeHeartbeat(): void {
+    this.#resetHeartbeatTimeout();
+    if (this.#hbSentAt !== null) {
+      this.#latencyMs = Math.max(0, Math.round(performance.now() - this.#hbSentAt));
+      this.#hbSentAt = null;
+      this.#emitLatency();
+    }
+    this.#heartbeatHandlers.forEach((h) => h());
+  }
+
   #startHeartbeat(): void {
     this.#clearHeartbeat();
     this.#hbTimer = setInterval(() => {
@@ -596,10 +869,19 @@ export class RpcClient {
       if (this.#hbAckTimer) return;
       try {
         this.#hbSentAt = performance.now();
-        this.#ws.send(JSON.stringify({ jsonrpc: "2.0", method: "Base.Heartbeat" }));
+        if (this.#hbProtocol.mode === "request") {
+          // Request mode: a JSON-RPC request whose id-correlated response
+          // completes the beat (matched in the WS onmessage handler).
+          const id = `hb-${(++this.#idCounter).toString(36)}`;
+          this.#hbRequests.set(id, () => this.#completeHeartbeat());
+          this.#ws.send(JSON.stringify({ jsonrpc: "2.0", method: this.#hbProtocol.method, id }));
+        } else {
+          this.#ws.send(JSON.stringify({ jsonrpc: "2.0", method: this.#hbProtocol.method }));
+        }
         this.#hbAckTimer = setTimeout(() => {
           this.#hbAckTimer = null;
           this.#hbSentAt = null;
+          this.#hbRequests.clear();
           if (this.#ws && this.#ws.readyState === WebSocket.OPEN) {
             this.#ws.close(4000, "heartbeat timeout");
           }
@@ -626,6 +908,7 @@ export class RpcClient {
   #clearHeartbeat(): void {
     if (this.#hbTimer) { clearInterval(this.#hbTimer); this.#hbTimer = null; }
     this.#resetHeartbeatTimeout();
+    this.#hbRequests.clear();
   }
 
   // ═══════════════════════════════════════════════════════════
@@ -633,6 +916,7 @@ export class RpcClient {
   // ═══════════════════════════════════════════════════════════
 
   #teardownAll(): void {
+    this.#cancelRecovery();
     this.#eventSource?.close();
     this.#eventSource = null;
     if (this.#pollTimer) { clearInterval(this.#pollTimer); this.#pollTimer = null; }
@@ -652,6 +936,46 @@ export class RpcClient {
     this.#rejectAllPending("disconnected");
   }
 
+  /** Recovery loop for an established connection that dropped: surface
+   *  `reconnecting` with a countdown, then re-enter the progressive
+   *  rounds after an exponential backoff. Backoff resets on a successful
+   *  reconnect (see the connected branch of #progressiveConnect). */
+  #scheduleRecovery(): void {
+    if (this.#disposed || this.#reconnectArmed) return;
+    this.#reconnectArmed = true;
+    this.#clearHeartbeat();
+    this.#retryCount = MAX_RETRIES; // exhaust the "rounds" so a failure re-arms recovery, not the loop
+    const jitter = Math.random() * this.#reconnectDelay * 0.5;
+    const delay = this.#reconnectDelay + jitter;
+    this.#reconnectDelay = Math.min(this.#reconnectDelay * 1.5, 30_000);
+    let remaining = Math.ceil(delay / 1000);
+    this.#setState("reconnecting", remaining);
+    const tick = setInterval(() => {
+      remaining -= 1;
+      if (remaining >= 0 && !this.#disposed) {
+        this.#setState("reconnecting", remaining);
+      }
+    }, 1_000);
+    this.#reconnectTimer = setTimeout(() => {
+      clearInterval(tick);
+      this.#reconnectTimer = null;
+      this.#reconnectArmed = false;
+      if (!this.#disposed) {
+        this.#fromRecovery = true;
+        this.#progressiveConnect();
+      }
+    }, delay);
+  }
+
+  #cancelRecovery(): void {
+    this.#reconnectArmed = false;
+    this.#reconnectDelay = 1_000;
+    if (this.#reconnectTimer !== null) {
+      clearTimeout(this.#reconnectTimer);
+      this.#reconnectTimer = null;
+    }
+  }
+
   #setState(state: ConnectionState, retryIn?: number, transportTier?: string, attemptNumber?: number, countdown?: number): void {
     this.#state = state;
     this.#stateHandlers.forEach((h) => h({

package/src/index.ts

@@ -2,8 +2,13 @@ export { RpcClient } from "./client.js";
 export { RpcError } from "./client.js";
 export type {
   RpcClientOpts,
+  HeartbeatProtocol,
   ConnectionState,
   ConnectionStateEvent,
   RpcErrorKind,
   RpcNotification,
 } from "./client.js";
+
+// Relay extension (edge side) — see docs/en/rpc/relay-profile.md.
+export { RELAY, relayMethods, RelayClient, createTauriTransport, createMemoryTransport } from "./relay.js";
+export type { RelayContext, EdgeFrame, EdgeTransport } from "./relay.js";

package/src/relay.ts

@@ -0,0 +1,153 @@
+// Relay extension — the edge (webview/UI) side.
+//
+// Mirrors `plana-rpc-client`'s Rust `relay` module and `plana-tauri`'s
+// bridge: one request/response transport function plus one notification
+// lane, canonical JSON-RPC 2.0 frames, the reserved `relay.*`
+// system-control method names, and the hop context for chains. A webview
+// picks a transport (Tauri v2 global bridge or in-memory for tests) and
+// speaks the same surface in every app.
+
+/** Reserved system-control namespace (never forwarded). */
+export const RELAY = "relay";
+
+/** Pre-standardized `relay.*` method names (see docs/en/rpc/relay-profile.md). */
+export const relayMethods = {
+  netSetProxy: "relay.net.set_proxy",
+  netConfigureEntrypoint: "relay.net.configure_entrypoint",
+  connOpen: "relay.conn.open",
+  fwdMap: "relay.fwd.map",
+  fwdList: "relay.fwd.list",
+  windowMinimize: "relay.window.minimize",
+  windowMaximizeToggle: "relay.window.maximize_toggle",
+  windowClose: "relay.window.close",
+  windowState: "relay.window.state",
+} as const;
+
+/** Per-frame relay context: hop count for the loop guard + trace. */
+export interface RelayContext {
+  hops: number;
+  via?: string[];
+}
+
+/** One edge frame: canonical JSON-RPC request members + relay extension. */
+export interface EdgeFrame {
+  method: string;
+  params?: unknown;
+  relay?: RelayContext;
+}
+
+/** The transport contract any framework adapter implements. */
+export interface EdgeTransport {
+  call(frame: EdgeFrame): Promise<unknown>;
+  /** Subscribe to the notification lane; returns an unsubscribe. */
+  listen(handler: (method: string, params?: unknown) => void): () => void;
+}
+
+/**
+ * Tauri v2 transport: `bridge_call` invoke + the `bridge_event` lane.
+ * Reads the strict v2 global shape (`__TAURI__.core.invoke`).
+ */
+export function createTauriTransport(): EdgeTransport {
+  const raw = (window as unknown as {
+    __TAURI__?: {
+      core?: { invoke?: (cmd: string, args?: Record<string, unknown>) => Promise<unknown> };
+      event?: {
+        listen?: (
+          event: string,
+          handler: (e: { payload: unknown }) => void,
+        ) => Promise<() => void>;
+      };
+    };
+  }).__TAURI__;
+  const invoke = raw?.core?.invoke;
+  const listen = raw?.event?.listen;
+  if (!invoke || !listen) {
+    throw new Error("tauri v2 global API unavailable (no withGlobalTauri shell)");
+  }
+  const subscribers = new Set<(method: string, params?: unknown) => void>();
+  let wired = false;
+  return {
+    async call(frame) {
+      return invoke("bridge_call", {
+        method: frame.method,
+        params: frame.params ?? null,
+        relay: frame.relay ?? null,
+      });
+    },
+    listen(handler) {
+      if (!wired) {
+        wired = true;
+        void listen("bridge_event", (e) => {
+          const payload = e.payload as { method?: string; params?: unknown };
+          if (payload?.method) {
+            for (const fn of subscribers) fn(payload.method, payload.params);
+          }
+        });
+      }
+      subscribers.add(handler);
+      return () => subscribers.delete(handler);
+    },
+  };
+}
+
+/** In-memory transport for tests and non-framework embedding. */
+export function createMemoryTransport(
+  far: (frame: EdgeFrame) => Promise<unknown>,
+): EdgeTransport {
+  return {
+    call: (frame) => far(frame),
+    listen: () => () => {},
+  };
+}
+
+/** The edge client every UI surface shares. */
+export class RelayClient {
+  constructor(private transport: EdgeTransport) {}
+
+  /** One request/response call; the transport owns correlation. */
+  call(method: string, params?: unknown, relay?: RelayContext): Promise<unknown> {
+    return this.transport.call({ method, params, relay });
+  }
+
+  /** Typed helpers over the standard system-control battery. */
+  setProxy(config: {
+    scheme: "http" | "https" | "socks5";
+    host: string;
+    username?: string;
+    password?: string;
+  }): Promise<unknown> {
+    return this.call(relayMethods.netSetProxy, config);
+  }
+
+  configureEntrypoint(url: string): Promise<unknown> {
+    return this.call(relayMethods.netConfigureEntrypoint, { url });
+  }
+
+  fwdMap(namespacePrefix: string, endpoint: string): Promise<unknown> {
+    return this.call(relayMethods.fwdMap, { namespacePrefix, endpoint });
+  }
+
+  fwdList(): Promise<unknown> {
+    return this.call(relayMethods.fwdList);
+  }
+
+  windowMinimize(): Promise<unknown> {
+    return this.call(relayMethods.windowMinimize);
+  }
+
+  windowMaximizeToggle(): Promise<unknown> {
+    return this.call(relayMethods.windowMaximizeToggle);
+  }
+
+  windowClose(): Promise<unknown> {
+    return this.call(relayMethods.windowClose);
+  }
+
+  windowState(): Promise<unknown> {
+    return this.call(relayMethods.windowState);
+  }
+
+  onNotification(handler: (method: string, params?: unknown) => void): () => void {
+    return this.transport.listen(handler);
+  }
+}