@livedesk/hub 0.1.72 → 0.1.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/hub",
-  "version": "0.1.72",
+  "version": "0.1.73",
   "description": "VuvoDesk local Hub API and browser frame bridge",
   "type": "module",
   "main": "src/server.js",

package/src/monitor-capture-ownership.mjs

@@ -0,0 +1,15 @@
+// Capture sharing is scoped to one physical monitor. Capability negotiation
+// keeps old Clients on their existing exclusive-capture protocol.
+export function supportsMonitorCapture(device) {
+  return device?.capabilities?.liveCaptureConcurrency === 'per-monitor';
+}
+
+export function captureOwnersCompete(existing, requested, perMonitor) {
+  if (!perMonitor) return true;
+  const existingMonitor = existing?.monitorIndex;
+  const requestedMonitor = requested?.monitorIndex;
+  if (!Number.isInteger(existingMonitor) || !Number.isInteger(requestedMonitor)) return true;
+  // Input ownership remains exclusive per computer, even on different screens.
+  return existingMonitor === requestedMonitor
+    || (existing.streamPurpose === 'control' && requested.streamPurpose === 'control');
+}

package/src/monitor-capture-ownership.test.mjs

@@ -0,0 +1,16 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { captureOwnersCompete, supportsMonitorCapture } from './monitor-capture-ownership.mjs';
+
+test('different monitors keep independent capture but the same monitor shares one owner', () => {
+  const wall = { monitorIndex: 0, streamPurpose: 'wall' };
+  assert.equal(captureOwnersCompete(wall, { ...wall, monitorIndex: 1 }, true), false);
+  assert.equal(captureOwnersCompete(wall, { ...wall, streamPurpose: 'control' }, true), true);
+  assert.equal(captureOwnersCompete(wall, { monitorIndex: 1, streamPurpose: 'control' }, true), false);
+  assert.equal(captureOwnersCompete({ ...wall, streamPurpose: 'control' },
+    { monitorIndex: 1, streamPurpose: 'control' }, true), true);
+  assert.equal(captureOwnersCompete(wall, { ...wall, monitorIndex: 1 }, false), true);
+  assert.equal(captureOwnersCompete(wall, { streamPurpose: 'wall' }, true), true);
+  assert.equal(supportsMonitorCapture({ capabilities: { liveCaptureConcurrency: 'per-monitor' } }), true);
+  assert.equal(supportsMonitorCapture({ capabilities: { liveCaptureConcurrency: 'exclusive' } }), false);
+});

package/src/monitor-capture-runtime.test.mjs

