@livedesk/hub 0.1.59 → 0.1.61

package/src/live-stream-monitor-contract.js

@@ -10,7 +10,7 @@ export function parseExactLiveStreamMonitorIndex(value) {
         : null;
 }
 
-export function isReusedLiveStreamFrameReady(result, activeStream, expectedBinding) {
+export function isReusedLiveStreamFrameReady(result, activeStream, expectedBinding) {
     const expectedMonitorIndex = parseExactLiveStreamMonitorIndex(expectedBinding?.monitorIndex);
     const activeMonitorIndex = parseExactLiveStreamMonitorIndex(activeStream?.monitorIndex);
     const latestFrame = activeStream?.latestFrame;
@@ -34,5 +34,197 @@ export function isReusedLiveStreamFrameReady(result, activeStream, expectedBindi
         && Number(latestFrame?.captureGeneration || 0) === expectedCaptureGeneration
         && expectedMonitorIndex !== null
         && activeMonitorIndex === expectedMonitorIndex
-        && frameMonitorIndex === expectedMonitorIndex;
-}
+        && frameMonitorIndex === expectedMonitorIndex;
+}
+
+export const READ_ONLY_CONTROL_PRESENTATION_MAX_IDLE_MS = 3_000;
+export const READ_ONLY_CONTROL_STOP_RECONCILE_GRACE_MS = 250;
+
+function normalizedPurpose(value) {
+    return String(value || '').trim().toLowerCase();
+}
+
+function positiveInteger(value) {
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : 0;
+}
+
+/**
+ * Own exactly one short stop-reconcile timer per device. A replacement Control
+ * transition cancels that timer before a PWA Wall can claim the released
+ * native capture; its Ready event then rebinds observers immediately.
+ */
+export function createReadOnlyControlPresentationReconcileCoordinator({
+    onReconcile,
+    graceMs = READ_ONLY_CONTROL_STOP_RECONCILE_GRACE_MS,
+    setTimeoutFn = setTimeout,
+    clearTimeoutFn = clearTimeout
+} = {}) {
+    if (typeof onReconcile !== 'function') {
+        throw new TypeError('onReconcile must be a function');
+    }
+    if (typeof setTimeoutFn !== 'function' || typeof clearTimeoutFn !== 'function') {
+        throw new TypeError('timer functions must be callable');
+    }
+    const normalizedGraceMs = Number(graceMs);
+    if (!Number.isFinite(normalizedGraceMs)
+        || normalizedGraceMs < 1
+        || normalizedGraceMs > 5_000) {
+        throw new RangeError('graceMs must be between 1 and 5000 milliseconds');
+    }
+
+    const pendingByDeviceId = new Map();
+    let closed = false;
+
+    function normalizeDeviceId(deviceId) {
+        return String(deviceId || '').trim();
+    }
+
+    function cancelForControlTransition(deviceId) {
+        const normalizedDeviceId = normalizeDeviceId(deviceId);
+        const owner = normalizedDeviceId ? pendingByDeviceId.get(normalizedDeviceId) : null;
+        if (!owner) return false;
+        pendingByDeviceId.delete(normalizedDeviceId);
+        clearTimeoutFn(owner.timer);
+        return true;
+    }
+
+    function scheduleAfterConfirmedStop(deviceId) {
+        const normalizedDeviceId = normalizeDeviceId(deviceId);
+        if (closed || !normalizedDeviceId || pendingByDeviceId.has(normalizedDeviceId)) {
+            return false;
+        }
+        const owner = { timer: null };
+        pendingByDeviceId.set(normalizedDeviceId, owner);
+        try {
+            owner.timer = setTimeoutFn(() => {
+                if (closed || pendingByDeviceId.get(normalizedDeviceId) !== owner) {
+                    return;
+                }
+                pendingByDeviceId.delete(normalizedDeviceId);
+                onReconcile(normalizedDeviceId);
+            }, normalizedGraceMs);
+            owner.timer?.unref?.();
+        } catch (error) {
+            if (pendingByDeviceId.get(normalizedDeviceId) === owner) {
+                pendingByDeviceId.delete(normalizedDeviceId);
+            }
+            throw error;
+        }
+        return true;
+    }
+
+    function reconcileReadyControl(deviceId) {
+        const normalizedDeviceId = normalizeDeviceId(deviceId);
+        if (closed || !normalizedDeviceId) return false;
+        cancelForControlTransition(normalizedDeviceId);
+        onReconcile(normalizedDeviceId);
+        return true;
+    }
+
+    function close() {
+        if (closed) return;
+        closed = true;
+        for (const owner of pendingByDeviceId.values()) {
+            clearTimeoutFn(owner.timer);
+        }
+        pendingByDeviceId.clear();
+    }
+
+    return {
+        scheduleAfterConfirmedStop,
+        cancelForControlTransition,
+        reconcileReadyControl,
+        close,
+        getPendingCount: () => pendingByDeviceId.size
+    };
+}
+
+/**
+ * Bind a Wall presentation observer to an already healthy Control encoder.
+ * This returns metadata only: it never starts, stops, or replaces native work.
+ */
+export function resolveReadOnlyControlPresentationBorrow({
+    device,
+    liveOptions,
+    monitorIndex,
+    nowEpochMs = Date.now()
+} = {}) {
+    if (liveOptions?.allowReadOnlyControlBorrow !== true
+        || normalizedPurpose(liveOptions?.streamPurpose) !== 'wall') {
+        return null;
+    }
+
+    const active = device?.activeLiveStream;
+    const latest = active?.latestFrame;
+    const sessionId = String(device?.sessionId || '').trim();
+    const streamId = String(active?.streamId || '').trim();
+    const commandId = String(active?.commandId || '').trim();
+    const captureGeneration = positiveInteger(active?.captureGeneration);
+    const activeMonitorIndex = parseExactLiveStreamMonitorIndex(active?.monitorIndex);
+    const requestedMonitorIndex = parseExactLiveStreamMonitorIndex(monitorIndex);
+    const frameMode = String(active?.frameMode || active?.mode || '').trim().toLowerCase();
+    const requestedFrameMode = String(liveOptions?.frameMode || liveOptions?.mode || '').trim().toLowerCase();
+    const lastFrameAtEpochMs = Date.parse(String(active?.lastFrameAt || ''));
+    const currentEpochMs = Number(nowEpochMs);
+    const frameIdleMs = Number.isFinite(lastFrameAtEpochMs) && Number.isFinite(currentEpochMs)
+        ? Math.max(0, currentEpochMs - lastFrameAtEpochMs)
+        : Number.POSITIVE_INFINITY;
+    const latestMonitorIndex = parseExactLiveStreamMonitorIndex(latest?.monitorIndex);
+
+    if (active?.active !== true
+        || active?.open !== true
+        || active?.stopPending === true
+        || !!String(active?.stopCommandId || '').trim()
+        || !!String(active?.pendingDescriptor?.commandId || '').trim()
+        || normalizedPurpose(active?.streamPurpose) !== 'control'
+        || frameMode !== 'mode3-h264-hw'
+        || requestedFrameMode !== 'mode3-h264-hw'
+        || !sessionId
+        || !streamId
+        || !commandId
+        || captureGeneration <= 0
+        || requestedMonitorIndex === null
+        || activeMonitorIndex !== requestedMonitorIndex
+        || active?.readyFrameReceived !== true
+        || Number(active?.framesReceived || 0) <= 0
+        || frameIdleMs > READ_ONLY_CONTROL_PRESENTATION_MAX_IDLE_MS
+        || latest?.currentGenerationVerified !== true
+        || String(latest?.sessionId || '') !== sessionId
+        || String(latest?.streamId || '') !== streamId
+        || String(latest?.commandId || '') !== commandId
+        || Number(latest?.captureGeneration || 0) !== captureGeneration
+        || latestMonitorIndex !== activeMonitorIndex
+        || normalizedPurpose(latest?.streamPurpose) !== 'control') {
+        return null;
+    }
+
+    return {
+        ok: true,
+        commandId,
+        sessionId,
+        streamId,
+        streamPurpose: 'control',
+        fps: positiveInteger(active?.fps) || 1,
+        mode: String(active?.mode || active?.frameMode || 'mode3-h264-hw'),
+        frameMode: 'mode3-h264-hw',
+        monitorIndex: activeMonitorIndex,
+        captureGeneration,
+        ready: true,
+        reused: true,
+        readOnlyControlBorrow: true,
+        presentationPurpose: 'wall',
+        requestedProfile: {
+            fps: Number(liveOptions?.fps || 0),
+            maxWidth: Number(liveOptions?.maxWidth || 0),
+            maxHeight: Number(liveOptions?.maxHeight || 0),
+            quality: Number(liveOptions?.quality || 0)
+        },
+        effectiveProfile: {
+            fps: Number(active?.fps || 0),
+            maxWidth: Number(active?.maxWidth || 0),
+            maxHeight: Number(active?.maxHeight || 0),
+            quality: Number(active?.quality || 0)
+        }
+    };
+}

package/src/remote-hub.js

@@ -9,7 +9,10 @@ import {
     isSecureDirectHandshakeStart
 } from '../../runtime-core/src/direct-secure-transport.js';
 import { createHubRelayControl } from './transport/relay-hub-control.js';
-import { parseExactLiveStreamMonitorIndex } from './live-stream-monitor-contract.js';
+import {
+    parseExactLiveStreamMonitorIndex,
+    resolveReadOnlyControlPresentationBorrow
+} from './live-stream-monitor-contract.js';
 import {
     BoundedSegmentedBuffer,
     createBoundedAgentBinaryIngressLane
@@ -63,9 +66,9 @@ const RECENT_THUMBNAIL_FRAME_CACHE_MAX_BYTES = 2 * 1024 * 1024;
 const RECENT_LIVE_FRAME_CACHE_MAX_BYTES = 8 * 1024 * 1024;
 const LIVE_STREAM_PENDING_REUSE_MS = 5000;
 const LIVE_STREAM_REPLACEMENT_PENDING_MS = 7000;
-const LIVE_STREAM_MIN_FRESH_MS = 3000;
-const LIVE_STREAM_MAX_FRESH_MS = 12000;
-const DEFAULT_REMOTE_INPUT_ACK_TIMEOUT_MS = 5000;
+const LIVE_STREAM_MIN_FRESH_MS = 3000;
+const LIVE_STREAM_MAX_FRESH_MS = 12000;
+const DEFAULT_REMOTE_INPUT_ACK_TIMEOUT_MS = 5000;
 // RemoteFast owns a shared 7s native stop deadline. Keep four seconds for a
 // priority command.result to cross either Direct or encrypted Relay transport.
 const DEFAULT_LIVE_CAPTURE_STOP_ACK_TIMEOUT_MS = 11000;
@@ -2303,7 +2306,7 @@ export class RemoteHubWebSocketAgentSocket {
     }
 }
 
-export function createRemoteHub(options = {}) {
+export function createRemoteHub(options = {}) {
     const env = options.env || process.env;
     const transportDiagnosticCommandTimeoutMs = clampNumber(
         options.transportDiagnosticCommandTimeoutMs,
@@ -10638,7 +10641,7 @@ export function createRemoteHub(options = {}) {
                 === normalized.streamPurpose;
     }
 
-    function sharedLiveProfileResult(device, activeLiveStream, normalized, extra = {}) {
+    function sharedLiveProfileResult(device, activeLiveStream, normalized, extra = {}) {
         return {
             ok: true,
             commandId: activeLiveStream.commandId,
@@ -10667,9 +10670,40 @@ export function createRemoteHub(options = {}) {
             },
             ...extra
         };
-    }
-
-    function startLiveStream(deviceId, options = {}) {
+    }
+
+    function readOnlyControlPresentationBorrowResult(device, normalized, options = {}) {
+        const borrowed = resolveReadOnlyControlPresentationBorrow({
+            device,
+            liveOptions: {
+                allowReadOnlyControlBorrow: options.allowReadOnlyControlBorrow === true,
+                streamPurpose: normalized.streamPurpose,
+                mode: normalized.transfer.mode,
+                frameMode: normalized.transfer.frameMode,
+                fps: normalized.fps,
+                maxWidth: normalized.maxWidth,
+                maxHeight: normalized.maxHeight,
+                quality: normalized.quality
+            },
+            monitorIndex: normalized.monitorIndex
+        });
+        if (!borrowed) {
+            return null;
+        }
+        emitRemoteEvent('RemoteLiveStreamControlPresentationBorrowed', device, {
+            streamId: borrowed.streamId,
+            commandId: borrowed.commandId,
+            captureGeneration: borrowed.captureGeneration,
+            streamPurpose: borrowed.streamPurpose,
+            presentationPurpose: borrowed.presentationPurpose,
+            monitorIndex: borrowed.monitorIndex,
+            requestedProfile: borrowed.requestedProfile,
+            effectiveProfile: borrowed.effectiveProfile
+        });
+        return borrowed;
+    }
+
+    function startLiveStream(deviceId, options = {}) {
         const device = devices.get(String(deviceId || ''));
         const denied = policyError(device);
         if (denied) return { ok: false, error: denied };
@@ -10693,11 +10727,13 @@ export function createRemoteHub(options = {}) {
             }
 
             const now = new Date().toISOString();
-            const normalized = normalizeLiveStreamStartOptions({ fps: 2, ...options, platform: device.platform });
-            const modePolicyError = liveStreamModePolicyError(normalized);
-            if (modePolicyError) return { ok: false, error: modePolicyError };
-            const { fps, maxWidth, maxHeight, quality, monitorIndex, transfer, streamPurpose } = normalized;
-            const streamId = safeString(options.streamId, 128) || makeStableLiveStreamId(deviceId, streamPurpose);
+            const normalized = normalizeLiveStreamStartOptions({ fps: 2, ...options, platform: device.platform });
+            const modePolicyError = liveStreamModePolicyError(normalized);
+            if (modePolicyError) return { ok: false, error: modePolicyError };
+            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);
             if (!reserveDeviceLiveStreamDescriptor(device, streamId)) {
                 return {
                     ok: false,
@@ -10776,12 +10812,13 @@ export function createRemoteHub(options = {}) {
                 monitorIndex,
                 fps
             });
-            emitRemoteEvent('RemoteLiveStreamStarted', device, {
-                streamId,
-                commandId,
-                fps,
-                mode: transfer.mode,
-                synthetic: true
+            emitRemoteEvent('RemoteLiveStreamStarted', device, {
+                streamId,
+                commandId,
+                streamPurpose,
+                fps,
+                mode: transfer.mode,
+                synthetic: true
             });
             return {
                 ok: true,
@@ -10811,14 +10848,16 @@ export function createRemoteHub(options = {}) {
         const modePolicyError = liveStreamModePolicyError(normalized);
         if (modePolicyError) return { ok: false, error: modePolicyError };
         const { fps, maxWidth, maxHeight, quality, monitorIndex, transfer, streamPurpose } = normalized;
-        if (deviceExplicitlyRejectsFrameMode(device, transfer.frameMode)) {
-            return {
-                ok: false,
-                error: 'device-frame-mode-unavailable',
-                frameMode: transfer.frameMode
-            };
-        }
-        const streamId = safeString(options.streamId, 128) || makeStableLiveStreamId(deviceId, streamPurpose);
+        if (deviceExplicitlyRejectsFrameMode(device, transfer.frameMode)) {
+            return {
+                ok: false,
+                error: 'device-frame-mode-unavailable',
+                frameMode: transfer.frameMode
+            };
+        }
+        const borrowedControl = readOnlyControlPresentationBorrowResult(device, normalized, options);
+        if (borrowedControl) return borrowedControl;
+        const streamId = safeString(options.streamId, 128) || makeStableLiveStreamId(deviceId, streamPurpose);
         if (!reserveDeviceLiveStreamDescriptor(device, streamId)) {
             return {
                 ok: false,
@@ -10875,9 +10914,9 @@ export function createRemoteHub(options = {}) {
         }
         const commandId = safeString(options.commandId, 128) || crypto.randomUUID();
         const restartToken = safeString(options.restartToken, 128);
-        if (activeLiveStream
-            && options.forceRestart === true
-            && restartToken
+        if (activeLiveStream
+            && options.forceRestart === true
+            && restartToken
             && safeString(activeLiveStream.restartToken, 128) === restartToken
             && liveStreamMatchesOptions(activeLiveStream, normalized)
             && liveStreamIsReusable(activeLiveStream)) {
@@ -10900,11 +10939,11 @@ export function createRemoteHub(options = {}) {
                 captureGeneration: Number(activeLiveStream.captureGeneration || 0),
                 ready: liveStreamHasCurrentFrame(activeLiveStream),
                 pending: activeLiveStream.open !== true,
-                reused: true
-            };
-        }
-        if (activeLiveStream
-            && options.forceRestart !== true
+                reused: true
+            };
+        }
+        if (activeLiveStream
+            && options.forceRestart !== true
             && options.reuseExisting === true
             && liveStreamMatchesOptions(activeLiveStream, normalized)
             && liveStreamIsReusable(activeLiveStream)) {
@@ -11084,11 +11123,12 @@ export function createRemoteHub(options = {}) {
             setDeviceLiveStream(device, nextStreamState);
         }
         device.counters.liveStreamsStarted += 1;
-        emitRemoteEvent('RemoteLiveStreamStarted', device, {
-            streamId,
-            commandId,
-            previousCommandId,
-            pending: replacingActiveStream,
+        emitRemoteEvent('RemoteLiveStreamStarted', device, {
+            streamId,
+            commandId,
+            streamPurpose,
+            previousCommandId,
+            pending: replacingActiveStream,
             fps,
             mode: transfer.mode,
             frameMode: transfer.frameMode,
@@ -11277,11 +11317,13 @@ export function createRemoteHub(options = {}) {
                     captureLiveStreamStopOwner(device, streamState, commandId));
             }
             device.counters.liveStreamsStopped += 1;
-            emitRemoteEvent('RemoteLiveStreamStopped', device, {
-                streamId,
-                commandId,
-                synthetic: true
-            });
+            emitRemoteEvent('RemoteLiveStreamStopped', device, {
+                streamId,
+                commandId,
+                streamPurpose: safeString(streamState?.streamPurpose || streamPurpose, 24).toLowerCase() || 'wall',
+                captureStopConfirmed: true,
+                synthetic: true
+            });
             return { ok: true, commandId, streamId, synthetic: true };
         }
 
@@ -11316,7 +11358,7 @@ export function createRemoteHub(options = {}) {
             : (streamState ? [streamState] : []);
         const stopRequestedAt = new Date().toISOString();
         const targetOwners = [];
-        for (const targetStream of targetStreams) {
+        for (const targetStream of targetStreams) {
             const pendingTarget = getPendingLiveStreamDescriptor(targetStream);
             const targetDescriptor = pendingTarget || targetStream;
             const targetOwnerKind = pendingTarget ? 'pending' : 'active';
@@ -11340,10 +11382,19 @@ export function createRemoteHub(options = {}) {
                 targetOwners.push({
                     owner: targetOwner,
                     ownerKind: targetOwnerKind
-                });
-            }
-        }
-        const stopPromise = acknowledgementPromise.then(acknowledgement => {
+                });
+            }
+        }
+        const stoppedStreamPurposes = new Set(
+            targetOwners
+                .map(targetRecord => safeString(targetRecord.owner?.streamPurpose, 24).toLowerCase())
+                .filter(Boolean));
+        const stoppedStreamPurpose = stoppedStreamPurposes.size === 1
+            ? [...stoppedStreamPurposes][0]
+            : targetOwners.length === 0
+                ? safeString(streamState?.streamPurpose || streamPurpose, 24).toLowerCase()
+                : '';
+        const stopPromise = acknowledgementPromise.then(acknowledgement => {
             const currentDevice = devices.get(String(deviceId || ''));
             const stopReported = acknowledgement.result?.stream === true
                 && acknowledgement.result?.stopped === true;
@@ -11411,11 +11462,12 @@ export function createRemoteHub(options = {}) {
                 if (captureStopConfirmed
                     && (targetOwners.length === 0 || appliedOwnerCount > 0)) {
                     currentDevice.counters.liveStreamsStopped += 1;
-                    emitRemoteEvent('RemoteLiveStreamStopped', currentDevice, {
-                        streamId,
-                        commandId,
-                        appliedOwnerCount,
-                        captureStopConfirmed: true
+                    emitRemoteEvent('RemoteLiveStreamStopped', currentDevice, {
+                        streamId,
+                        commandId,
+                        streamPurpose: stoppedStreamPurpose,
+                        appliedOwnerCount,
+                        captureStopConfirmed: true
                     });
                 } else if (!captureStopConfirmed && appliedOwnerCount > 0) {
                     emitRemoteEvent('RemoteLiveStreamStopUnconfirmed', currentDevice, {