@livedesk/hub 0.1.0 → 0.1.1

package/src/server.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 
-import cors from 'cors';
 import express from 'express';
 import crypto from 'node:crypto';
 import { createServer } from 'node:http';
@@ -9,6 +8,11 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { WebSocketServer } from 'ws';
 import { createRemoteHub } from './remote-hub.js';
+import { Mode4AtlasSession } from './mode4-atlas.js';
+import { createHubFilesystem } from './filesystem/hub-filesystem.js';
+import { createHubTransferJobs } from './filesystem/transfer-jobs.js';
+import { createHubSharedFolders } from './filesystem/shared-folders.js';
+import { toFilesystemHttpError } from './filesystem/directory-reader.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const webDistCandidates = [
@@ -19,15 +23,173 @@ const webDistCandidates = [
 const webDistPath = webDistCandidates.find(candidate => existsSync(resolve(candidate, 'index.html'))) || webDistCandidates[webDistCandidates.length - 1];
 const webIndexPath = resolve(webDistPath, 'index.html');
 const packageInfo = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8'));
-const httpHost = process.env.LIVEDESK_HUB_HTTP_HOST || '0.0.0.0';
+const httpHost = process.env.LIVEDESK_HUB_HTTP_HOST || '127.0.0.1';
 const httpPort = Number(process.env.LIVEDESK_HUB_HTTP_PORT || process.env.PORT || 5179);
+const frameBackpressureBytes = readPositiveIntegerEnv('LIVEDESK_FRAME_WS_BACKPRESSURE_BYTES', 64 * 1024 * 1024);
+const frameClientQueuePackets = readPositiveIntegerEnv('LIVEDESK_FRAME_WS_QUEUE_PACKETS', 256);
+const frameClientDrainBudgetPackets = readPositiveIntegerEnv('LIVEDESK_FRAME_WS_DRAIN_BUDGET_PACKETS', 64);
+const mode5FrameBackpressureBytes = readPositiveIntegerEnv('LIVEDESK_MODE5_WS_BACKPRESSURE_BYTES', 2 * 1024 * 1024);
+const mode5FrameQueuePackets = readPositiveIntegerEnv('LIVEDESK_MODE5_WS_QUEUE_PACKETS', 2);
 const frameClients = new Set();
+const frameClientsByDeviceId = new Map();
+const frameWildcardClients = new Set();
+const atlasClients = new Map();
 const inputClients = new Set();
 const audioClients = new Set();
+const FREE_DEVICE_LIMIT = 5;
+const PLUS_DEVICE_LIMIT = 30;
+const LICENSE_VERIFY_MAX_AGE_MS = 6 * 60 * 60 * 1000;
+const supabaseUrl = String(process.env.LIVEDESK_SUPABASE_URL || 'https://otbyfkjxrkngvjziawki.supabase.co').replace(/\/+$/, '');
+const supabasePublishableKey = String(process.env.LIVEDESK_SUPABASE_PUBLISHABLE_KEY || 'sb_publishable_NpUs0RDJH2YnllsqTKO6TQ_1jTdSsNQ');
+const testLicensePlan = process.env.LIVEDESK_TEST_MODE === '1'
+  && ['ltd', 'pro'].includes(String(process.env.LIVEDESK_TEST_LICENSE_PLAN || '').toLowerCase())
+  ? String(process.env.LIVEDESK_TEST_LICENSE_PLAN).toLowerCase()
+  : '';
+let connectedDeviceCount = 0;
+let verifiedLicense = {
+  userId: '',
+  plan: 'free',
+  status: 'inactive',
+  expiresAt: '',
+  verifiedAt: 0
+};
 let frameClientSeq = 0;
 let inputClientSeq = 0;
 let audioClientSeq = 0;
 
+function readPositiveIntegerEnv(name, fallback) {
+  const value = Number(process.env[name]);
+  return Number.isFinite(value) && value > 0 ? Math.round(value) : fallback;
+}
+
+function handleRemoteHubEvent(type, event) {
+  if (type === 'RemoteInputApplied') {
+    for (const ws of inputClients) {
+      sendJson(ws, {
+        type: 'RemoteInputApplied',
+        ...event
+      });
+    }
+    return;
+  }
+  if (type === 'RemoteDeviceConnected' || type === 'RemoteDeviceDisconnected') {
+    connectedDeviceCount = Number(remoteHub.getStatus({ includeSecrets: false }).connectedDeviceCount || 0);
+  }
+  if (type !== 'RemoteDeviceConnected') {
+    return;
+  }
+  const deviceId = String(event?.deviceId || event?.device?.deviceId || '').trim();
+  if (!deviceId) {
+    return;
+  }
+  for (const ws of atlasClients.keys()) {
+    if (ws.readyState === 1 && ws.liveDeskAtlasDeviceIds?.has(deviceId)) {
+      startMode4AtlasInput(ws, deviceId, 'device-connected');
+    }
+  }
+  const clients = new Set([
+    ...(frameClientsByDeviceId.get(deviceId) || []),
+    ...frameWildcardClients
+  ]);
+  for (const ws of clients) {
+    if (ws.readyState === 1
+      && ws.liveDeskAutoStart
+      && (!ws.liveDeskDeviceIds?.size || ws.liveDeskDeviceIds.has(deviceId))) {
+      startFrameSubscriptionLive(ws, 'device-reconnected', deviceId);
+    }
+  }
+}
+
+function activeLicensePlan() {
+  if (testLicensePlan) {
+    return testLicensePlan;
+  }
+  const now = Date.now();
+  if (verifiedLicense.status !== 'active'
+    || now - verifiedLicense.verifiedAt > LICENSE_VERIFY_MAX_AGE_MS) {
+    return 'free';
+  }
+  const expiresAt = verifiedLicense.expiresAt ? Date.parse(verifiedLicense.expiresAt) : Number.POSITIVE_INFINITY;
+  if (Number.isFinite(expiresAt) && expiresAt <= now) {
+    return 'free';
+  }
+  return verifiedLicense.plan === 'pro' ? 'pro' : verifiedLicense.plan === 'ltd' ? 'ltd' : 'free';
+}
+
+function activeDeviceLimit() {
+  const plan = activeLicensePlan();
+  return plan === 'pro' ? Number.POSITIVE_INFINITY : plan === 'ltd' ? PLUS_DEVICE_LIMIT : FREE_DEVICE_LIMIT;
+}
+
+function hasHubFeatureAccess() {
+  return connectedDeviceCount <= activeDeviceLimit();
+}
+
+function licenseSnapshot() {
+  const plan = activeLicensePlan();
+  const limit = activeDeviceLimit();
+  return {
+    plan,
+    status: plan === 'free' ? 'free' : 'active',
+    deviceLimit: Number.isFinite(limit) ? limit : null,
+    connectedDeviceCount,
+    featureAccess: connectedDeviceCount <= limit,
+    verifiedAt: verifiedLicense.verifiedAt ? new Date(verifiedLicense.verifiedAt).toISOString() : '',
+    expiresAt: verifiedLicense.expiresAt || ''
+  };
+}
+
+async function syncVerifiedLicense(accessToken) {
+  const token = String(accessToken || '').trim();
+  if (!token) {
+    throw new Error('supabase-access-token-required');
+  }
+  const headers = {
+    apikey: supabasePublishableKey,
+    Authorization: `Bearer ${token}`,
+    Accept: 'application/json'
+  };
+  const userResponse = await fetch(`${supabaseUrl}/auth/v1/user`, { headers });
+  if (!userResponse.ok) {
+    throw new Error(`supabase-user-verification-failed:${userResponse.status}`);
+  }
+  const user = await userResponse.json();
+  const userId = String(user?.id || '').trim();
+  if (!userId) {
+    throw new Error('supabase-user-missing');
+  }
+  const query = new URLSearchParams({
+    select: 'user_id,product_key,plan,status,expires_at,updated_at',
+    user_id: `eq.${userId}`,
+    product_key: 'eq.livedesk',
+    limit: '1'
+  });
+  const entitlementResponse = await fetch(`${supabaseUrl}/rest/v1/livedesk_entitlements?${query}`, { headers });
+  if (!entitlementResponse.ok) {
+    throw new Error(`supabase-entitlement-query-failed:${entitlementResponse.status}`);
+  }
+  const rows = await entitlementResponse.json();
+  const entitlement = Array.isArray(rows) ? rows[0] : null;
+  const plan = entitlement?.plan === 'pro' ? 'pro' : entitlement?.plan === 'ltd' ? 'ltd' : 'free';
+  const status = entitlement?.status === 'active' ? 'active' : 'inactive';
+  verifiedLicense = {
+    userId,
+    plan,
+    status,
+    expiresAt: String(entitlement?.expires_at || ''),
+    verifiedAt: Date.now()
+  };
+  return licenseSnapshot();
+}
+
+function requireHubFeatureAccess(_req, res, next) {
+  if (hasHubFeatureAccess()) {
+    next();
+    return;
+  }
+  res.status(402).json({ ok: false, error: 'livedesk-plan-device-limit', license: licenseSnapshot() });
+}
+
 const remoteHub = createRemoteHub({
   managerPackage: '@livedesk/hub',
   managerVersion: packageInfo.version,
@@ -38,39 +200,125 @@ const remoteHub = createRemoteHub({
   },
   logEvent: (_scope, message) => console.log(`[LiveDesk Hub] ${message}`),
   logWarn: (_scope, message) => console.warn(`[LiveDesk Hub] ${message}`),
+  emitEvent: handleRemoteHubEvent,
   emitFrame: broadcastRemoteBinaryFrame,
   emitAudio: broadcastRemoteBinaryAudio
 });
+const hubFilesystem = createHubFilesystem();
+const hubTransferJobs = createHubTransferJobs({
+  filesystem: hubFilesystem,
+  remoteHub,
+  maxConcurrent: Number(process.env.LIVEDESK_MAX_FILE_JOBS || 2)
+});
+const hubSharedFolders = createHubSharedFolders({
+  filesystem: hubFilesystem,
+  transferJobs: hubTransferJobs,
+  remoteHub
+});
 
 const app = express();
 const httpServer = createServer(app);
-const frameWss = new WebSocketServer({ noServer: true });
-const inputWss = new WebSocketServer({ noServer: true });
-const audioWss = new WebSocketServer({ noServer: true });
+const frameWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+const atlasWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+const inputWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+const audioWss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+
+function normalizeHostname(value) {
+  return String(value || '').trim().toLowerCase().replace(/^\[|\]$/g, '');
+}
+
+function isLoopbackHostname(value) {
+  const hostname = normalizeHostname(value);
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1';
+}
+
+function isPrivateHubHostname(value) {
+  const hostname = normalizeHostname(value);
+  if (isLoopbackHostname(hostname)
+    || hostname === '0.0.0.0'
+    || hostname.startsWith('10.')
+    || hostname.startsWith('192.168.')
+    || hostname.startsWith('169.254.')
+    || hostname.startsWith('fc')
+    || hostname.startsWith('fd')
+    || hostname.startsWith('fe80:')) {
+    return true;
+  }
+  const match = /^(172)\.(\d{1,3})\./.exec(hostname);
+  return !!match && Number(match[2]) >= 16 && Number(match[2]) <= 31;
+}
+
+function isLoopbackAddress(value) {
+  const address = String(value || '').trim().toLowerCase();
+  return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
+}
+
+function requestHostname(req) {
+  try {
+    return normalizeHostname(new URL(`http://${req.headers.host || '127.0.0.1'}`).hostname);
+  } catch {
+    return '';
+  }
+}
+
+function isTrustedBrowserRequest(req) {
+  const origin = String(req.headers.origin || '').trim();
+  if (!origin) {
+    const fetchSite = String(req.headers['sec-fetch-site'] || '').toLowerCase();
+    return isLoopbackAddress(req.socket?.remoteAddress)
+      || fetchSite === 'same-origin'
+      || fetchSite === 'none';
+  }
+  try {
+    const parsed = new URL(origin);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      return false;
+    }
+    const originHost = normalizeHostname(parsed.hostname);
+    const targetHost = requestHostname(req);
+    return (originHost === targetHost && isPrivateHubHostname(targetHost))
+      || (isLoopbackHostname(originHost) && isLoopbackHostname(targetHost));
+  } catch {
+    return false;
+  }
+}
 
 app.use((req, res, next) => {
-  if (req.headers.origin) {
+  if (!isTrustedBrowserRequest(req)) {
+    res.status(403).json({ ok: false, error: 'untrusted-hub-origin' });
+    return;
+  }
+  const origin = String(req.headers.origin || '').trim();
+  if (origin) {
+    res.setHeader('Access-Control-Allow-Origin', origin);
     res.setHeader('Access-Control-Allow-Private-Network', 'true');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PATCH, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
     res.setHeader('Vary', 'Origin, Access-Control-Request-Headers, Access-Control-Request-Private-Network');
   }
+  if (req.method === 'OPTIONS') {
+    res.status(204).end();
+    return;
+  }
   next();
 });
-
-app.use(cors({
-  origin: true,
-  credentials: false,
-  methods: ['GET', 'POST', 'DELETE', 'OPTIONS'],
-  allowedHeaders: ['Content-Type']
-}));
 app.use(express.json({ limit: '32mb' }));
 
 const MAX_FILE_TRANSFER_FILES = 24;
 const MAX_FILE_TRANSFER_BYTES = 24 * 1024 * 1024;
+const MAX_FILE_TRANSFER_CHUNK_BYTES = 512 * 1024;
 
 function noStore(res) {
   res.setHeader('Cache-Control', 'no-store');
 }
 
+function sendFilesystemError(res, error) {
+  const normalized = toFilesystemHttpError(error);
+  const code = String(normalized.code || 'FILESYSTEM_ERROR').toLowerCase();
+  const status = Number(normalized.status || 500);
+  res.status(status).json({ ok: false, error: code });
+}
+
 function clampNumber(value, min, max, fallback) {
   const number = Number(value);
   if (!Number.isFinite(number)) {
@@ -79,6 +327,24 @@ function clampNumber(value, min, max, fallback) {
   return Math.max(min, Math.min(max, Math.round(number)));
 }
 
+function normalizeMonitorIndex(value, fallback = 0) {
+  return clampNumber(value, 0, 63, fallback);
+}
+
+function normalizeMonitorSelections(value) {
+  const result = {};
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return result;
+  }
+  for (const [deviceId, monitorIndex] of Object.entries(value)) {
+    const id = String(deviceId || '').trim();
+    if (id) {
+      result[id] = normalizeMonitorIndex(monitorIndex);
+    }
+  }
+  return result;
+}
+
 function normalizeDeviceIds(value) {
   const raw = Array.isArray(value)
     ? value
@@ -133,13 +399,55 @@ function normalizeTransferFiles(value) {
   return { ok: true, files, totalBytes };
 }
 
+function normalizeTransferChunk(body = {}) {
+  const dataBase64 = String(body.dataBase64 || '').replace(/^data:[^,]*,/i, '').trim();
+  const name = String(body.name || '').replace(/[\r\n\t\0]/g, ' ').trim().slice(0, 240);
+  const relativePath = String(body.relativePath || name).replace(/[\r\n\t\0]/g, ' ').trim().slice(0, 600);
+  const offset = Math.max(0, Math.floor(Number(body.offset) || 0));
+  const totalBytes = Math.max(0, Math.floor(Number(body.totalBytes) || 0));
+  const byteLength = dataBase64 ? Buffer.byteLength(dataBase64, 'base64') : 0;
+  const final = body.final === true;
+
+  if (!name || !relativePath || offset > totalBytes || offset + byteLength > totalBytes) {
+    return { ok: false, error: 'invalid-file-transfer-chunk' };
+  }
+  if (byteLength > MAX_FILE_TRANSFER_CHUNK_BYTES) {
+    return { ok: false, error: 'file-transfer-chunk-too-large', byteLength };
+  }
+  if (byteLength === 0 && !(final && totalBytes === 0 && offset === 0)) {
+    return { ok: false, error: 'empty-file-transfer-chunk' };
+  }
+
+  return {
+    ok: true,
+    chunk: {
+      name,
+      relativePath,
+      offset,
+      totalBytes,
+      byteLength,
+      dataBase64,
+      final,
+      mimeType: String(body.type || body.mimeType || '').slice(0, 160),
+      lastModified: Number(body.lastModified || 0) || 0
+    }
+  };
+}
+
 function normalizeLiveOptions(payload = {}) {
-  const mode = String(payload.frameMode || payload.mode || 'remote-fast').trim() || 'remote-fast';
+  const mode = String(payload.frameMode || payload.mode || 'mode3-h264-hw').trim() || 'mode3-h264-hw';
+  const streamPurpose = String(payload.streamPurpose || payload.purpose || 'wall').trim().slice(0, 24) || 'wall';
+  const maxFps = streamPurpose === 'control' ? 60 : 30;
   return {
-    fps: clampNumber(payload.fps, 1, 24, 12),
-    maxWidth: clampNumber(payload.maxWidth, 320, 2560, 960),
-    maxHeight: clampNumber(payload.maxHeight, 180, 1440, 540),
-    quality: clampNumber(payload.quality, 20, 95, 60),
+    fps: clampNumber(payload.fps, 1, maxFps, 2),
+    maxWidth: clampNumber(payload.maxWidth, 320, 3840, 640),
+    maxHeight: clampNumber(payload.maxHeight, 180, 2160, 360),
+    quality: clampNumber(payload.quality, 20, 95, 45),
+    monitorIndex: normalizeMonitorIndex(payload.monitorIndex ?? payload.screenIndex ?? payload.displayIndex),
+    monitorSelections: normalizeMonitorSelections(payload.monitorSelections),
+    forceRestart: /^(1|true|yes|on)$/i.test(String(payload.forceRestart ?? '')),
+    reuseExisting: /^(1|true|yes|on)$/i.test(String(payload.reuseExisting ?? '')),
+    streamPurpose,
     mode,
     frameMode: mode
   };
@@ -149,15 +457,226 @@ function sendJson(ws, payload) {
   if (!ws || ws.readyState !== 1) {
     return false;
   }
-  ws.send(JSON.stringify(payload));
+  return safeWebSocketSend(ws, JSON.stringify(payload));
+}
+
+function forgetWebSocketClient(ws) {
+  unregisterFrameClient(ws);
+  frameClients.delete(ws);
+  audioClients.delete(ws);
+  inputClients.delete(ws);
+  try {
+    ws.terminate?.();
+  } catch {
+    // Ignore cleanup failures.
+  }
+}
+
+function safeWebSocketSend(ws, payload, options = undefined) {
+  if (!ws || ws.readyState !== 1) {
+    return false;
+  }
+
+  try {
+    ws.send(payload, options, err => {
+      if (err) {
+        forgetWebSocketClient(ws);
+      }
+    });
+    return true;
+  } catch {
+    forgetWebSocketClient(ws);
+    return false;
+  }
+}
+
+function unregisterFrameClient(ws) {
+  if (!ws) {
+    return;
+  }
+  const ids = ws.liveDeskDeviceIds instanceof Set ? ws.liveDeskDeviceIds : new Set();
+  for (const deviceId of ids) {
+    const clients = frameClientsByDeviceId.get(deviceId);
+    if (!clients) {
+      continue;
+    }
+    clients.delete(ws);
+    if (clients.size === 0) {
+      frameClientsByDeviceId.delete(deviceId);
+    }
+  }
+  frameWildcardClients.delete(ws);
+  ws.liveDeskFrameSendLane?.queue?.splice?.(0);
+}
+
+function registerFrameClient(ws) {
+  if (!ws) {
+    return;
+  }
+  const ids = ws.liveDeskDeviceIds instanceof Set ? ws.liveDeskDeviceIds : new Set();
+  if (ids.size === 0) {
+    frameWildcardClients.add(ws);
+    return;
+  }
+  for (const deviceId of ids) {
+    let clients = frameClientsByDeviceId.get(deviceId);
+    if (!clients) {
+      clients = new Set();
+      frameClientsByDeviceId.set(deviceId, clients);
+    }
+    clients.add(ws);
+  }
+}
+
+function ensureFrameClientSendLane(ws) {
+  if (!ws.liveDeskFrameSendLane) {
+    ws.liveDeskFrameSendLane = {
+      queue: [],
+      draining: false,
+      dropped: 0,
+      awaitingKeyFrames: new Set()
+    };
+  }
+  return ws.liveDeskFrameSendLane;
+}
+
+function dropQueuedFrameForLane(lane) {
+  const deltaIndex = lane.queue.findIndex(item => item?.isKeyFrame !== true);
+  const dropIndex = deltaIndex >= 0 ? deltaIndex : 0;
+  const dropped = lane.queue.splice(dropIndex, 1);
+  lane.dropped += dropped.length;
+  const droppedItem = dropped[0];
+  if (droppedItem?.isH264 && droppedItem.deviceId) {
+    lane.awaitingKeyFrames.add(droppedItem.deviceId);
+    let recoveryKeySeen = false;
+    lane.queue = lane.queue.filter(item => {
+      if (!item?.isH264 || item.deviceId !== droppedItem.deviceId) {
+        return true;
+      }
+      if (item.isKeyFrame) {
+        recoveryKeySeen = true;
+        lane.awaitingKeyFrames.delete(item.deviceId);
+        return true;
+      }
+      if (recoveryKeySeen) {
+        return true;
+      }
+      lane.dropped += 1;
+      return false;
+    });
+  }
+}
+
+function dropQueuedMode5FrameForLane(lane, deviceId) {
+  const dropIndex = lane.queue.findIndex(item => item?.isMode5 && item.deviceId === deviceId);
+  if (dropIndex < 0) {
+    return false;
+  }
+  lane.queue.splice(dropIndex, 1);
+  lane.dropped += 1;
+  return true;
+}
+
+function drainFrameClientSendLane(ws) {
+  const lane = ws.liveDeskFrameSendLane;
+  if (!lane || lane.draining) {
+    return;
+  }
+  lane.draining = true;
+  setImmediate(() => {
+    lane.draining = false;
+    if (!ws || ws.readyState !== ws.OPEN) {
+      lane.queue.length = 0;
+      return;
+    }
+
+    let sent = 0;
+    while (lane.queue.length > 0 && sent < frameClientDrainBudgetPackets) {
+      if (ws.bufferedAmount > frameBackpressureBytes) {
+        ws.liveDeskFrameBackpressured = true;
+        break;
+      }
+      const item = lane.queue.shift();
+      if (!item) {
+        continue;
+      }
+      ws.liveDeskFrameBackpressured = false;
+      safeWebSocketSend(ws, item.packet, { binary: true });
+      sent += 1;
+    }
+
+    if (lane.queue.length > 0 && ws.readyState === ws.OPEN) {
+      drainFrameClientSendLane(ws);
+    }
+  });
+}
+
+function enqueueFramePacketForClient(ws, packet, meta) {
+  if (!ws || ws.readyState !== ws.OPEN) {
+    return false;
+  }
+  const lane = ensureFrameClientSendLane(ws);
+  if (meta.isH264 && meta.isKeyFrame) {
+    lane.awaitingKeyFrames.delete(meta.deviceId);
+  } else if (meta.isH264 && lane.awaitingKeyFrames.has(meta.deviceId)) {
+    lane.dropped += 1;
+    ws.liveDeskFrameBackpressureDrops = Number(ws.liveDeskFrameBackpressureDrops || 0) + 1;
+    return false;
+  }
+  const backpressureBytes = meta.isMode5 ? mode5FrameBackpressureBytes : frameBackpressureBytes;
+  if (ws.bufferedAmount > backpressureBytes) {
+    ws.liveDeskFrameBackpressured = true;
+    lane.dropped += 1;
+    if (meta.isH264 && meta.deviceId) {
+      lane.awaitingKeyFrames.add(meta.deviceId);
+    }
+    ws.liveDeskFrameBackpressureDrops = Number(ws.liveDeskFrameBackpressureDrops || 0) + 1;
+    return false;
+  }
+  if (meta.isMode5) {
+    let queuedMode5Packets = lane.queue.filter(item => item?.isMode5 && item.deviceId === meta.deviceId).length;
+    while (queuedMode5Packets >= mode5FrameQueuePackets) {
+      if (!dropQueuedMode5FrameForLane(lane, meta.deviceId)) {
+        break;
+      }
+      queuedMode5Packets -= 1;
+      ws.liveDeskFrameBackpressureDrops = Number(ws.liveDeskFrameBackpressureDrops || 0) + 1;
+    }
+  }
+  while (lane.queue.length >= frameClientQueuePackets) {
+    dropQueuedFrameForLane(lane);
+    ws.liveDeskFrameBackpressureDrops = Number(ws.liveDeskFrameBackpressureDrops || 0) + 1;
+  }
+  lane.queue.push({
+    packet,
+    deviceId: meta.deviceId,
+    frameSeq: meta.frameSeq,
+    isH264: meta.isH264,
+    isMode5: meta.isMode5,
+    isKeyFrame: meta.isKeyFrame
+  });
+  drainFrameClientSendLane(ws);
   return true;
 }
 
 function updateFrameSubscription(ws, payload = {}) {
+  const previousDeviceIds = ws.liveDeskDeviceIds instanceof Set
+    ? new Set(ws.liveDeskDeviceIds)
+    : new Set();
+  unregisterFrameClient(ws);
   const deviceIds = normalizeDeviceIds(payload.deviceIds ?? payload.devices ?? payload.deviceId);
   ws.liveDeskDeviceIds = new Set(deviceIds);
+  registerFrameClient(ws);
   ws.liveDeskAutoStart = /^(1|true|yes|on|live)$/i.test(String(payload.autoStartLive ?? payload.startLive ?? ''));
   ws.liveDeskLiveOptions = normalizeLiveOptions(payload);
+  if (!(ws.liveDeskStreamIdsByDeviceId instanceof Map)) {
+    ws.liveDeskStreamIdsByDeviceId = new Map();
+  }
+  for (const subscribedDeviceId of ws.liveDeskStreamIdsByDeviceId.keys()) {
+    if (!ws.liveDeskDeviceIds.has(subscribedDeviceId)) {
+      ws.liveDeskStreamIdsByDeviceId.delete(subscribedDeviceId);
+    }
+  }
   sendJson(ws, {
     type: 'RemoteFrameSubscription',
     timestamp: new Date().toISOString(),
@@ -165,37 +684,97 @@ function updateFrameSubscription(ws, payload = {}) {
     autoStartLive: ws.liveDeskAutoStart
   });
 
-  if (ws.liveDeskAutoStart && deviceIds.length > 0) {
-    const lookup = new Map(remoteHub.listDevices({ includeDataUrl: false }).map(device => [device.deviceId, device]));
-    const started = [];
-    const skipped = [];
-    for (const deviceId of deviceIds.slice(0, 80)) {
-      const device = lookup.get(deviceId);
-      const liveCapable = device?.liveStreamEnabled === true
-        || device?.liveStreamCapable === true
-        || device?.capabilities?.liveStream === true
-        || device?.capabilities?.stream === true
-        || device?.capabilities?.screenStream === true;
-      if (!device?.connected || !liveCapable) {
-        skipped.push({ deviceId, reason: device?.connected ? 'live-unavailable' : 'not-connected' });
-        continue;
-      }
-      const result = remoteHub.startLiveStream(deviceId, {
-        ...ws.liveDeskLiveOptions,
-        streamId: `livedesk-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
-      });
-      if (result?.ok) {
-        started.push({ deviceId, streamId: result.streamId, fps: result.fps });
-      } else {
-        skipped.push({ deviceId, reason: result?.error || 'start-failed' });
-      }
+  const newlySubscribedIds = deviceIds.filter(deviceId => !previousDeviceIds.has(deviceId));
+  const targetIds = newlySubscribedIds.length > 0 ? newlySubscribedIds : deviceIds;
+  for (const deviceId of targetIds.slice(0, 80)) {
+    startFrameSubscriptionLive(ws, 'subscribe', deviceId, { reuseExisting: true });
+  }
+}
+
+function startFrameSubscriptionLive(ws, reason = 'subscribe', onlyDeviceId = '', overrideLiveOptions = null) {
+  if (!hasHubFeatureAccess()) {
+    sendJson(ws, { type: 'RemoteFrameSubscriptionError', error: 'livedesk-plan-device-limit', license: licenseSnapshot() });
+    return;
+  }
+  const subscribedIds = [...(ws.liveDeskDeviceIds || [])];
+  if (!ws.liveDeskAutoStart || subscribedIds.length === 0) {
+    return;
+  }
+
+  const targetIds = onlyDeviceId
+    ? subscribedIds.filter(deviceId => deviceId === onlyDeviceId)
+    : subscribedIds;
+  if (targetIds.length === 0) {
+    return;
+  }
+
+  const liveOptions = overrideLiveOptions && typeof overrideLiveOptions === 'object'
+    ? { ...ws.liveDeskLiveOptions, ...overrideLiveOptions }
+    : ws.liveDeskLiveOptions;
+  const lookup = new Map(remoteHub.listDevices({ includeDataUrl: false }).map(device => [device.deviceId, device]));
+  const started = [];
+  const skipped = [];
+  for (const deviceId of targetIds.slice(0, 80)) {
+    const device = lookup.get(deviceId);
+    const liveCapable = device?.liveStreamEnabled === true
+      || device?.liveStreamCapable === true
+      || device?.capabilities?.liveStream === true
+      || device?.capabilities?.stream === true
+      || device?.capabilities?.screenStream === true;
+    if (!device?.connected || !liveCapable) {
+      skipped.push({ deviceId, reason: device?.connected ? 'live-unavailable' : 'not-connected' });
+      continue;
     }
-    sendJson(ws, {
-      type: 'RemoteFrameLiveAutoStart',
-      timestamp: new Date().toISOString(),
-      started,
-      skipped: skipped.slice(0, 24)
+    const monitorIndex = Object.prototype.hasOwnProperty.call(liveOptions.monitorSelections || {}, deviceId)
+      ? liveOptions.monitorSelections[deviceId]
+      : liveOptions.monitorIndex;
+    const result = remoteHub.startLiveStream(deviceId, {
+      ...liveOptions,
+      monitorIndex,
+      reuseExisting: liveOptions.forceRestart !== true
+        && (liveOptions.reuseExisting === true || reason === 'subscribe' || reason === 'watchdog'),
+      silentReuse: reason === 'watchdog' && liveOptions.forceRestart !== true
     });
+    if (result?.ok) {
+      ws.liveDeskStreamIdsByDeviceId.set(deviceId, result.streamId);
+      started.push({ deviceId, streamId: result.streamId, fps: result.fps, reused: result.reused === true });
+    } else {
+      ws.liveDeskStreamIdsByDeviceId.delete(deviceId);
+      skipped.push({ deviceId, reason: result?.error || 'start-failed' });
+    }
+  }
+  if (reason === 'watchdog' && !started.some(item => item.reused !== true)) {
+    return;
+  }
+  sendJson(ws, {
+    type: 'RemoteFrameLiveAutoStart',
+    timestamp: new Date().toISOString(),
+    reason,
+    started,
+    skipped: skipped.slice(0, 24)
+  });
+}
+
+function restartFrameSubscriptionLive(ws, payload = {}) {
+  const requestedIds = normalizeDeviceIds(payload.deviceIds ?? payload.devices ?? payload.deviceId);
+  const targetIds = requestedIds.length > 0
+    ? requestedIds
+    : [...(ws.liveDeskDeviceIds || [])];
+  if (targetIds.length === 0) {
+    sendJson(ws, { type: 'RemoteFrameSubscriptionError', error: 'restart-device-missing' });
+    return;
+  }
+  const restartOptions = {
+    ...normalizeLiveOptions({
+      ...ws.liveDeskLiveOptions,
+      ...payload
+    }),
+    forceRestart: true,
+    restartToken: String(payload.restartToken || `${Date.now()}`).slice(0, 128),
+    restartReason: String(payload.restartReason || payload.reason || 'browser-stale').slice(0, 128)
+  };
+  for (const deviceId of targetIds.slice(0, 16)) {
+    startFrameSubscriptionLive(ws, restartOptions.restartReason, deviceId, restartOptions);
   }
 }
 
@@ -209,20 +788,26 @@ function updateAudioSubscription(ws, payload = {}) {
   });
 }
 
-function buildRemoteFrameBinaryPacket(frameEvent) {
+function buildRemoteFrameBinaryPacket(frameEvent, diagnostics = {}) {
   const payload = frameEvent?.payload;
   if (!Buffer.isBuffer(payload) || payload.length === 0) {
     return null;
   }
   const frame = frameEvent.frame || {};
+  const hubPacketEpochMs = Date.now();
+  const hubPacketAt = new Date(hubPacketEpochMs).toISOString();
   const metadata = {
     type: 'remote.frame.binary',
     kind: frameEvent.kind || 'live',
     deviceId: frameEvent.deviceId || frame.deviceId || '',
     frameSeq: Number(frame.frameSeq || 0) || 0,
+    streamFrameSeq: Number(frame.streamFrameSeq || 0) || 0,
     streamId: frame.streamId || '',
+    commandId: frame.commandId || '',
     width: Number(frame.width || 0) || 0,
     height: Number(frame.height || 0) || 0,
+    sourceWidth: Number(frame.sourceWidth || 0) || 0,
+    sourceHeight: Number(frame.sourceHeight || 0) || 0,
     mimeType: frameEvent.mimeType || frame.mimeType || frame.format || 'image/jpeg',
     mode: frame.mode || '',
     frameMode: frame.frameMode || frame.mode || '',
@@ -230,13 +815,52 @@ function buildRemoteFrameBinaryPacket(frameEvent) {
     encoding: frame.encoding || '',
     codec: frame.codec || '',
     compression: frame.compression || frame.mimeType || frame.format || '',
+    pixelFormat: frame.pixelFormat || '',
+    bytesPerPixel: Number(frame.bytesPerPixel || 0) || 0,
+    uncompressedByteLength: Number(frame.uncompressedByteLength || 0) || 0,
+    h264Format: frame.h264Format || '',
+    isKeyFrame: frame.isKeyFrame === true,
+    chunkType: frame.chunkType || '',
+    timestampUs: Number(frame.timestampUs || 0) || 0,
+    durationUs: Number(frame.durationUs || 0) || 0,
+    sourceGapMs: Number(frame.sourceGapMs || 0) || 0,
+    agentSendGapMs: Number(frame.agentSendGapMs || 0) || 0,
+    agentSendDurationMs: Number(frame.agentSendDurationMs || 0) || 0,
+    agentSendDurationFrameSeq: Number(frame.agentSendDurationFrameSeq || 0) || 0,
+    agentPaceMs: Number(frame.agentPaceMs || 0) || 0,
+    agentQueueBeforePaceMs: Number(frame.agentQueueBeforePaceMs || 0) || 0,
+    agentFrameAgeMs: Number(frame.agentFrameAgeMs || 0) || 0,
+    droppedByAgent: Number(frame.droppedByAgent || 0) || 0,
+    hubIngressDropped: Number(frame.hubIngressDropped || 0) || 0,
+    hubClientDropped: Number(diagnostics.hubClientDropped || 0) || 0,
+    hardwareEncoder: frame.hardwareEncoder || '',
+    platformProfile: frame.platformProfile || '',
+    monitorIndex: Number.isFinite(Number(frame.monitorIndex)) ? Number(frame.monitorIndex) : 0,
+    monitorCount: Number.isFinite(Number(frame.monitorCount)) ? Number(frame.monitorCount) : 1,
     fps: Number(frame.fps || 0) || 0,
     capturedAt: frame.capturedAt || '',
     receivedAt: frame.receivedAt || '',
+    hubPacketAt,
+    hubPacketEpochMs,
     byteLength: Number(frameEvent.byteLength || payload.length) || payload.length,
     contentHash: frame.contentHash || '',
     captureMs: Number(frame.captureMs || 0) || 0,
-    sameContentStreak: Number(frame.sameContentStreak || 0) || 0
+    captureStageMs: Number(frame.captureStageMs || 0) || 0,
+    convertMs: Number(frame.convertMs || 0) || 0,
+    compressMs: Number(frame.compressMs || 0) || 0,
+    captureSourceSerial: Number(frame.captureSourceSerial || 0) || 0,
+    captureSourceSkipped: Number(frame.captureSourceSkipped || 0) || 0,
+    deltaTileSize: Number(frame.deltaTileSize || 0) || 0,
+    deltaTileCount: Number(frame.deltaTileCount || 0) || 0,
+    deltaVisualTileCount: Number(frame.deltaVisualTileCount || 0) || 0,
+    deltaRefreshTileCount: Number(frame.deltaRefreshTileCount || 0) || 0,
+    deltaTotalTiles: Number(frame.deltaTotalTiles || 0) || 0,
+    sameContentStreak: Number(frame.sameContentStreak || 0) || 0,
+    layoutVersion: Number(frame.layoutVersion || 0) || 0,
+    atlasComposeMs: Number(frame.atlasComposeMs || 0) || 0,
+    atlasPoolStarved: Number(frame.atlasPoolStarved || 0) || 0,
+    atlasReadyTiles: Number(frame.atlasReadyTiles || 0) || 0,
+    atlasTileCount: Number(frame.atlasTileCount || 0) || 0
   };
   const metaBuffer = Buffer.from(JSON.stringify(metadata), 'utf8');
   const header = Buffer.allocUnsafe(4);
@@ -269,29 +893,60 @@ function buildRemoteAudioBinaryPacket(audioEvent) {
 }
 
 function broadcastRemoteBinaryFrame(frameEvent) {
+  for (const session of atlasClients.values()) {
+    session.ingest(frameEvent);
+  }
+  if (!hasHubFeatureAccess()) {
+    return;
+  }
   const deviceId = String(frameEvent?.deviceId || frameEvent?.frame?.deviceId || '').trim();
   if (!deviceId || frameClients.size === 0) {
     return;
   }
-  const packet = buildRemoteFrameBinaryPacket(frameEvent);
-  if (!packet) {
+  const targetClients = new Set([
+    ...(frameClientsByDeviceId.get(deviceId) || []),
+    ...frameWildcardClients
+  ]);
+  if (targetClients.size === 0) {
     return;
   }
-  for (const client of frameClients) {
+  const frame = frameEvent.frame || {};
+  const isH264 = String(frame.codec || frame.mimeType || frame.format || '').toLowerCase().includes('h264')
+    || String(frame.frameMode || frame.mode || '').toLowerCase() === 'mode3-h264-hw';
+  const isMode5 = String(frame.frameMode || frame.mode || '').toLowerCase() === 'mode5-lzo-delta';
+  const isKeyFrame = frame.isKeyFrame === true || String(frame.chunkType || '').toLowerCase() === 'key';
+  const frameSeq = Number(frame.frameSeq || 0) || 0;
+  for (const client of targetClients) {
     if (client.readyState !== client.OPEN) {
       continue;
     }
-    if (client.liveDeskDeviceIds?.size > 0 && !client.liveDeskDeviceIds.has(deviceId)) {
+    const expectedStreamId = client.liveDeskStreamIdsByDeviceId instanceof Map
+      ? client.liveDeskStreamIdsByDeviceId.get(deviceId)
+      : '';
+    if (expectedStreamId && String(frame.streamId || '') !== expectedStreamId) {
+      continue;
+    }
+    const lane = ensureFrameClientSendLane(client);
+    if (client.liveDeskFrameBackpressured && isH264 && !isKeyFrame) {
+      lane.dropped += 1;
+      lane.awaitingKeyFrames.add(deviceId);
+      client.liveDeskFrameBackpressureDrops = Number(client.liveDeskFrameBackpressureDrops || 0) + 1;
       continue;
     }
-    if (client.bufferedAmount > 8 * 1024 * 1024) {
+    const packet = buildRemoteFrameBinaryPacket(frameEvent, {
+      hubClientDropped: lane.dropped
+    });
+    if (!packet) {
       continue;
     }
-    client.send(packet, { binary: true });
+    enqueueFramePacketForClient(client, packet, { deviceId, frameSeq, isH264, isMode5, isKeyFrame });
   }
 }
 
 function broadcastRemoteBinaryAudio(audioEvent) {
+  if (!hasHubFeatureAccess()) {
+    return;
+  }
   const deviceId = String(audioEvent?.deviceId || audioEvent?.frame?.deviceId || '').trim();
   if (!deviceId || audioClients.size === 0) {
     return;
@@ -310,10 +965,125 @@ function broadcastRemoteBinaryAudio(audioEvent) {
     if (client.bufferedAmount > 2 * 1024 * 1024) {
       continue;
     }
-    client.send(packet, { binary: true });
+    safeWebSocketSend(client, packet, { binary: true });
   }
 }
 
+function sendMode4AtlasFrame(ws, output) {
+  if (!hasHubFeatureAccess() || ws.readyState !== ws.OPEN || !output?.payload?.length) return;
+  const metadata = output.metadata || {};
+  const frameSeq = Number(metadata.frameSeq || 0) || 0;
+  const isKeyFrame = metadata.isKeyFrame === true;
+  const workerGeneration = Math.max(1, Number(metadata.workerGeneration || 1) || 1);
+  const encoderGeneration = Math.max(1, Number(metadata.encoderGeneration || 1) || 1);
+  const streamId = `${ws.liveDeskAtlasStreamId}-w${workerGeneration}-e${encoderGeneration}`;
+  const frameEvent = {
+    kind: 'live',
+    deviceId: '__livedesk_mode4_atlas__',
+    mimeType: 'video/h264',
+    byteLength: output.payload.length,
+    payload: output.payload,
+    frame: {
+      deviceId: '__livedesk_mode4_atlas__',
+      frameSeq,
+      streamFrameSeq: Number(metadata.streamFrameSeq || frameSeq) || frameSeq,
+      streamId,
+      commandId: streamId,
+      width: Number(metadata.width || 1920),
+      height: Number(metadata.height || 1080),
+      sourceWidth: Number(metadata.width || 1920),
+      sourceHeight: Number(metadata.height || 1080),
+      mimeType: 'video/h264',
+      mode: 'mode4-h264-atlas',
+      frameMode: 'mode4-h264-atlas',
+      frameProfile: 'mode4-h264-atlas-v1',
+      encoding: 'video-atlas',
+      codec: 'h264',
+      compression: 'video/h264',
+      h264Format: 'annexb',
+      isKeyFrame,
+      chunkType: isKeyFrame ? 'key' : 'delta',
+      timestampUs: Number(metadata.timestampUs || 0),
+      durationUs: Number(metadata.durationUs || 0),
+      fps: Number(metadata.fps || 20),
+      capturedAt: new Date().toISOString(),
+      receivedAt: new Date().toISOString(),
+      hardwareEncoder: String(metadata.hardwareEncoder || ''),
+      platformProfile: 'mode4-hub-atlas-worker',
+      workerGeneration,
+      encoderGeneration,
+      layoutVersion: Number(metadata.layoutVersion || 0),
+      atlasComposeMs: Number(metadata.composeMs || 0),
+      atlasPoolStarved: Number(metadata.poolStarved || 0),
+      atlasReadyTiles: Number(metadata.readyTileCount || 0),
+      atlasTileCount: Number(metadata.tileCount || 0)
+    }
+  };
+  const lane = ensureFrameClientSendLane(ws);
+  if (ws.liveDeskFrameBackpressured && !isKeyFrame) {
+    lane.dropped += 1;
+    lane.awaitingKeyFrames.add('__livedesk_mode4_atlas__');
+    return;
+  }
+  const packet = buildRemoteFrameBinaryPacket(frameEvent, { hubClientDropped: lane.dropped });
+  if (packet) {
+    enqueueFramePacketForClient(ws, packet, {
+      deviceId: '__livedesk_mode4_atlas__',
+      frameSeq,
+      isH264: true,
+      isKeyFrame
+    });
+  }
+}
+
+function configureMode4Atlas(ws, payload = {}) {
+  const deviceIds = normalizeDeviceIds(payload.deviceIds ?? payload.devices ?? payload.deviceId).slice(0, 100);
+  const monitorSelections = normalizeMonitorSelections(payload.monitorSelections);
+  const sharpTiles = Number(payload.tileWidth) >= 480 || Number(payload.tileHeight) >= 270;
+  const tileWidth = sharpTiles ? 480 : 320;
+  const tileHeight = sharpTiles ? 270 : 180;
+  ws.liveDeskAtlasDeviceIds = new Set(deviceIds);
+  ws.liveDeskAtlasInputOptions = { tileWidth, tileHeight, monitorSelections };
+  ws.liveDeskAtlasSession.configure({
+    deviceIds,
+    width: clampNumber(payload.width, 640, 3840, 1920),
+    height: clampNumber(payload.height, 360, 2160, 1080),
+    tileWidth,
+    tileHeight,
+    fps: clampNumber(payload.fps, 1, 30, 20)
+  });
+  for (const deviceId of deviceIds) {
+    startMode4AtlasInput(ws, deviceId, 'atlas-configure');
+  }
+  sendJson(ws, {
+    type: 'Mode4AtlasSubscription',
+    deviceIds,
+    inputMode: 'mode2-lzo',
+    outputMode: 'mode4-h264-atlas',
+    tileWidth,
+    tileHeight,
+    timestamp: new Date().toISOString()
+  });
+}
+
+function startMode4AtlasInput(ws, deviceId, reason = 'atlas-configure') {
+  const options = ws?.liveDeskAtlasInputOptions;
+  if (!options || !ws.liveDeskAtlasDeviceIds?.has(deviceId)) return { ok: false, error: 'atlas-device-not-configured' };
+  return remoteHub.startLiveStream(deviceId, {
+    fps: 8,
+    maxWidth: options.tileWidth,
+    maxHeight: options.tileHeight,
+    quality: 60,
+    mode: 'mode2-lzo',
+    frameMode: 'mode2-lzo',
+    streamPurpose: 'atlas',
+    monitorIndex: Number(options.monitorSelections?.[deviceId] || 0),
+    reuseExisting: false,
+    silentReuse: true,
+    restartReason: reason
+  });
+}
+
 function wantsBinaryFrame(req) {
   return /^(1|true|yes|on|binary|raw)$/i.test(String(req.query?.binary ?? req.query?.raw ?? ''))
     || /image\//i.test(String(req.headers.accept || ''));
@@ -350,13 +1120,69 @@ app.get('/api/health', (_req, res) => {
 
 app.get('/api/remote/status', (_req, res) => {
   noStore(res);
+  const secretStatus = remoteHub.getStatus({ includeSecrets: true });
   res.json({
-    ...remoteHub.getStatus({ includeSecrets: true }),
+    ...remoteHub.getStatus({ includeSecrets: false }),
+    pairingPin: secretStatus.pairingPin,
     product: 'LiveDesk',
     agentPackage: '@livedesk/client'
   });
 });
 
+app.get('/api/remote/registry-credentials', (_req, res) => {
+  noStore(res);
+  const status = remoteHub.getStatus({ includeSecrets: true });
+  res.json({
+    pairToken: status.pairToken,
+    pairingPin: status.pairingPin,
+    pairingPinUpdatedAt: status.pairingPinUpdatedAt
+  });
+});
+
+app.get('/api/remote/license', (_req, res) => {
+  noStore(res);
+  res.json(licenseSnapshot());
+});
+
+app.post('/api/remote/license/sync', async (req, res) => {
+  noStore(res);
+  try {
+    const authorization = String(req.headers.authorization || '');
+    const accessToken = authorization.replace(/^Bearer\s+/i, '').trim();
+    res.json(await syncVerifiedLicense(accessToken));
+  } catch (err) {
+    verifiedLicense = {
+      userId: '',
+      plan: 'free',
+      status: 'inactive',
+      expiresAt: '',
+      verifiedAt: Date.now()
+    };
+    res.status(401).json({ ok: false, error: err instanceof Error ? err.message : String(err), license: licenseSnapshot() });
+  }
+});
+
+app.delete('/api/remote/license', (_req, res) => {
+  noStore(res);
+  verifiedLicense = {
+    userId: '',
+    plan: 'free',
+    status: 'inactive',
+    expiresAt: '',
+    verifiedAt: Date.now()
+  };
+  res.json(licenseSnapshot());
+});
+
+app.post('/api/remote/pairing-pin', (_req, res) => {
+  noStore(res);
+  try {
+    res.json(remoteHub.rotatePairingPin());
+  } catch (err) {
+    res.status(500).json({ ok: false, error: err instanceof Error ? err.message : String(err) });
+  }
+});
+
 app.get('/api/remote/devices', (req, res) => {
   noStore(res);
   const includeDataUrl = /^(1|true|yes|on|data|base64)$/i.test(String(req.query?.includeDataUrl ?? ''));
@@ -438,12 +1264,138 @@ app.post('/api/remote/devices/:deviceId/ping', (req, res) => {
   }));
 });
 
-app.post('/api/remote/devices/:deviceId/input', (req, res) => {
+app.post('/api/remote/devices/:deviceId/input', requireHubFeatureAccess, (req, res) => {
   noStore(res);
   res.json(remoteHub.sendInputControl(req.params.deviceId, req.body || {}));
 });
 
-app.post('/api/remote/files/transfer', (req, res) => {
+app.get('/api/remote/filesystem/roots', requireHubFeatureAccess, async (req, res) => {
+  noStore(res);
+  try {
+    res.json(await hubFilesystem.getRoots({ refresh: /^(1|true|yes|on)$/i.test(String(req.query?.refresh || '')) }));
+  } catch (error) {
+    sendFilesystemError(res, error);
+  }
+});
+
+app.get('/api/remote/filesystem/entries', requireHubFeatureAccess, async (req, res) => {
+  noStore(res);
+  try {
+    res.json(await hubFilesystem.getEntries(req.query?.id));
+  } catch (error) {
+    sendFilesystemError(res, error);
+  }
+});
+
+app.post('/api/remote/filesystem/selection/scan', requireHubFeatureAccess, async (req, res) => {
+  noStore(res);
+  try {
+    const scan = await hubFilesystem.scan(req.body?.itemIds);
+    res.json({ files: scan.files.length, folders: scan.folders, totalBytes: scan.totalBytes });
+  } catch (error) {
+    sendFilesystemError(res, error);
+  }
+});
+
+app.post('/api/remote/files/from-hub', requireHubFeatureAccess, (req, res) => {
+  noStore(res);
+  try {
+    const deviceIds = normalizeDeviceIds(req.body?.deviceIds);
+    if (deviceIds.length === 0) {
+      res.status(400).json({ ok: false, error: 'no-target-devices' });
+      return;
+    }
+    const itemIds = Array.isArray(req.body?.itemIds) ? req.body.itemIds : [];
+    if (itemIds.length === 0) {
+      res.status(400).json({ ok: false, error: 'no-filesystem-items-selected' });
+      return;
+    }
+    const job = hubTransferJobs.create({
+      itemIds,
+      deviceIds,
+      remoteDirectory: req.body?.remoteDirectory
+    });
+    res.status(202).json({ ok: true, jobId: job.jobId, state: job.state });
+  } catch (error) {
+    sendFilesystemError(res, error);
+  }
+});
+
+app.get('/api/remote/files/jobs', requireHubFeatureAccess, (req, res) => {
+  noStore(res);
+  res.json({ jobs: hubTransferJobs.list({ activeOnly: /^(1|true|yes|on)$/i.test(String(req.query?.active || '')) }) });
+});
+
+app.get('/api/remote/files/jobs/:jobId', requireHubFeatureAccess, (req, res) => {
+  noStore(res);
+  const job = hubTransferJobs.get(req.params.jobId);
+  if (!job) {
+    res.status(404).json({ ok: false, error: 'transfer-job-not-found' });
+    return;
+  }
+  res.json(job);
+});
+
+app.post('/api/remote/files/jobs/:jobId/cancel', requireHubFeatureAccess, (req, res) => {
+  noStore(res);
+  const job = hubTransferJobs.cancel(req.params.jobId);
+  if (!job) {
+    res.status(404).json({ ok: false, error: 'transfer-job-not-found' });
+    return;
+  }
+  res.json({ ok: true, ...job });
+});
+
+app.get('/api/remote/filesystem/shared-folders', requireHubFeatureAccess, async (_req, res) => {
+  noStore(res);
+  try {
+    res.json({ folders: await hubSharedFolders.list() });
+  } catch (error) {
+    sendFilesystemError(res, error);
+  }
+});
+
+app.post('/api/remote/filesystem/shared-folders', requireHubFeatureAccess, async (req, res) => {
+  noStore(res);
+  try {
+    res.status(201).json({ ok: true, folder: await hubSharedFolders.add(req.body?.sourceId) });
+  } catch (error) {
+    sendFilesystemError(res, error);
+  }
+});
+
+app.patch('/api/remote/filesystem/shared-folders/:folderId', requireHubFeatureAccess, async (req, res) => {
+  noStore(res);
+  try {
+    res.json({ ok: true, folder: await hubSharedFolders.update(req.params.folderId, req.body || {}) });
+  } catch (error) {
+    sendFilesystemError(res, error);
+  }
+});
+
+app.delete('/api/remote/filesystem/shared-folders/:folderId', requireHubFeatureAccess, async (req, res) => {
+  noStore(res);
+  try {
+    res.json(await hubSharedFolders.remove(req.params.folderId));
+  } catch (error) {
+    sendFilesystemError(res, error);
+  }
+});
+
+app.post('/api/remote/filesystem/shared-folders/:folderId/sync', requireHubFeatureAccess, async (req, res) => {
+  noStore(res);
+  try {
+    res.status(202).json(await hubSharedFolders.sync(
+      req.params.folderId,
+      normalizeDeviceIds(req.body?.deviceIds),
+      req.body?.remoteDirectory
+    ));
+  } catch (error) {
+    sendFilesystemError(res, error);
+  }
+});
+
+app.post('/api/remote/files/transfer', requireHubFeatureAccess, (req, res) => {
   noStore(res);
   const deviceIds = normalizeDeviceIds(req.body?.deviceIds);
   if (deviceIds.length === 0) {
@@ -484,7 +1436,49 @@ app.post('/api/remote/files/transfer', (req, res) => {
   });
 });
 
-app.post('/api/remote/devices/:deviceId/tasks', (req, res) => {
+app.post('/api/remote/files/chunk', requireHubFeatureAccess, (req, res) => {
+  noStore(res);
+  const deviceIds = normalizeDeviceIds(req.body?.deviceIds);
+  if (deviceIds.length === 0) {
+    res.status(400).json({ ok: false, error: 'no-target-devices' });
+    return;
+  }
+  const normalized = normalizeTransferChunk(req.body || {});
+  if (!normalized.ok) {
+    res.status(400).json({ ok: false, error: normalized.error, byteLength: normalized.byteLength || 0 });
+    return;
+  }
+
+  const transferId = String(req.body?.transferId || crypto.randomUUID()).replace(/[^a-zA-Z0-9_.:-]/g, '-').slice(0, 128);
+  const remoteDirectory = String(req.body?.remoteDirectory || '').replace(/[\0\r\n\t]/g, ' ').trim().slice(0, 600);
+  const queuedAt = new Date().toISOString();
+  const results = deviceIds.map(deviceId => ({
+    deviceId,
+    ...remoteHub.sendCommand(deviceId, {
+      command: 'file.transfer.chunk',
+      payload: {
+        transferId,
+        remoteDirectory,
+        ...normalized.chunk,
+        requestedAt: queuedAt
+      }
+    })
+  }));
+  const queued = results.filter(result => result.ok).length;
+  res.json({
+    ok: queued > 0,
+    transferId,
+    queued,
+    total: deviceIds.length,
+    byteLength: normalized.chunk.byteLength,
+    offset: normalized.chunk.offset,
+    final: normalized.chunk.final,
+    results,
+    error: queued > 0 ? undefined : 'no-transfer-queued'
+  });
+});
+
+app.post('/api/remote/devices/:deviceId/tasks', requireHubFeatureAccess, (req, res) => {
   noStore(res);
   res.json(remoteHub.requestAgentTask(req.params.deviceId, {
     instruction: req.body?.instruction,
@@ -496,7 +1490,7 @@ app.post('/api/remote/devices/:deviceId/tasks', (req, res) => {
   }));
 });
 
-app.post('/api/remote/tasks', (req, res) => {
+app.post('/api/remote/tasks', requireHubFeatureAccess, (req, res) => {
   noStore(res);
   const requestedIds = normalizeDeviceIds(req.body?.deviceIds);
   const approvalLevel = req.body?.approvalLevel === 'ai-assist' ? 'ai-assist' : 'task-only';
@@ -545,7 +1539,7 @@ app.post('/api/remote/devices/:deviceId/thumbnail/request', (req, res) => {
   res.json(remoteHub.requestThumbnail(req.params.deviceId, req.body || {}));
 });
 
-app.get('/api/remote/devices/:deviceId/live/frame', (req, res) => {
+app.get('/api/remote/devices/:deviceId/live/frame', requireHubFeatureAccess, (req, res) => {
   noStore(res);
   if (wantsBinaryFrame(req)) {
     sendFrameBinary(req, res, 'live');
@@ -561,7 +1555,7 @@ app.get('/api/remote/devices/:deviceId/live/frame', (req, res) => {
   res.json({ ok: true, frame });
 });
 
-app.post('/api/remote/devices/:deviceId/live/start', (req, res) => {
+app.post('/api/remote/devices/:deviceId/live/start', requireHubFeatureAccess, (req, res) => {
   noStore(res);
   res.json(remoteHub.startLiveStream(req.params.deviceId, req.body || {}));
 });
@@ -571,7 +1565,7 @@ app.post('/api/remote/devices/:deviceId/live/stop', (req, res) => {
   res.json(remoteHub.stopLiveStream(req.params.deviceId, req.body || {}));
 });
 
-app.post('/api/remote/devices/:deviceId/audio/start', (req, res) => {
+app.post('/api/remote/devices/:deviceId/audio/start', requireHubFeatureAccess, (req, res) => {
   noStore(res);
   res.json(remoteHub.startAudioStream(req.params.deviceId, req.body || {}));
 });
@@ -597,12 +1591,21 @@ if (existsSync(webIndexPath)) {
 }
 
 httpServer.on('upgrade', (req, socket, head) => {
+  if (!isTrustedBrowserRequest(req)) {
+    socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
+    socket.destroy();
+    return;
+  }
   try {
     const parsed = new URL(req.url || '/', `http://${req.headers.host || '127.0.0.1'}`);
     if (parsed.pathname === '/api/remote/frames/ws') {
       frameWss.handleUpgrade(req, socket, head, ws => frameWss.emit('connection', ws, req));
       return;
     }
+    if (parsed.pathname === '/api/remote/atlas/ws') {
+      atlasWss.handleUpgrade(req, socket, head, ws => atlasWss.emit('connection', ws, req));
+      return;
+    }
     if (parsed.pathname === '/api/remote/input/ws') {
       inputWss.handleUpgrade(req, socket, head, ws => inputWss.emit('connection', ws, req));
       return;
@@ -622,6 +1625,15 @@ httpServer.on('upgrade', (req, socket, head) => {
 frameWss.on('connection', (ws, req) => {
   frameClients.add(ws);
   ws.liveDeskFrameClientId = `rfws-${++frameClientSeq}`;
+  try {
+    ws._socket?.setNoDelay?.(true);
+  } catch {
+    // Best-effort latency hint for browser frame sockets.
+  }
+  const cleanup = () => {
+    unregisterFrameClient(ws);
+    frameClients.delete(ws);
+  };
   try {
     const parsed = new URL(req.url || '/', `http://${req.headers.host || '127.0.0.1'}`);
     updateFrameSubscription(ws, { deviceIds: parsed.searchParams.get('devices') || '' });
@@ -633,13 +1645,15 @@ frameWss.on('connection', (ws, req) => {
       const payload = JSON.parse(Buffer.isBuffer(data) ? data.toString('utf8') : String(data || ''));
       if (payload?.type === 'subscribe') {
         updateFrameSubscription(ws, payload);
+      } else if (payload?.type === 'restart-live') {
+        restartFrameSubscriptionLive(ws, payload);
       }
     } catch {
       sendJson(ws, { type: 'RemoteFrameSubscriptionError', error: 'invalid-message' });
     }
   });
-  ws.on('close', () => frameClients.delete(ws));
-  ws.on('error', () => frameClients.delete(ws));
+  ws.on('close', cleanup);
+  ws.on('error', cleanup);
   sendJson(ws, {
     type: 'RemoteFrameSocketReady',
     protocol: 'livedesk.remote.frames.binary.v1',
@@ -648,6 +1662,52 @@ frameWss.on('connection', (ws, req) => {
   });
 });
 
+atlasWss.on('connection', ws => {
+  ws.liveDeskFrameClientId = `atlas-${++frameClientSeq}`;
+  ws.liveDeskAtlasStreamId = `mode4-atlas-${crypto.randomUUID()}`;
+  try { ws._socket?.setNoDelay?.(true); } catch {}
+  const session = new Mode4AtlasSession({
+    onFrame: output => sendMode4AtlasFrame(ws, output),
+    onLayout: layout => sendJson(ws, { ...layout, type: 'Mode4AtlasLayout' }),
+    onStatus: status => {
+      if (status?.type === 'log') {
+        const logger = status.level === 'warn' ? console.warn : console.log;
+        logger(`[LiveDesk Hub] ${status.message}`);
+      }
+      sendJson(ws, { ...status, type: 'Mode4AtlasStatus' });
+    }
+  });
+  ws.liveDeskAtlasSession = session;
+  atlasClients.set(ws, session);
+  const cleanup = () => {
+    atlasClients.delete(ws);
+    session.close();
+    const lane = ws.liveDeskFrameSendLane;
+    if (lane) {
+      lane.queue.length = 0;
+      lane.awaitingKeyFrames.clear();
+    }
+  };
+  ws.on('message', data => {
+    try {
+      const payload = JSON.parse(Buffer.isBuffer(data) ? data.toString('utf8') : String(data || ''));
+      if (payload?.type === 'subscribe' || payload?.type === 'configure') {
+        configureMode4Atlas(ws, payload);
+      }
+    } catch {
+      sendJson(ws, { type: 'Mode4AtlasError', error: 'invalid-message' });
+    }
+  });
+  ws.on('close', cleanup);
+  ws.on('error', cleanup);
+  sendJson(ws, {
+    type: 'Mode4AtlasSocketReady',
+    protocol: 'livedesk.remote.atlas.h264.v1',
+    clientId: ws.liveDeskFrameClientId,
+    timestamp: new Date().toISOString()
+  });
+});
+
 audioWss.on('connection', (ws, req) => {
   audioClients.add(ws);
   ws.liveDeskAudioClientId = `raws-${++audioClientSeq}`;
@@ -681,6 +1741,10 @@ inputWss.on('connection', ws => {
   inputClients.add(ws);
   ws.liveDeskInputClientId = `riws-${++inputClientSeq}`;
   ws.on('message', data => {
+    if (!hasHubFeatureAccess()) {
+      sendJson(ws, { type: 'RemoteInputError', error: 'livedesk-plan-device-limit', license: licenseSnapshot() });
+      return;
+    }
     let payload;
     try {
       payload = JSON.parse(Buffer.isBuffer(data) ? data.toString('utf8') : String(data || ''));
@@ -689,8 +1753,15 @@ inputWss.on('connection', ws => {
       return;
     }
     const deviceId = String(payload?.deviceId || '').trim();
-    const input = payload?.input && typeof payload.input === 'object' ? payload.input : payload;
+    const input = payload?.input && typeof payload.input === 'object'
+      ? { ...payload.input, hubReceivedAtEpochMs: Date.now() }
+      : { ...payload, hubReceivedAtEpochMs: Date.now() };
     const result = remoteHub.sendInputControl(deviceId, input);
+    const fireAndForget = payload?.fireAndForget === true
+      || String(input?.type || '').toLowerCase() === 'pointermove';
+    if (fireAndForget && result?.ok) {
+      return;
+    }
     sendJson(ws, {
       type: result?.ok ? 'RemoteInputQueued' : 'RemoteInputError',
       requestId: payload?.requestId || '',
@@ -710,14 +1781,24 @@ inputWss.on('connection', ws => {
 });
 
 await remoteHub.start();
+connectedDeviceCount = Number(remoteHub.getStatus({ includeSecrets: false }).connectedDeviceCount || 0);
+hubSharedFolders.startAutoSync(
+  () => remoteHub.listDevices({ includeDataUrl: false }).filter(device => device.connected).map(device => device.deviceId),
+  () => process.env.LIVEDESK_REMOTE_DIRECTORY || 'Desktop/LiveDeskFiles'
+);
 httpServer.listen(httpPort, httpHost, () => {
   const status = remoteHub.getStatus({ includeSecrets: true });
+  const managerVersion = String(process.env.LIVEDESK_MANAGER_VERSION || packageInfo.version || 'dev');
+  console.log(`[LiveDesk Hub] Version ${managerVersion}`);
   console.log(`[LiveDesk Hub] HTTP API http://${httpHost}:${httpPort}`);
-  console.log(`[LiveDesk Hub] RemoteHub ${status.agentEndpoint} pair=${status.pairTokenPreview}`);
+  console.log(`[LiveDesk Hub] Client endpoint ${status.agentEndpoint} pair=${status.pairTokenPreview}`);
 });
 
 for (const signal of ['SIGINT', 'SIGTERM']) {
   process.once(signal, async () => {
+    for (const session of atlasClients.values()) session.close();
+    atlasClients.clear();
+    hubSharedFolders.close();
     await remoteHub.close();
     httpServer.close(() => process.exit(0));
   });