@@ -0,0 +1,121 @@
+import assert from 'node:assert/strict';
+import net from 'node:net';
+import { once } from 'node:events';
+import test from 'node:test';
+import { createRemoteHub } from './remote-hub.js';
+
+const keyFrame = Buffer.from([
+  0, 0, 0, 1, 0x67, 0x42, 0, 0x1f,
+  0, 0, 0, 1, 0x68, 0xce, 6, 0xe2,
+  0, 0, 0, 1, 0x65, 0x88, 0x84
+]).toString('base64');
+
+test('two monitor viewers and a Control handoff cannot replace or stop the other monitor', async () => {
+  const hub = createRemoteHub({
+    env: { ...process.env, LIVEDESK_REMOTE_HUB: '1', REMOTE_HUB_HOST: '127.0.0.1', REMOTE_HUB_PORT: '0' },
+    pairToken: 'monitor-owner-fixture'
+  });
+  let socket;
+  const commands = [];
+  const active = new Map();
+  const waitUntil = async predicate => {
+    const deadline = Date.now() + 2_000;
+    while (Date.now() < deadline) {
+      if (predicate()) return;
+      await new Promise(resolve => setTimeout(resolve, 5));
+    }
+    throw new Error('monitor owner fixture deadline');
+  };
+  try {
+    const status = await hub.start();
+    socket = net.createConnection({ host: '127.0.0.1', port: status.port });
+    await once(socket, 'connect');
+    const send = message => socket.write(`${JSON.stringify(message)}\n`);
+    let welcomed = false;
+    let input = '';
+    let frameSeq = 0;
+    const publishFrame = (streamId, payload, commandId) => {
+      send({ type: 'stream.open', ...payload, streamId, commandId, width: 960, height: 540 });
+      send({ type: 'stream.frame', ...payload, streamId, commandId, frameSeq: ++frameSeq,
+        width: 960, height: 540, mimeType: 'video/h264', isKeyFrame: true, chunkType: 'key', data: keyFrame });
+    };
+    socket.on('data', chunk => {
+      input += chunk.toString('utf8');
+      let newline;
+      while ((newline = input.indexOf('\n')) >= 0) {
+        const line = input.slice(0, newline); input = input.slice(newline + 1);
+        if (!line.trim()) continue;
+        const message = JSON.parse(line);
+        if (message.type === 'welcome') welcomed = true;
+        if (message.type !== 'command') continue;
+        commands.push(message);
+        if (message.command === 'stream.start') {
+          const p = message.payload;
+          for (const [id, owner] of active) {
+            assert.ok(id === p.streamId || owner.monitorIndex !== p.monitorIndex,
+              'same monitor cannot overlap a second native owner');
+          }
+          active.set(p.streamId, { ...p, commandId: message.commandId });
+          send({ type: 'command.result', commandId: message.commandId, result: {
+            stream: true, started: true, ...p, width: 960, height: 540
+          } });
+          publishFrame(p.streamId, p, message.commandId);
+        } else if (message.command === 'stream.stop') {
+          const streamId = message.payload.streamId;
+          if (streamId) active.delete(streamId); else active.clear();
+          send({ type: 'command.result', commandId: message.commandId,
+            result: { stream: true, stopped: true, streamId, stoppedCount: 1 } });
+        }
+      }
+    });
+    send({ type: 'hello', pairToken: 'monitor-owner-fixture', deviceId: 'monitor-device',
+      deviceName: 'Monitor fixture', hostname: 'monitor-fixture', platform: 'darwin', arch: 'arm64',
+      protocol: 'mindexec.remote.agent', protocolVersion: 2,
+      capabilities: { liveStream: true, liveCaptureConcurrency: 'per-monitor', frameProtocol: {}, frameModes: [] } });
+    await waitUntil(() => welcomed);
+    const options = { streamPurpose: 'wall', mode: 'mode3-h264-hw', frameMode: 'mode3-h264-hw',
+      fps: 30, maxWidth: 960, maxHeight: 540, quality: 68, reuseExisting: true, reuseSharedExisting: true };
+    const first = hub.startLiveStream('monitor-device', { ...options, monitorIndex: 0 });
+    assert.equal(first.ok, true);
+    await waitUntil(() => hub.getDeviceLiveFrame('monitor-device', { streamId: first.streamId })?.currentGenerationVerified);
+    const second = hub.startLiveStream('monitor-device', { ...options, monitorIndex: 1 });
+    assert.equal(second.ok, true);
+    assert.notEqual(second.streamId, first.streamId, 'Wall stream ids must include monitor ownership');
+    await waitUntil(() => hub.getDeviceLiveFrame('monitor-device', { streamId: second.streamId })?.currentGenerationVerified);
+    assert.equal(active.size, 2);
+    for (let i = 0; i < 10; i++) {
+      const monitorIndex = i % 2;
+      const original = monitorIndex ? second : first;
+      const reused = hub.startLiveStream('monitor-device', { ...options, monitorIndex, fps: 20 });
+      assert.equal(reused.reused, true);
+      assert.equal(reused.commandId, original.commandId);
+      assert.equal(reused.captureGeneration, original.captureGeneration);
+    }
+    assert.equal(commands.filter(c => c.command === 'stream.start').length, 2);
+    assert.equal(hub.getDeviceLiveFrame('monitor-device', { streamId: first.streamId }).monitorIndex, 0);
+    const controlOptions = { ...options, streamPurpose: 'control', monitorIndex: 1 };
+    const transition = hub.startLiveStream('monitor-device', controlOptions);
+    assert.equal(transition.error, 'CAPTURE_TRANSITION_IN_PROGRESS');
+    await transition.transitionPromise;
+    const control = hub.startLiveStream('monitor-device', controlOptions);
+    assert.equal(control.ok, true);
+    await waitUntil(() => active.has(control.streamId));
+    assert.ok(active.has(first.streamId));
+    assert.ok(!active.has(second.streamId));
+    assert.equal(active.size, 2);
+    const wallWhileOtherControl = hub.startLiveStream('monitor-device', { ...options, monitorIndex: 0 });
+    assert.equal(wallWhileOtherControl.commandId, first.commandId);
+    assert.equal(wallWhileOtherControl.captureGeneration, first.captureGeneration);
+    const selectedStop = hub.stopLiveStream('monitor-device', { streamPurpose: 'wall', monitorIndex: 0 });
+    assert.equal((await selectedStop.stopPromise).captureStopConfirmed, true);
+    assert.ok(active.has(control.streamId));
+    assert.ok(!active.has(first.streamId));
+    const controlStop = hub.stopLiveStream('monitor-device', { streamId: control.streamId, streamPurpose: 'control' });
+    assert.equal((await controlStop.stopPromise).captureStopConfirmed, true);
+    assert.equal(active.size, 0);
+    assert.equal(hub.getLiveCaptureResourceSnapshot('monitor-device').terminal, true);
+  } finally {
+    socket?.destroy();
+    await hub.close();
+  }
+});

package/src/monitor-capture-viewers.test.mjs

