@livedesk/hub 0.1.55 → 0.1.57

package/src/server.js

@@ -14,7 +14,7 @@ import {
   RemoteClipboardContractError,
   normalizeRemoteClipboardRequest
 } from './remote-clipboard-contract.mjs';
-import { createHubConsoleRelay } from './console-relay.js';
+import { createHubConsoleDirect } from './console-direct.js';
 import {
   buildImmutableRemoteFramePacket,
   createRemoteFramePacketMetrics,
@@ -211,20 +211,23 @@ let inputClientSeq = 0;
 let audioClientSeq = 0;
 let liveDeskUpdateManager = null;
 let hubTransferJobs = null;
-let hubConsoleRelay = null;
+let hubConsoleDirect = null;
 const HUB_HOST_TARGET_LEASE_MS = Math.max(5000, readPositiveIntegerEnv('LIVEDESK_HOST_TARGET_LEASE_MS', 60_000));
 const HUB_HOST_TARGET_RENEW_MS = Math.max(1000, Math.min(
   readPositiveIntegerEnv('LIVEDESK_HOST_TARGET_RENEW_MS', 20_000),
   Math.max(1000, HUB_HOST_TARGET_LEASE_MS - 1000)
 ));
 const HUB_ACCESS_TOKEN_REFRESH_SKEW_MS = 90_000;
-const hubWakeBaseUrl = String(process.env.LIVEDESK_WAKE_URL || 'https://livedesk-wake.lovecrdm.workers.dev').trim();
-const hubConsoleRelayBaseUrl = String(
-  process.env.LIVEDESK_CONSOLE_RELAY_URL
-  || (process.env.LIVEDESK_TEST_MODE === '1' || process.env.LIVEDESK_AUTH_TEST_MODE === '1'
-    ? 'off'
-    : 'https://livedesk-wake.lovecrdm.workers.dev')
-).trim();
+const hubWakeBaseUrl = String(process.env.LIVEDESK_WAKE_URL || 'https://livedesk-wake.lovecrdm.workers.dev').trim();
+const hubConsoleDirectSignalBaseUrl = String(
+  process.env.LIVEDESK_CONSOLE_SIGNAL_URL
+  || (process.env.LIVEDESK_TEST_MODE === '1' || process.env.LIVEDESK_AUTH_TEST_MODE === '1'
+    ? 'off'
+    : hubWakeBaseUrl)
+).trim();
+const hubConsoleDirectStunUrls = String(
+  process.env.LIVEDESK_CONSOLE_STUN_URLS || 'stun:stun.cloudflare.com:3478'
+).trim();
 const HUB_WAKE_NOTIFY_RETRY_MS = 60_000;
 let hubHostTargetRenewTimer = null;
 let hubHostTargetRenewInFlight = false;
@@ -1394,13 +1397,13 @@ const hubSharedFolders = createHubSharedFolders({
 
 const app = express();
 const httpServer = createServer(app);
-hubConsoleRelay = createHubConsoleRelay({
-  url: runtimeRole === 'hub' ? hubConsoleRelayBaseUrl : 'off',
-  deviceId: runtimeDeviceId,
-  httpBaseUrl: `http://127.0.0.1:${httpPort}`,
-  getAccessToken: () => getRuntimeAccessToken(),
-  logger: console
-});
+hubConsoleDirect = createHubConsoleDirect({
+  url: runtimeRole === 'hub' ? hubConsoleDirectSignalBaseUrl : 'off',
+  deviceId: runtimeDeviceId,
+  httpBaseUrl: `http://127.0.0.1:${httpPort}`,
+  stunUrls: hubConsoleDirectStunUrls,
+  getAccessToken: () => getRuntimeAccessToken()
+});
 const httpConnections = new Set();
 const frameWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
 const atlasWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
@@ -4342,27 +4345,35 @@ app.post('/api/settings/agent/summary', async (req, res) => {
   }
 });
 
-app.get('/api/remote/status', (_req, res) => {
-  noStore(res);
-  if (runtimeRole !== 'hub') {
+app.get('/api/remote/status', async (_req, res) => {
+  noStore(res);
+  if (runtimeRole !== 'hub') {
     res.status(403).json({ ok: false, error: 'role-not-allowed' });
     return;
   }
-  const secretStatus = remoteHub.getStatus({ includeSecrets: true });
-  res.json({
-    ...remoteHub.getStatus({ includeSecrets: false }),
-    pairingPin: secretStatus.pairingPin,
-    product: 'LiveDesk',
-    runtimeRole,
-    deviceId: runtimeDeviceId,
-    deviceName: runtimeDeviceName,
-    roleSource: runtimeRoleSource,
-    agentPackage: '@livedesk/client',
-    consoleRelay: hubConsoleRelay?.inspect() || { enabled: false, state: 'starting' },
-    frameLanes: snapshotFrameLaneResourceHealth(),
-    update: getLiveDeskUpdateStatus()
-  });
-});
+  try {
+    const [secretStatus, wallPreferences] = await Promise.all([
+      Promise.resolve(remoteHub.getStatus({ includeSecrets: true })),
+      liveDeskSettingsStore.getWallPreferencesRecord()
+    ]);
+    res.json({
+      ...remoteHub.getStatus({ includeSecrets: false }),
+      pairingPin: secretStatus.pairingPin,
+      product: 'LiveDesk',
+      runtimeRole,
+      deviceId: runtimeDeviceId,
+      deviceName: runtimeDeviceName,
+      roleSource: runtimeRoleSource,
+      agentPackage: '@livedesk/client',
+      wallPreferences,
+      consoleDirect: hubConsoleDirect?.inspect() || { enabled: false, state: 'starting' },
+      frameLanes: snapshotFrameLaneResourceHealth(),
+      update: getLiveDeskUpdateStatus()
+    });
+  } catch (error) {
+    res.status(500).json({ ok: false, error: error instanceof Error ? error.message : String(error) });
+  }
+});
 
 app.post('/api/remote/diagnostics/transport/start', async (req, res) => {
   noStore(res);
@@ -4593,7 +4604,7 @@ app.post('/api/auth/session', async (req, res) => {
       }
     });
     if (runtimeRole === 'hub') {
-      hubConsoleRelay?.refresh();
+      hubConsoleDirect?.refresh();
       scheduleAuthenticatedHubHostTargetPublication('session-received');
     }
   } catch (error) {
@@ -4619,7 +4630,7 @@ function getHubHostTargetLeaseStatus() {
     authenticated: Boolean(runtimeAccessToken),
     timerActive: Boolean(hubHostTargetRenewTimer),
     wake: { ...hubWakeNotificationState },
-    consoleRelay: hubConsoleRelay?.inspect() || { enabled: false, state: 'starting' }
+    consoleDirect: hubConsoleDirect?.inspect() || { enabled: false, state: 'starting' }
   };
 }
 
@@ -4905,10 +4916,11 @@ function scheduleAuthenticatedHubHostTargetPublication(reason = 'session-receive
 
 app.delete('/api/auth/session', async (req, res) => {
   noStore(res);
-  const hostTarget = runtimeRole === 'hub'
-    ? await clearHubHostTarget('logout')
-    : { ok: true, active: false };
-  clearRuntimeSession();
+  const hostTarget = runtimeRole === 'hub'
+    ? await clearHubHostTarget('logout')
+    : { ok: true, active: false };
+  clearRuntimeSession();
+  hubConsoleDirect?.close();
   res.setHeader('Set-Cookie', clearHubUiSessionCookie({ secure: isSecureHubHttpRequest(req) }));
   res.json({ ok: true, authenticated: false, role: runtimeRole, hostTarget });
 });
@@ -4926,7 +4938,7 @@ app.get('/api/hub/status', (_req, res) => {
     deviceName: runtimeDeviceName,
     roleSource: runtimeRoleSource,
     runtimeStarted: true,
-    consoleRelay: hubConsoleRelay?.inspect() || { enabled: false, state: 'starting' },
+    consoleDirect: hubConsoleDirect?.inspect() || { enabled: false, state: 'starting' },
     hostTargetLease: getHubHostTargetLeaseStatus(),
     update: getLiveDeskUpdateStatus()
   });
@@ -6010,7 +6022,7 @@ httpServer.listen(httpPort, httpHost, () => {
   console.log(`[VuvoDesk Hub] Version ${managerVersion}`);
   console.log(`[VuvoDesk Hub] HTTP API http://${httpHost}:${httpPort}`);
   console.log(`[VuvoDesk Hub] Client endpoint ${status.agentEndpoint} pair=${status.pairTokenPreview}`);
-  hubConsoleRelay?.start();
+  hubConsoleDirect?.start();
 });
 
 const roleWatchTimer = runtimeRole === 'hub'
@@ -6094,7 +6106,7 @@ function shutdownHub(signal) {
     if (roleWatchTimer) clearInterval(roleWatchTimer);
     clearInterval(browserWebSocketHeartbeatTimer);
     runSynchronousShutdownStep('update manager close', () => liveDeskUpdateManager?.close());
-    runSynchronousShutdownStep('mobile console relay close', () => hubConsoleRelay?.close());
+    runSynchronousShutdownStep('mobile console direct close', () => hubConsoleDirect?.close());
     atlasClients.clear();
     runSynchronousShutdownStep('shared folder close', () => hubSharedFolders.close());
 

package/src/settings/settings-schema.js

@@ -46,9 +46,11 @@ export const DEFAULT_LIVEDESK_SETTINGS = Object.freeze({
     rememberLastMonitor: true,
     keepControlReadyBetweenPages: true
   },
-  wall: {
-    performanceMode: 'auto',
-    autoStart: true,
+  wall: {
+    performanceMode: 'auto',
+    cadence: 'fast',
+    viewScale: 100,
+    autoStart: true,
     connectedOnly: false,
     keepEmptySlots: true,
     showDeviceStatus: true,
@@ -110,9 +112,10 @@ export const DEFAULT_LIVEDESK_SETTINGS = Object.freeze({
   }
 });
 
-const ENUMS = {
+const ENUMS = {
   accessMode: new Set(['trusted-only', 'ask-every-time', 'view-only', 'block-remote-access']),
-  performanceMode: new Set(['auto', 'responsive', 'quality', 'custom']),
+  performanceMode: new Set(['auto', 'responsive', 'quality', 'custom']),
+  wallCadence: new Set(['slow', 'fast']),
   permissionMode: new Set(['ask', 'safe-auto', 'full-access', 'custom']),
   wallFrameMode: new Set(['auto', 'mode2-lzo', 'mode3-h264-hw', 'mode4-h264-atlas']),
   controlFrameMode: new Set(['mode3-h264-hw', 'mode5-lzo-delta']),
@@ -169,9 +172,11 @@ const RULES = {
   control: {
     ...bools(['allowKeyboardMouse', 'allowSystemShortcuts', 'allowClipboardText', 'allowRemoteRestart', 'reconnectAfterRemoteRestart', 'allowSwitchingMonitors', 'showConnectionToolbar', 'showRemoteCursor', 'openControlOnDoubleClick', 'startRemoteAudioWithControl', 'fitRemoteScreen', 'rememberLastMonitor', 'keepControlReadyBetweenPages'])
   },
-  wall: {
-    performanceMode: { type: 'enum', values: ENUMS.performanceMode },
-    ...bools(['autoStart', 'connectedOnly', 'keepEmptySlots', 'showDeviceStatus', 'showPerformanceDetails', 'pauseHiddenTiles', 'reduceWhenHidden', 'autoAdjustTileQuality', 'rememberDevicePositions'])
+  wall: {
+    performanceMode: { type: 'enum', values: ENUMS.performanceMode },
+    cadence: { type: 'enum', values: ENUMS.wallCadence },
+    viewScale: { type: 'number', min: 0, max: 100 },
+    ...bools(['autoStart', 'connectedOnly', 'keepEmptySlots', 'showDeviceStatus', 'showPerformanceDetails', 'pauseHiddenTiles', 'reduceWhenHidden', 'autoAdjustTileQuality', 'rememberDevicePositions'])
   },
   filesAudio: {
     ...bools(['allowFileTransfer', 'allowFolderSync', 'askBeforeReceivingFiles', 'openReceivedFolder', 'notifyTransferComplete', 'allowOverwrite', 'allowRemoteAudio', 'startAudioMuted', 'rememberVolume', 'automaticallyRecoverAudio', 'showAudioTroubleshooting', 'rollingBufferEnabled', 'includeRemoteCursor']),

package/src/settings/settings-store.js

@@ -40,12 +40,22 @@ export class LiveDeskSettingsStore {
     return structuredClone(this.record);
   }
 
-  getCached() {
-    if (!this.record) return DEFAULT_LIVEDESK_SETTINGS;
-    return { ...this.record.settings, revision: this.record.revision };
-  }
-
-  async get() {
+  getCached() {
+    if (!this.record) return DEFAULT_LIVEDESK_SETTINGS;
+    return { ...this.record.settings, revision: this.record.revision };
+  }
+
+  async getWallPreferencesRecord() {
+    if (!this.record) await this.getRecord();
+    return {
+      revision: this.record.revision,
+      updatedAt: this.record.updatedAt,
+      cadence: this.record.settings.wall.cadence,
+      viewScale: this.record.settings.wall.viewScale
+    };
+  }
+
+  async get() {
     return publicSettings((await this.getRecord()).settings);
   }
 

package/src/console-relay.js

@@ -1,424 +0,0 @@
-import WebSocket from 'ws';
-
-const DEFAULT_CONSOLE_RELAY_URL = 'https://livedesk-wake.lovecrdm.workers.dev';
-const DEFAULT_RETRY_DELAYS_MS = [1_000, 2_000, 5_000, 10_000, 20_000];
-const MAX_CHANNELS = 32;
-const MAX_HTTP_REQUEST_BYTES = 1024 * 1024;
-const MAX_HTTP_RESPONSE_BYTES = 4 * 1024 * 1024;
-const MAX_RELAY_BUFFERED_BYTES = 4 * 1024 * 1024;
-const HTTP_TIMEOUT_MS = 15_000;
-const BINARY_HEADER_BYTES = 73;
-const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-
-function normalizeRelayUrl(value) {
-  const source = String(value || DEFAULT_CONSOLE_RELAY_URL).trim();
-  if (!source || /^(off|disabled|none)$/i.test(source)) return '';
-  try {
-    const url = new URL(source);
-    url.protocol = url.protocol === 'http:' ? 'ws:' : url.protocol === 'https:' ? 'wss:' : url.protocol;
-    url.pathname = '/v1/hub';
-    url.search = '';
-    url.hash = '';
-    return url;
-  } catch {
-    return null;
-  }
-}
-
-function allowedHttpRequest(method, path) {
-  if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) return false;
-  const pathname = String(path || '').split('?')[0];
-  if (pathname === '/api/health'
-    || pathname === '/api/runtime/status'
-    || pathname === '/api/runtime/restart'
-    || pathname === '/api/auth/status'
-    || pathname === '/api/remote/status'
-    || pathname === '/api/hub/status'
-    || pathname === '/api/update/status'
-    || pathname === '/api/update/apply') {
-    return true;
-  }
-  if (/^\/api\/settings(?:\/|$)/.test(pathname)
-    || /^\/api\/captures(?:\/|$)/.test(pathname)
-    || /^\/api\/capture-sessions(?:\/|$)/.test(pathname)
-    || /^\/api\/remote\/devices(?:\/|$)/.test(pathname)
-    || /^\/api\/remote\/frames$/.test(pathname)
-    || /^\/api\/remote\/filesystem(?:\/|$)/.test(pathname)
-    || /^\/api\/remote\/files(?:\/|$)/.test(pathname)
-    || /^\/api\/remote\/tasks(?:\/|$)/.test(pathname)
-    || /^\/api\/remote\/license(?:\/sync)?$/.test(pathname)) {
-    return pathname !== '/api/remote/registry-credentials'
-      && pathname !== '/api/remote/pairing-pin'
-      && !pathname.startsWith('/api/remote/host-target')
-      && !pathname.startsWith('/api/remote/synthetic');
-  }
-  return false;
-}
-
-function allowedWebSocketPath(path) {
-  const pathname = String(path || '').split('?')[0];
-  return pathname === '/api/remote/frames/ws'
-    || pathname === '/api/remote/atlas/ws'
-    || pathname === '/api/remote/input/ws'
-    || pathname === '/api/remote/audio/ws';
-}
-
-function channelKey(consoleId, channelId) {
-  return `${consoleId}\n${channelId}`;
-}
-
-function parseMessage(raw) {
-  try {
-    return JSON.parse(String(raw || ''));
-  } catch {
-    return null;
-  }
-}
-
-function safeContentHeaders(headers) {
-  const result = {};
-  for (const name of ['accept', 'content-type', 'if-match', 'range']) {
-    const value = headers && typeof headers === 'object' ? headers[name] || headers[name.toUpperCase()] : '';
-    if (value) result[name] = String(value).slice(0, 512);
-  }
-  return result;
-}
-
-export function createHubConsoleRelay(options = {}) {
-  const relayUrl = normalizeRelayUrl(options.url);
-  const deviceId = String(options.deviceId || '').trim();
-  const httpBaseUrl = String(options.httpBaseUrl || '').replace(/\/+$/, '');
-  const WebSocketImpl = options.WebSocketImpl || WebSocket;
-  const fetchImpl = options.fetchImpl || globalThis.fetch;
-  const getAccessToken = typeof options.getAccessToken === 'function'
-    ? options.getAccessToken
-    : async () => String(options.accessToken || '').trim();
-  const logger = options.logger || console;
-  const retryDelaysMs = options.retryDelaysMs || DEFAULT_RETRY_DELAYS_MS;
-  const localSockets = new Map();
-  const pendingHttp = new Set();
-  let relaySocket = null;
-  let retryTimer = null;
-  let retryAttempt = 0;
-  let generation = 0;
-  let stopped = true;
-  let state = relayUrl ? 'idle' : 'disabled';
-  let lastConnectedAt = '';
-  let lastError = relayUrl instanceof URL ? '' : relayUrl === '' ? '' : 'invalid-relay-url';
-  let droppedBinaryMessages = 0;
-
-  const sendRelay = (payload, bypassBackpressure = false) => {
-    if (!relaySocket || relaySocket.readyState !== WebSocketImpl.OPEN) return false;
-    if (!bypassBackpressure
-      && Number(relaySocket.bufferedAmount || 0) > MAX_RELAY_BUFFERED_BYTES) return false;
-    relaySocket.send(typeof payload === 'string' || Buffer.isBuffer(payload) ? payload : JSON.stringify(payload));
-    return true;
-  };
-
-  const sendError = (consoleId, channelId, error, type = 'relay-error') => {
-    sendRelay({ type, consoleId, channelId, error: String(error || 'console-relay-error').slice(0, 240) });
-  };
-
-  const closeLocalSocket = (key, code = 1000, reason = 'console-channel-closed') => {
-    const socket = localSockets.get(key);
-    if (!socket) return;
-    localSockets.delete(key);
-    try { socket.close(code, reason); } catch { /* exact socket is already closed */ }
-    try { socket.terminate?.(); } catch { /* exact socket is already closed */ }
-  };
-
-  const closeConsoleChannels = consoleId => {
-    for (const key of [...localSockets.keys()]) {
-      if (key.startsWith(`${consoleId}\n`)) closeLocalSocket(key, 1001, 'console-detached');
-    }
-  };
-
-  const closeAllLocalSockets = reason => {
-    for (const key of [...localSockets.keys()]) closeLocalSocket(key, 1012, reason);
-  };
-
-  const handleHttpRequest = async payload => {
-    const consoleId = String(payload?.consoleId || '');
-    const channelId = String(payload?.channelId || '');
-    const method = String(payload?.method || 'GET').toUpperCase();
-    const path = String(payload?.path || '');
-    if (!UUID_PATTERN.test(consoleId) || !UUID_PATTERN.test(channelId) || !allowedHttpRequest(method, path)) {
-      sendError(consoleId, channelId, 'console-route-not-allowed', 'http-response');
-      return;
-    }
-    if (pendingHttp.size >= MAX_CHANNELS) {
-      sendError(consoleId, channelId, 'console-http-capacity-reached', 'http-response');
-      return;
-    }
-    let body;
-    try {
-      body = payload.bodyBase64 ? Buffer.from(String(payload.bodyBase64), 'base64') : undefined;
-    } catch {
-      sendError(consoleId, channelId, 'invalid-console-http-body', 'http-response');
-      return;
-    }
-    if (body && body.byteLength > MAX_HTTP_REQUEST_BYTES) {
-      sendError(consoleId, channelId, 'console-http-body-too-large', 'http-response');
-      return;
-    }
-
-    const requestKey = channelKey(consoleId, channelId);
-    pendingHttp.add(requestKey);
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(new Error('console-http-timeout')), HTTP_TIMEOUT_MS);
-    timeout.unref?.();
-    try {
-      const response = await fetchImpl(`${httpBaseUrl}${path}`, {
-        method,
-        headers: safeContentHeaders(payload.headers),
-        body: ['GET', 'HEAD'].includes(method) ? undefined : body,
-        signal: controller.signal
-      });
-      const responseBytes = Buffer.from(await response.arrayBuffer());
-      if (responseBytes.byteLength > MAX_HTTP_RESPONSE_BYTES) {
-        sendError(consoleId, channelId, 'console-http-response-too-large', 'http-response');
-        return;
-      }
-      sendRelay({
-        type: 'http-response',
-        consoleId,
-        channelId,
-        status: response.status,
-        statusText: response.statusText,
-        headers: {
-          'content-type': String(response.headers.get('content-type') || '').slice(0, 256),
-          'content-range': String(response.headers.get('content-range') || '').slice(0, 256)
-        },
-        bodyBase64: responseBytes.toString('base64')
-      });
-    } catch (error) {
-      sendError(consoleId, channelId, error instanceof Error ? error.message : error, 'http-response');
-    } finally {
-      clearTimeout(timeout);
-      pendingHttp.delete(requestKey);
-    }
-  };
-
-  const handleWebSocketOpen = payload => {
-    const consoleId = String(payload?.consoleId || '');
-    const channelId = String(payload?.channelId || '');
-    const path = String(payload?.path || '');
-    if (!UUID_PATTERN.test(consoleId) || !UUID_PATTERN.test(channelId) || !allowedWebSocketPath(path)) {
-      sendError(consoleId, channelId, 'console-websocket-route-not-allowed', 'ws-error');
-      return;
-    }
-    if (localSockets.size >= MAX_CHANNELS) {
-      sendError(consoleId, channelId, 'console-websocket-capacity-reached', 'ws-error');
-      return;
-    }
-    const key = channelKey(consoleId, channelId);
-    closeLocalSocket(key, 1000, 'console-channel-replaced');
-    const localUrl = new URL(path, httpBaseUrl);
-    localUrl.protocol = localUrl.protocol === 'https:' ? 'wss:' : 'ws:';
-    let socket;
-    try {
-      socket = new WebSocketImpl(localUrl, { perMessageDeflate: false });
-    } catch (error) {
-      sendError(consoleId, channelId, error instanceof Error ? error.message : error, 'ws-error');
-      return;
-    }
-    localSockets.set(key, socket);
-    socket.once('open', () => {
-      if (localSockets.get(key) !== socket) return;
-      sendRelay({ type: 'ws-opened', consoleId, channelId });
-    });
-    socket.on('message', (data, isBinary) => {
-      if (localSockets.get(key) !== socket) return;
-      if (isBinary) {
-        if (!relaySocket || relaySocket.readyState !== WebSocketImpl.OPEN
-          || Number(relaySocket.bufferedAmount || 0) > MAX_RELAY_BUFFERED_BYTES) {
-          droppedBinaryMessages += 1;
-          closeLocalSocket(key, 1013, 'console-relay-backpressure');
-          return;
-        }
-        const header = Buffer.from(`B${consoleId}${channelId}`, 'ascii');
-        if (header.byteLength !== BINARY_HEADER_BYTES) {
-          closeLocalSocket(key, 1008, 'invalid-relay-channel-id');
-          return;
-        }
-        relaySocket.send(Buffer.concat([header, Buffer.from(data)]));
-        return;
-      }
-      sendRelay({ type: 'ws-message', consoleId, channelId, data: String(data), binary: false });
-    });
-    socket.once('close', (code, reason) => {
-      if (localSockets.get(key) === socket) localSockets.delete(key);
-      const closeReason = String(reason || '').slice(0, 120);
-      // Do not silently punch a hole in an H.264 GOP. A tiny terminal control
-      // message is allowed behind the already-bounded video backlog so the
-      // browser replaces only this logical lane and starts again on a key.
-      sendRelay(
-        { type: 'ws-closed', consoleId, channelId, code, reason: closeReason },
-        closeReason === 'console-relay-backpressure'
-      );
-    });
-    socket.once('error', error => {
-      sendError(consoleId, channelId, error instanceof Error ? error.message : error, 'ws-error');
-    });
-  };
-
-  const handleMessage = raw => {
-    const payload = parseMessage(raw);
-    if (!payload?.type) return;
-    if (payload.type === 'relay-ready') {
-      state = 'connected';
-      lastConnectedAt = new Date().toISOString();
-      lastError = '';
-      return;
-    }
-    if (payload.type === 'console-detached') {
-      closeConsoleChannels(String(payload.consoleId || ''));
-      return;
-    }
-    if (payload.type === 'http-request') {
-      void handleHttpRequest(payload);
-      return;
-    }
-    if (payload.type === 'ws-open') {
-      handleWebSocketOpen(payload);
-      return;
-    }
-    const key = channelKey(String(payload.consoleId || ''), String(payload.channelId || ''));
-    const socket = localSockets.get(key);
-    if (!socket) return;
-    if (payload.type === 'ws-send' && socket.readyState === WebSocketImpl.OPEN) {
-      const data = String(payload.data || '');
-      if (Buffer.byteLength(data) <= MAX_HTTP_REQUEST_BYTES) socket.send(data);
-    } else if (payload.type === 'ws-close') {
-      closeLocalSocket(key, Number(payload.code || 1000), String(payload.reason || 'console-request').slice(0, 120));
-    }
-  };
-
-  const scheduleReconnect = connect => {
-    if (stopped || retryTimer || !(relayUrl instanceof URL)) return;
-    const delayMs = retryDelaysMs[Math.min(retryAttempt, retryDelaysMs.length - 1)];
-    retryAttempt += 1;
-    state = 'waiting-retry';
-    retryTimer = setTimeout(() => {
-      retryTimer = null;
-      void connect();
-    }, delayMs);
-    retryTimer.unref?.();
-  };
-
-  const connect = async () => {
-    if (stopped || !(relayUrl instanceof URL) || !deviceId) return;
-    const ownerGeneration = ++generation;
-    state = 'connecting';
-    let accessToken = '';
-    try {
-      accessToken = String(await getAccessToken() || '').trim();
-    } catch (error) {
-      lastError = error instanceof Error ? error.message : String(error);
-    }
-    if (stopped || ownerGeneration !== generation) return;
-    if (!accessToken) {
-      lastError = 'hub-session-required';
-      scheduleReconnect(connect);
-      return;
-    }
-    const url = new URL(relayUrl);
-    url.searchParams.set('deviceId', deviceId);
-    let socket;
-    try {
-      socket = new WebSocketImpl(url, {
-        headers: { Authorization: `Bearer ${accessToken}` },
-        perMessageDeflate: false
-      });
-    } catch (error) {
-      lastError = error instanceof Error ? error.message : String(error);
-      scheduleReconnect(connect);
-      return;
-    }
-    if (stopped || ownerGeneration !== generation) {
-      try { socket.terminate?.(); } catch { /* stale connect is already gone */ }
-      return;
-    }
-    relaySocket = socket;
-    socket.once('open', () => {
-      if (relaySocket !== socket || ownerGeneration !== generation || stopped) return;
-      retryAttempt = 0;
-      state = 'authenticating';
-    });
-    socket.on('message', raw => {
-      if (relaySocket === socket && ownerGeneration === generation && !stopped) handleMessage(raw);
-    });
-    socket.once('close', () => {
-      if (relaySocket === socket) relaySocket = null;
-      if (ownerGeneration !== generation || stopped) return;
-      state = 'disconnected';
-      closeAllLocalSockets('relay-disconnected');
-      scheduleReconnect(connect);
-    });
-    socket.once('error', error => {
-      lastError = error instanceof Error ? error.message : String(error);
-      try { socket.terminate?.(); } catch { /* close handler owns retry */ }
-    });
-  };
-
-  const start = () => {
-    if (!stopped || !(relayUrl instanceof URL) || !deviceId) return;
-    stopped = false;
-    void connect();
-  };
-
-  const refresh = () => {
-    if (stopped) {
-      start();
-      return;
-    }
-    generation += 1;
-    if (retryTimer) {
-      clearTimeout(retryTimer);
-      retryTimer = null;
-    }
-    const socket = relaySocket;
-    relaySocket = null;
-    try { socket?.terminate?.(); } catch { /* refresh owns the exact socket */ }
-    closeAllLocalSockets('relay-refresh');
-    void connect();
-  };
-
-  const close = () => {
-    if (stopped) return;
-    stopped = true;
-    generation += 1;
-    if (retryTimer) clearTimeout(retryTimer);
-    retryTimer = null;
-    closeAllLocalSockets('hub-shutdown');
-    const socket = relaySocket;
-    relaySocket = null;
-    try { socket?.close(1001, 'hub-shutdown'); } catch { /* exact socket is already closed */ }
-    try { socket?.terminate?.(); } catch { /* exact socket is already closed */ }
-    state = relayUrl ? 'closed' : 'disabled';
-  };
-
-  return {
-    start,
-    refresh,
-    close,
-    inspect: () => ({
-      enabled: relayUrl instanceof URL && Boolean(deviceId),
-      state,
-      connected: state === 'connected',
-      localWebSocketChannels: localSockets.size,
-      pendingHttpRequests: pendingHttp.size,
-      droppedBinaryMessages,
-      lastConnectedAt,
-      lastError
-    })
-  };
-}
-
-export const consoleRelayContract = Object.freeze({
-  maxChannels: MAX_CHANNELS,
-  maxHttpRequestBytes: MAX_HTTP_REQUEST_BYTES,
-  maxHttpResponseBytes: MAX_HTTP_RESPONSE_BYTES,
-  maxBufferedBytes: MAX_RELAY_BUFFERED_BYTES,
-  binaryHeaderBytes: BINARY_HEADER_BYTES
-});