@@ -0,0 +1,229 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { mkdtemp } from 'node:fs/promises';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+import WebSocket from 'ws';
+
+async function freePort() {
+  const server = net.createServer();
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  const port = server.address().port;
+  await new Promise(resolve => server.close(resolve));
+  return port;
+}
+
+async function until(predicate, label, timeout = 6000) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    if (await predicate()) return;
+    await new Promise(resolve => setTimeout(resolve, 15));
+  }
+  throw new Error(`Monitor viewers: ${label}`);
+}
+
+test('real frame sockets keep different monitor bindings and release only the last viewer of each monitor', {
+  timeout: 25000
+}, async () => {
+  const httpPort = await freePort();
+  let agentPort = await freePort();
+  while (agentPort === httpPort) agentPort = await freePort();
+  const dataDir = await mkdtemp(path.join(os.tmpdir(), 'vuvodesk-monitor-viewers-'));
+  const base = `http://127.0.0.1:${httpPort}`;
+  const deviceId = 'two-monitor-agent';
+  const pairToken = 'two-monitor-fixture';
+  const root = fileURLToPath(new URL('../../../', import.meta.url));
+  const child = spawn(process.execPath, [fileURLToPath(new URL('./server.js', import.meta.url))], {
+    cwd: root, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, LIVEDESK_DATA_DIR: dataDir,
+      LIVEDESK_HUB_HTTP_HOST: '127.0.0.1', LIVEDESK_HUB_HTTP_PORT: String(httpPort),
+      REMOTE_HUB_HOST: '127.0.0.1', REMOTE_HUB_PORT: String(agentPort),
+      REMOTE_HUB_PAIR_TOKEN: pairToken, REMOTE_HUB_LIVE_CAPTURE_STOP_ACK_TIMEOUT_MS: '750',
+      LIVEDESK_FRAME_STREAM_STOP_GRACE_MS: '25', LIVEDESK_PUBLIC_IP_DISCOVERY_DISABLED: '1',
+      REMOTE_HUB_PUBLIC_IP_DISCOVERY_DISABLED: '1', LIVEDESK_TEST_MODE: '1',
+      LIVEDESK_TEST_LICENSE_PLAN: 'pro', LIVEDESK_UDP_ENABLED: '0' }
+  });
+  const output = [];
+  for (const stream of [child.stdout, child.stderr]) stream.on('data', chunk => {
+    output.push(String(chunk)); while (output.length > 40) output.shift();
+  });
+  const sockets = [];
+  const commands = [];
+  const active = new Map();
+  const media = new Map();
+  const mediaSockets = [];
+  let agent, welcomed = false, sessionId = '', timer, sequence = 0;
+  const send = message => agent.write(`${JSON.stringify(message)}\n`);
+  const frameMessage = owner => ({ type: 'stream.frame', ...owner, frameSeq: ++sequence,
+    width: 960, height: 540, codec: 'h264', mimeType: 'video/h264',
+    isKeyFrame: true, chunkType: 'key', data: Buffer.from([
+      0, 0, 0, 1, 0x67, 0x42, 0, 0x1f, 0, 0, 0, 1, 0x68, 0xce, 6, 0xe2,
+      0, 0, 0, 1, 0x65, 0x88, 0x84
+    ]).toString('base64') });
+  const frame = owner => {
+    const socket = media.get(owner.streamId);
+    if (socket && !socket.destroyed && socket.readyForFrames)
+      socket.write(`${JSON.stringify(frameMessage(owner))}\n`);
+  };
+  async function connectMedia(owner, expectAccepted = true) {
+    const socket = net.createConnection({ host: '127.0.0.1', port: agentPort });
+    mediaSockets.push(socket);
+    const received = [];
+    let pending = '';
+    socket.on('data', data => {
+      pending += String(data);
+      let newline;
+      while ((newline = pending.indexOf('\n')) >= 0) {
+        const raw = pending.slice(0, newline); pending = pending.slice(newline + 1);
+        if (raw.trim()) received.push(JSON.parse(raw));
+      }
+    });
+    await once(socket, 'connect');
+    socket.write(`${JSON.stringify({ type: 'hello', channel: 'frame', deviceId, pairToken,
+      parentSessionId: sessionId, frameOwner: { streamId: owner.streamId, commandId: owner.commandId,
+        captureGeneration: owner.captureGeneration, monitorIndex: owner.monitorIndex } })}\n`);
+    await until(() => received.length > 0, 'monitor channel welcome');
+    if (expectAccepted) {
+      assert.equal(received[0].type, 'welcome');
+      assert.equal(received[0].frameOwner.monitorIndex, owner.monitorIndex);
+      socket.readyForFrames = true;
+      media.set(owner.streamId, socket);
+    } else {
+      assert.equal(received[0].error, 'frame-channel-owner-stale');
+      await until(() => socket.destroyed, 'stale channel rejection');
+    }
+    return socket;
+  }
+  async function connectViewer(monitorIndex, streamPurpose = 'wall') {
+    const ws = new WebSocket(`ws://127.0.0.1:${httpPort}/api/remote/frames/ws?devices=${deviceId}`,
+      { headers: { Origin: base }, perMessageDeflate: false });
+    sockets.push(ws);
+    const messages = [], frames = [];
+    ws.on('message', (data, binary) => {
+      if (binary) {
+        const length = data.readUInt32BE(0);
+        frames.push(JSON.parse(data.subarray(4, 4 + length).toString()));
+      } else messages.push(JSON.parse(String(data)));
+    });
+    await once(ws, 'open');
+    await until(() => messages.some(m => m.type === 'RemoteFrameSocketReady'), 'socket ready');
+    ws.send(JSON.stringify({ type: 'subscribe', deviceIds: [deviceId], autoStartLive: true,
+      allowReadOnlyControlBorrow: true, streamPurpose, monitorIndex,
+      mode: 'mode3-h264-hw', frameMode: 'mode3-h264-hw', fps: 30,
+      maxWidth: 960, maxHeight: 540, quality: 68 }));
+    await until(() => frames.length > 0, `monitor ${monitorIndex} first frame`);
+    return { ws, messages, frames, monitorIndex };
+  }
+  const starts = () => commands.filter(c => c.command === 'stream.start');
+  const close = async viewer => { viewer.ws.close(); await once(viewer.ws, 'close'); };
+  try {
+    await until(async () => {
+      if (child.exitCode !== null) throw new Error(`Hub exited: ${output.join('')}`);
+      try { return (await fetch(`${base}/api/health`)).ok; } catch { return false; }
+    }, 'isolated Hub health', 10000);
+    agent = net.createConnection({ host: '127.0.0.1', port: agentPort });
+    await once(agent, 'connect');
+    let input = '';
+    agent.on('data', chunk => {
+      input += String(chunk);
+      let newline;
+      while ((newline = input.indexOf('\n')) >= 0) {
+        const raw = input.slice(0, newline); input = input.slice(newline + 1);
+        if (!raw.trim()) continue;
+        const message = JSON.parse(raw);
+        if (message.type === 'welcome') { welcomed = true; sessionId = message.sessionId; }
+        if (message.type !== 'command') continue;
+        commands.push(message);
+        if (message.command === 'stream.start') {
+          const owner = { ...message.payload, commandId: message.commandId };
+          active.set(owner.streamId, owner);
+          send({ type: 'command.result', commandId: message.commandId,
+            result: { ...owner, stream: true, started: true } });
+          send({ type: 'stream.open', ...owner, width: 960, height: 540 });
+          void connectMedia(owner).then(() => frame(owner));
+        } else if (message.command === 'stream.stop') {
+          if (message.payload.streamId) {
+            media.get(message.payload.streamId)?.destroy();
+            media.delete(message.payload.streamId);
+            active.delete(message.payload.streamId);
+          } else {
+            for (const socket of media.values()) socket.destroy();
+            media.clear(); active.clear();
+          }
+          send({ type: 'command.result', commandId: message.commandId,
+            result: { stream: true, stopped: true, streamId: message.payload.streamId } });
+        }
+      }
+    });
+    send({ type: 'hello', pairToken, deviceId, deviceName: 'Two monitor fixture', platform: 'darwin',
+      arch: 'arm64', protocol: 'mindexec.remote.agent', protocolVersion: 2,
+      capabilities: { liveStream: true, liveCaptureConcurrency: 'per-monitor', frameProtocol: {}, frameModes: [] } });
+    await until(() => welcomed, 'Agent welcome');
+    timer = setInterval(() => { for (const owner of active.values()) frame(owner); }, 40);
+    const hub = await connectViewer(0);
+    const pwa = await connectViewer(1);
+    const phone = await connectViewer(0);
+    await until(() => hub.frames.length >= 4 && pwa.frames.length >= 4 && phone.frames.length >= 4,
+      'all three viewers receive frames');
+    assert.equal(starts().length, 2, 'same monitor viewer created duplicate capture');
+    const original = [hub.frames[0], pwa.frames[0]];
+    for (const viewer of [hub, pwa, phone]) {
+      assert.ok(viewer.frames.every(f => f.monitorIndex === viewer.monitorIndex), 'cross-monitor frame delivery');
+      assert.ok(viewer.frames.every(f => f.commandId === original[viewer.monitorIndex].commandId), 'capture churn');
+    }
+    const zero = [...active.values()].find(o => o.monitorIndex === 0);
+    const one = [...active.values()].find(o => o.monitorIndex === 1);
+    await connectMedia({ ...zero, captureGeneration: zero.captureGeneration + 100 }, false);
+    assert.equal(media.get(zero.streamId).destroyed, false, 'stale hello replaced current monitor channel');
+    const wrongChannel = media.get(zero.streamId);
+    wrongChannel.write(`${JSON.stringify(frameMessage(one))}\n`);
+    await until(() => wrongChannel.destroyed, 'cross-monitor packet closes only its channel');
+    const otherCount = pwa.frames.length;
+    await until(() => pwa.frames.length >= otherCount + 3, 'healthy monitor survives peer channel failure');
+    await connectMedia(zero);
+    const resumedCount = hub.frames.length;
+    await until(() => hub.frames.length >= resumedCount + 3, 'exact monitor channel reconnects');
+    assert.equal(starts().length, 2, 'transport reconnect restarted native capture');
+    await close(hub);
+    const phoneCount = phone.frames.length;
+    await until(() => phone.frames.length >= phoneCount + 3, 'same-monitor peer continues after close');
+    assert.equal(active.size, 2);
+    await close(pwa);
+    await until(() => active.size === 1, 'last monitor-one viewer stops capture');
+    assert.equal([...active.values()][0].monitorIndex, 0);
+    assert.equal([...active.values()][0].commandId, original[0].commandId);
+    const rejoined = await connectViewer(1);
+    assert.equal(starts().length, 3);
+    assert.notEqual(rejoined.frames[0].captureGeneration, original[1].captureGeneration);
+    assert.equal([...active.values()].find(o => o.monitorIndex === 0).commandId, original[0].commandId);
+    const controller = await connectViewer(1, 'control');
+    await until(() => rejoined.frames.some(f => f.streamPurpose === 'control'), 'same-monitor Wall borrows Control');
+    assert.equal(starts().length, 4);
+    assert.equal([...active.values()].find(o => o.monitorIndex === 0).commandId, original[0].commandId);
+    const borrowedIndex = rejoined.frames.length;
+    await close(controller);
+    await until(() => rejoined.frames.slice(borrowedIndex).some(f => f.streamPurpose === 'wall'),
+      'Control exit restores only its monitor Wall');
+    assert.equal(starts().length, 5);
+    assert.equal([...active.values()].find(o => o.monitorIndex === 0).commandId, original[0].commandId);
+    await close(rejoined);
+    await close(phone);
+    await until(() => active.size === 0, 'final viewer cleanup');
+    assert.equal(commands.filter(c => c.command === 'stream.stop').length, 5);
+  } catch (error) {
+    error.message += `\nIsolated Hub tail: ${output.join('').slice(-2500)}`;
+    throw error;
+  } finally {
+    clearInterval(timer);
+    for (const socket of sockets) socket.terminate();
+    for (const socket of mediaSockets) socket.destroy();
+    agent?.destroy();
+    child.kill();
+    if (child.exitCode === null) await once(child, 'exit');
+  }
+});

package/src/remote-hub.js

@@ -26,6 +26,7 @@ import {
     remoteClipboardContentNeedsFileTransfer
 } from './remote-clipboard-contract.mjs';
 import { liveProfileSatisfiesDemand } from './shared-wall-profile-contract.mjs';
+import { captureOwnersCompete, supportsMonitorCapture } from './monitor-capture-ownership.mjs';
 
 const DEFAULT_REMOTE_HUB_PORT = 5197;
 const DEFAULT_REMOTE_HUB_HOST = '0.0.0.0';
@@ -1888,7 +1889,8 @@ function serializeDevice(device, options = {}) {
         channels: {
             control: !!device.socket && !device.socket.destroyed,
             input: !!device.inputSocket && !device.inputSocket.destroyed,
-            frame: !!device.frameSocket && !device.frameSocket.destroyed,
+            frame: (!!device.frameSocket && !device.frameSocket.destroyed)
+                || [...(device.monitorFrameSockets?.values() || [])].some(socket => !socket.destroyed),
             audio: !!device.audioSocket && !device.audioSocket.destroyed,
             file: !!device.fileSocket && !device.fileSocket.destroyed
         },
@@ -4506,7 +4508,14 @@ export function createRemoteHub(options = {}) {
         existing.socket.destroy();
     }
 
-    function closeFrameSocket(device, reason = 'frame-socket-closed') {
+    function closeFrameSocket(device, reason = 'frame-socket-closed', { legacyOnly = false } = {}) {
+        if (!legacyOnly) {
+            for (const scopedSocket of device?.monitorFrameSockets?.values() || []) {
+                frameSockets.delete(scopedSocket);
+                scopedSocket.destroy();
+            }
+            device?.monitorFrameSockets?.clear();
+        }
         const socket = device?.frameSocket;
         if (!socket) {
             return;
@@ -4630,8 +4639,16 @@ export function createRemoteHub(options = {}) {
             return;
         }
 
-        const device = devices.get(deviceId);
-        if (!device || device.frameSocket !== socket) {
+        const device = devices.get(deviceId);
+        const monitor = socket.__liveDeskMonitorFrameOwner?.monitorIndex;
+        if (Number.isInteger(monitor)) {
+            if (device?.monitorFrameSockets?.get(monitor) === socket) {
+                device.monitorFrameSockets.delete(monitor);
+                emitRemoteEvent('RemoteFrameSocketDisconnected', device, { reason, monitorIndex: monitor });
+            }
+            return;
+        }
+        if (!device || device.frameSocket !== socket) {
             return;
         }
 
@@ -5289,9 +5306,10 @@ export function createRemoteHub(options = {}) {
 
         devices.set(deviceId, device);
         sockets.set(socket, deviceId);
-        writeJsonLine(socket, {
-            type: 'welcome',
-            protocol: REMOTE_AGENT_PROTOCOL,
+        writeJsonLine(socket, {
+            type: 'welcome',
+            monitorFrameChannels: true,
+            protocol: REMOTE_AGENT_PROTOCOL,
             protocolVersion: REMOTE_PROTOCOL_VERSION,
             sessionId,
             deviceId,
@@ -5411,17 +5429,41 @@ export function createRemoteHub(options = {}) {
             emitRemoteEvent('RemoteLegacyMediaSideChannelAccepted', device, { channel: 'frame' });
         }
 
-        closeFrameSocket(device, 'replaced-by-new-frame-socket');
-
-        const now = new Date().toISOString();
-        device.frameSocket = socket;
+        const now = new Date().toISOString();
+        const frameOwner = hello.frameOwner;
+        if (frameOwner !== undefined && frameOwner !== null) {
+            const stream = getDeviceLiveStream(device, frameOwner.streamId);
+            const pending = getPendingLiveStreamDescriptor(stream);
+            const matches = owner => owner?.active === true
+                && owner.commandId === frameOwner.commandId
+                && owner.captureGeneration === frameOwner.captureGeneration
+                && owner.monitorIndex === frameOwner.monitorIndex;
+            if (!supportsMonitorCapture(device) || !parentSessionId
+                || !Number.isInteger(frameOwner.monitorIndex) || frameOwner.monitorIndex < 0 || frameOwner.monitorIndex > 63
+                || !(matches(pending) || matches(stream))) {
+                writeJsonLineAndClose(socket, { type: 'error', error: 'frame-channel-owner-stale' });
+                return null;
+            }
+            if (!device.monitorFrameSockets) device.monitorFrameSockets = new Map();
+            const previous = device.monitorFrameSockets.get(frameOwner.monitorIndex);
+            if (previous) { frameSockets.delete(previous); previous.destroy(); }
+            socket.__liveDeskMonitorFrameOwner = {
+                streamId: stream.streamId, commandId: frameOwner.commandId,
+                captureGeneration: frameOwner.captureGeneration, monitorIndex: frameOwner.monitorIndex
+            };
+            device.monitorFrameSockets.set(frameOwner.monitorIndex, socket);
+        } else {
+            closeFrameSocket(device, 'replaced-by-new-frame-socket', { legacyOnly: true });
+            device.frameSocket = socket;
+        }
         device.frameConnectedAt = now;
         device.frameLastSeenAt = now;
         frameSockets.set(socket, deviceId);
 
         writeJsonLine(socket, {
             type: 'welcome',
-            channel: 'frame',
+            channel: 'frame',
+            frameOwner: socket.__liveDeskMonitorFrameOwner || null,
             protocol: REMOTE_AGENT_PROTOCOL,
             protocolVersion: REMOTE_PROTOCOL_VERSION,
             sessionId: device.sessionId,
@@ -5431,7 +5473,11 @@ export function createRemoteHub(options = {}) {
             serverTime: now
         });
 
-        emitRemoteEvent('RemoteFrameSocketConnected', device);
+        emitRemoteEvent('RemoteFrameSocketConnected', device, {
+            monitorIndex: socket.__liveDeskMonitorFrameOwner?.monitorIndex,
+            streamId: socket.__liveDeskMonitorFrameOwner?.streamId,
+            captureGeneration: socket.__liveDeskMonitorFrameOwner?.captureGeneration
+        });
         return device;
     }
 
@@ -8313,7 +8359,11 @@ export function createRemoteHub(options = {}) {
             return false;
         }
         if (state.inputOnly) return device.inputSocket === socket;
-        if (state.frameOnly) return device.frameSocket === socket;
+        if (state.frameOnly) {
+            const owner = socket.__liveDeskMonitorFrameOwner;
+            return owner ? device.monitorFrameSockets?.get(owner.monitorIndex) === socket
+                : device.frameSocket === socket;
+        }
         if (state.audioOnly) return device.audioSocket === socket;
         if (state.fileOnly) return device.fileSocket === socket;
         return device.socket === socket;
@@ -8327,6 +8377,12 @@ export function createRemoteHub(options = {}) {
         return 'control';
     }
 
+    function frameSocketMatchesPacket(socket, message) {
+        const owner = socket.__liveDeskMonitorFrameOwner;
+        return !owner || (message.streamId === owner.streamId && message.commandId === owner.commandId
+            && message.captureGeneration === owner.captureGeneration && message.monitorIndex === owner.monitorIndex);
+    }
+
     function failCloseMediaSideChannel(socket, state, reason, error = 'media-side-channel-message-not-supported') {
         const device = state?.device;
         if (device) {
@@ -8375,6 +8431,10 @@ export function createRemoteHub(options = {}) {
             socket.destroy();
             return;
         }
+        if (state.frameOnly && !frameSocketMatchesPacket(socket, header)) {
+            failCloseMediaSideChannel(socket, state, 'frame-channel-owner-mismatch');
+            return;
+        }
 
         const hasDeclaredFrameKind = header.frameKind !== undefined
             && header.frameKind !== null
@@ -8778,6 +8838,10 @@ export function createRemoteHub(options = {}) {
                 case 'thumbnail.frame':
                 case 'stream.open':
                 case 'stream.frame': {
+                    if (!frameSocketMatchesPacket(socket, message)) {
+                        failCloseMediaSideChannel(socket, state, 'frame-channel-owner-mismatch');
+                        return;
+                    }
                     const receivedAt = new Date().toISOString();
                     device.counters.messagesReceived += 1;
                     device.frameLastSeenAt = receivedAt;
@@ -11182,10 +11246,10 @@ export function createRemoteHub(options = {}) {
         pruneDeviceLiveStreams(device);
     }
 
-    function makeStableLiveStreamId(deviceId, purpose = 'wall') {
+    function makeStableLiveStreamId(deviceId, purpose = 'wall', monitorIndex = null) {
         const hash = crypto.createHash('sha1').update(String(deviceId || 'device')).digest('hex').slice(0, 16);
         const role = safeString(purpose, 24).toLowerCase().replace(/[^a-z0-9_-]+/g, '-') || 'wall';
-        return `${role}-${hash}`;
+        return `${role}-${hash}${Number.isInteger(monitorIndex) ? `-m${monitorIndex}` : ''}`;
     }
 
     function getActiveLiveStreams(device) {
@@ -11260,11 +11324,14 @@ export function createRemoteHub(options = {}) {
         return result;
     }
 
-    function claimSingleLiveCapture(deviceId, device, streamId, streamPurpose) {
-        const purpose = safeString(streamPurpose, 24).toLowerCase() || 'wall';
-        const activeControlStream = getActiveControlStream(device);
-        if (purpose !== 'control'
-            && activeControlStream) {
+    function claimSingleLiveCapture(deviceId, device, streamId, streamPurpose, monitorIndex) {
+        const purpose = safeString(streamPurpose, 24).toLowerCase() || 'wall';
+        const perMonitor = supportsMonitorCapture(device);
+        const requestedOwner = { monitorIndex, streamPurpose: purpose };
+        const activeControlStream = getActiveControlStream(device);
+        if (purpose !== 'control'
+            && activeControlStream
+            && captureOwnersCompete(activeControlStream, requestedOwner, perMonitor)) {
             return {
                 ok: false,
                 error: 'CONTROL_CAPTURE_OWNS_DEVICE',
@@ -11276,10 +11343,11 @@ export function createRemoteHub(options = {}) {
         }
 
         const competingStreams = getActiveLiveStreams(device)
-            .filter(stream => (
-                stream.streamId !== streamId
-                || (safeString(stream?.streamPurpose, 24).toLowerCase() || 'wall') !== purpose
-            ));
+            .filter(stream => (
+                (stream.streamId !== streamId
+                    || (safeString(stream?.streamPurpose, 24).toLowerCase() || 'wall') !== purpose)
+                && captureOwnersCompete(stream, requestedOwner, perMonitor)
+            ));
         let stopIssued = false;
         for (const competingStream of competingStreams) {
             if (competingStream.stopPending === true
@@ -11523,7 +11591,7 @@ export function createRemoteHub(options = {}) {
 
     function readOnlyControlPresentationBorrowResult(device, normalized, options = {}) {
         const borrowed = resolveReadOnlyControlPresentationBorrow({
-            device,
+            device: { sessionId: device.sessionId, activeLiveStream: getActiveControlStream(device) },
             liveOptions: {
                 allowReadOnlyControlBorrow: options.allowReadOnlyControlBorrow === true,
                 streamPurpose: normalized.streamPurpose,
@@ -11582,7 +11650,8 @@ export function createRemoteHub(options = {}) {
             const { fps, maxWidth, maxHeight, quality, monitorIndex, transfer, streamPurpose } = normalized;
             const borrowedControl = readOnlyControlPresentationBorrowResult(device, normalized, options);
             if (borrowedControl) return { ...borrowedControl, synthetic: true };
-            const streamId = safeString(options.streamId, 128) || makeStableLiveStreamId(deviceId, streamPurpose);
+            const streamId = safeString(options.streamId, 128) || makeStableLiveStreamId(
+                deviceId, streamPurpose, streamPurpose === 'wall' && supportsMonitorCapture(device) ? monitorIndex : null);
             if (!reserveDeviceLiveStreamDescriptor(device, streamId)) {
                 return {
                     ok: false,
@@ -11590,7 +11659,7 @@ export function createRemoteHub(options = {}) {
                     descriptorCap: LIVE_STREAM_DESCRIPTOR_CAP
                 };
             }
-            const captureClaim = claimSingleLiveCapture(deviceId, device, streamId, streamPurpose);
+            const captureClaim = claimSingleLiveCapture(deviceId, device, streamId, streamPurpose, monitorIndex);
             if (!captureClaim.ok) return captureClaim;
             const activeLiveStream = getDeviceLiveStream(device, streamId);
             const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
@@ -11706,7 +11775,9 @@ export function createRemoteHub(options = {}) {
         }
         const borrowedControl = readOnlyControlPresentationBorrowResult(device, normalized, options);
         if (borrowedControl) return borrowedControl;
-        const streamId = safeString(options.streamId, 128) || makeStableLiveStreamId(deviceId, streamPurpose);
+        const streamId = safeString(options.streamId, 128) || makeStableLiveStreamId(
+            deviceId, streamPurpose,
+            supportsMonitorCapture(device) && streamPurpose === 'wall' ? monitorIndex : null);
         if (!reserveDeviceLiveStreamDescriptor(device, streamId)) {
             return {
                 ok: false,
@@ -11714,7 +11785,7 @@ export function createRemoteHub(options = {}) {
                 descriptorCap: LIVE_STREAM_DESCRIPTOR_CAP
             };
         }
-        const captureClaim = claimSingleLiveCapture(deviceId, device, streamId, streamPurpose);
+        const captureClaim = claimSingleLiveCapture(deviceId, device, streamId, streamPurpose, monitorIndex);
         if (!captureClaim.ok) return captureClaim;
         const activeLiveStream = getDeviceLiveStream(device, streamId);
         const pendingDescriptor = getPendingLiveStreamDescriptor(activeLiveStream);
@@ -12018,10 +12089,15 @@ export function createRemoteHub(options = {}) {
         }
         const stopAll = options.stopAll === true;
         const streamPurpose = safeString(options.streamPurpose || options.purpose, 24).toLowerCase();
-        const requestedStreamId = safeString(options.streamId, 128);
-        const purposeStreams = !stopAll && !requestedStreamId && streamPurpose && device
-            ? getActiveLiveStreams(device).filter(stream =>
-                (safeString(stream?.streamPurpose, 24).toLowerCase() || 'wall') === streamPurpose)
+        const requestedStreamId = safeString(options.streamId, 128);
+        const selectedMonitor = parseExactLiveStreamMonitorIndex(options.monitorIndex);
+        if (Object.prototype.hasOwnProperty.call(options, 'monitorIndex') && selectedMonitor === null) {
+            return { ok: false, error: 'LIVE_STREAM_STOP_MONITOR_INVALID' };
+        }
+        const purposeStreams = !stopAll && !requestedStreamId && streamPurpose && device
+            ? getActiveLiveStreams(device).filter(stream =>
+                (safeString(stream?.streamPurpose, 24).toLowerCase() || 'wall') === streamPurpose
+                && (selectedMonitor === null || stream.monitorIndex === selectedMonitor))
             : [];
         if (purposeStreams.length > 1) {
             return {
@@ -12033,8 +12109,9 @@ export function createRemoteHub(options = {}) {
         }
         const retainedPurposeStream = purposeStreams[0]
             || (!stopAll && !requestedStreamId && streamPurpose && device
-                ? [...ensureDeviceLiveStreams(device).values()].reverse().find(stream =>
-                    (safeString(stream?.streamPurpose, 24).toLowerCase() || 'wall') === streamPurpose)
+                ? [...ensureDeviceLiveStreams(device).values()].reverse().find(stream =>
+                    (safeString(stream?.streamPurpose, 24).toLowerCase() || 'wall') === streamPurpose
+                    && (selectedMonitor === null || stream.monitorIndex === selectedMonitor))
                 : null);
         if (!stopAll
             && !requestedStreamId
@@ -12056,8 +12133,11 @@ export function createRemoteHub(options = {}) {
                 || safeString(retainedPurposeStream?.streamId, 128)
                 || device?.activeLiveStream?.streamId
                 || '';
-        const streamState = getDeviceLiveStream(device, streamId);
-        const pendingStreamState = getPendingLiveStreamDescriptor(streamState);
+        const streamState = getDeviceLiveStream(device, streamId);
+        const pendingStreamState = getPendingLiveStreamDescriptor(streamState);
+        if (selectedMonitor !== null && streamState && streamState.monitorIndex !== selectedMonitor) {
+            return { ok: false, error: 'LIVE_STREAM_STOP_MONITOR_MISMATCH', streamId };
+        }
         const expectedCommandId = safeString(options.expectedCommandId, 128);
         const expectedCaptureGeneration = Number(options.expectedCaptureGeneration || 0);
         const expectedSessionId = safeString(options.expectedSessionId, 160);
@@ -12874,12 +12954,20 @@ export function createRemoteHub(options = {}) {
         return stopResult;
     }
 
-    function getDeviceLiveFrame(deviceId, options = {}) {
-        const device = devices.get(String(deviceId || ''));
-        return serializeRemoteFrame(device?.latestLiveFrame, device?.deviceId, 'live', {
-            includeDataUrl: options.includeDataUrl === true
-        });
-    }
+    function getDeviceLiveFrame(deviceId, options = {}) {
+        const device = devices.get(String(deviceId || ''));
+        const frame = options.streamId
+            ? getDeviceLiveStream(device, options.streamId)?.latestFrame
+            : device?.latestLiveFrame;
+        return serializeRemoteFrame(frame, device?.deviceId, 'live', {
+            includeDataUrl: options.includeDataUrl === true
+        });
+    }
+
+    function getDeviceLiveStreamSnapshot(deviceId, streamId) {
+        const device = devices.get(String(deviceId || ''));
+        return serializeActiveLiveStream(getDeviceLiveStream(device, streamId), device?.deviceId);
+    }
 
     function getDeviceThumbnail(deviceId, options = {}) {
         const device = devices.get(String(deviceId || ''));
@@ -13054,7 +13142,8 @@ export function createRemoteHub(options = {}) {
         startAudioStream,
         stopAudioStream,
         getLiveCaptureResourceSnapshot,
-        getDeviceLiveFrame,
+        getDeviceLiveFrame,
+        getDeviceLiveStreamSnapshot,
         getDeviceThumbnail,
         getFramePayload,
         handleUdpFrame,

package/src/server.js

@@ -368,7 +368,9 @@ function readRemoteLiveStreamEventPurpose(event) {
   const explicitPurpose = String(event?.streamPurpose || '').trim().toLowerCase();
   if (explicitPurpose) return explicitPurpose;
   const commandId = String(event?.commandId || '').trim();
-  const activeStream = event?.device?.activeLiveStream;
+  const activeStream = remoteHub.getDeviceLiveStreamSnapshot(
+    event?.deviceId || event?.device?.deviceId, event?.streamId
+  );
   if (!commandId || !activeStream) return '';
   const pendingDescriptor = activeStream.pendingDescriptor;
   if (String(pendingDescriptor?.commandId || '').trim() === commandId) {
@@ -441,7 +443,7 @@ function handleRemoteHubEvent(type, event) {
     const liveStreamEventDeviceId = String(event?.deviceId || event?.device?.deviceId || '').trim();
     const liveStreamEventPurpose = readRemoteLiveStreamEventPurpose(event);
     if (type === 'RemoteLiveStreamOpened' && liveStreamEventPurpose === 'wall') {
-      const committedOwner = event?.device?.activeLiveStream;
+      const committedOwner = remoteHub.getDeviceLiveStreamSnapshot(liveStreamEventDeviceId, event?.streamId);
       if (String(committedOwner?.commandId || '').trim() === String(event?.commandId || '').trim()
         && Number(committedOwner?.captureGeneration || 0) === Number(event?.captureGeneration || 0)) {
         rebindSharedWallSubscribersToOwner(liveStreamEventDeviceId, {
@@ -474,7 +476,7 @@ function handleRemoteHubEvent(type, event) {
   }
   if (type === 'RemoteLiveStreamRestartFailed') {
     const failedDeviceId = String(event?.deviceId || event?.device?.deviceId || '').trim();
-    const retainedOwner = event?.device?.activeLiveStream;
+    const retainedOwner = remoteHub.getDeviceLiveStreamSnapshot(failedDeviceId, event?.streamId);
     if (String(retainedOwner?.streamPurpose || '').trim().toLowerCase() === 'wall') {
       const rebound = rebindSharedWallSubscribersToOwner(failedDeviceId, {
         ...retainedOwner,
@@ -2616,6 +2618,7 @@ function hasOtherFrameStreamOwner(ws, deviceId, streamId, streamPurpose = '') {
   if (!streamId) {
     return false;
   }
+  const ownerMonitor = remoteHub.getDeviceLiveStreamSnapshot(deviceId, streamId)?.monitorIndex;
   for (const candidate of frameClients) {
     if (candidate === ws || candidate.readyState !== candidate.OPEN) {
       continue;
@@ -2637,8 +2640,10 @@ function hasOtherFrameStreamOwner(ws, deviceId, streamId, streamPurpose = '') {
     // socket's close cleanup stop the replacement generation in that window.
     if (candidate.liveDeskAutoStart === true
       && candidate.liveDeskDeviceIds instanceof Set
-      && candidate.liveDeskDeviceIds.has(deviceId)
-      && String(candidate.liveDeskLiveOptions?.streamPurpose || '') === String(streamPurpose || '')) {
+      && candidate.liveDeskDeviceIds.has(deviceId)
+      && String(candidate.liveDeskLiveOptions?.streamPurpose || '') === String(streamPurpose || '')
+      && Number.isInteger(ownerMonitor)
+      && frameClientMonitorIndex(candidate, deviceId) === ownerMonitor) {
       return true;
     }
   }
@@ -4041,7 +4046,7 @@ function startFrameSubscriptionLive(
       );
     }
     if (result?.ok) {
-      const activeStream = device?.activeLiveStream;
+      const activeStream = remoteHub.getDeviceLiveStreamSnapshot(deviceId, result.streamId);
       const retainWallOwner = shouldRetainWallOwnerUntilPendingStartCommits(
         result,
         activeStream