@livedesk/hub 0.1.59 → 0.1.64

package/src/live-capture-transition-retry.mjs

@@ -125,7 +125,7 @@ export function createLiveCaptureTransitionRetryCoordinator(options = {}) {
     return releaseOwner(owner, reason);
   }
 
-  function cancelClient(client, reason = 'client-closed') {
+  function cancelClient(client, reason = 'client-closed') {
     const state = clientStates.get(client);
     if (!state) {
       return 0;
@@ -138,8 +138,22 @@ export function createLiveCaptureTransitionRetryCoordinator(options = {}) {
     }
     state.intentGenerations.clear();
     clientStates.delete(client);
-    return cancelled;
-  }
+    return cancelled;
+  }
+
+  function cancelDevice(client, deviceId, reason = 'device-cancelled') {
+    const normalizedDeviceId = String(deviceId || '').trim();
+    const state = clientStates.get(client);
+    if (!state || !normalizedDeviceId) {
+      return false;
+    }
+    const cancelled = releaseOwner(state.owners.get(normalizedDeviceId), reason);
+    state.intentGenerations.delete(normalizedDeviceId);
+    if (state.owners.size === 0 && state.intentGenerations.size === 0) {
+      clientStates.delete(client);
+    }
+    return cancelled;
+  }
 
   function schedule(client, request = {}) {
     const deviceId = String(request.deviceId || '').trim();
@@ -288,10 +302,11 @@ export function createLiveCaptureTransitionRetryCoordinator(options = {}) {
   }
 
   return Object.freeze({
-    beginIntent,
-    schedule,
-    complete,
-    cancelClient,
-    snapshot
-  });
-}
+    beginIntent,
+    schedule,
+    complete,
+    cancelDevice,
+    cancelClient,
+    snapshot
+  });
+}

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/plan-device-access.mjs

@@ -0,0 +1,100 @@
+function normalizeDeviceId(value) {
+  return String(value || '').trim();
+}
+
+function normalizedPlanDeviceLimit(value) {
+  if (!Number.isFinite(Number(value))) return Number.POSITIVE_INFINITY;
+  return Math.max(0, Math.floor(Number(value)));
+}
+
+function stableSlot(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : Number.MAX_SAFE_INTEGER;
+}
+
+/**
+ * Selects the exact connected Client set owned by a finite plan.
+ *
+ * The result is independent from browser selection, monitor changes and input
+ * cadence. Slot order is the product-visible owner; device identity closes an
+ * equal-slot tie. Callers retain the returned Set outside transport hot paths.
+ */
+export function stablePlanAllowedDeviceIds(devices, deviceLimit) {
+  const limit = normalizedPlanDeviceLimit(deviceLimit);
+  if (limit <= 0) return [];
+  const stableDevices = (Array.isArray(devices) ? devices : [])
+    .filter(device => device && normalizeDeviceId(device.deviceId))
+    .slice()
+    .sort((left, right) => {
+      const leftSlot = stableSlot(left.slotNumber);
+      const rightSlot = stableSlot(right.slotNumber);
+      if (leftSlot !== rightSlot) return leftSlot - rightSlot;
+      return normalizeDeviceId(left.deviceId).localeCompare(normalizeDeviceId(right.deviceId));
+    });
+  const ids = [];
+  const seen = new Set();
+  for (const device of stableDevices) {
+    const deviceId = normalizeDeviceId(device.deviceId);
+    if (seen.has(deviceId)) continue;
+    seen.add(deviceId);
+    ids.push(deviceId);
+    if (ids.length >= limit) break;
+  }
+  return ids;
+}
+
+export function createPlanDeviceAccessSnapshot(devices, deviceLimit, generation = 0, {
+  exemptDeviceIds = []
+} = {}) {
+  const exemptDeviceIdSet = new Set((Array.isArray(exemptDeviceIds) ? exemptDeviceIds : [exemptDeviceIds])
+    .map(normalizeDeviceId)
+    .filter(Boolean));
+  const allConnectedDevices = (Array.isArray(devices) ? devices : [])
+    .filter(device => device?.connected === true && normalizeDeviceId(device.deviceId));
+  const connectedDevices = allConnectedDevices
+    .filter(device => !exemptDeviceIdSet.has(normalizeDeviceId(device.deviceId)));
+  const connectedDeviceIds = [...new Set(connectedDevices.map(device => normalizeDeviceId(device.deviceId)))];
+  const exemptConnectedDeviceIds = [...new Set(allConnectedDevices
+    .map(device => normalizeDeviceId(device.deviceId))
+    .filter(deviceId => exemptDeviceIdSet.has(deviceId)))];
+  const allowedDeviceIds = [...new Set([
+    ...exemptDeviceIdSet,
+    ...stablePlanAllowedDeviceIds(connectedDevices, deviceLimit)
+  ])];
+  const allowedDeviceIdSet = new Set(allowedDeviceIds);
+  const blockedDeviceIds = connectedDeviceIds.filter(deviceId => !allowedDeviceIdSet.has(deviceId));
+  return {
+    generation: Math.max(0, Number(generation) || 0),
+    deviceLimit: normalizedPlanDeviceLimit(deviceLimit),
+    connectedDeviceIds,
+    exemptConnectedDeviceIds,
+    allowedDeviceIds,
+    allowedDeviceIdSet,
+    blockedDeviceIds
+  };
+}
+
+export function partitionPlanDeviceIds(deviceIds, snapshot) {
+  const normalizedIds = [...new Set((Array.isArray(deviceIds) ? deviceIds : [deviceIds])
+    .map(normalizeDeviceId)
+    .filter(Boolean))];
+  if (!Number.isFinite(snapshot?.deviceLimit)) {
+    return { allowedDeviceIds: normalizedIds, blockedDeviceIds: [] };
+  }
+  const allowedSet = snapshot?.allowedDeviceIdSet instanceof Set
+    ? snapshot.allowedDeviceIdSet
+    : new Set(snapshot?.allowedDeviceIds || []);
+  return {
+    allowedDeviceIds: normalizedIds.filter(deviceId => allowedSet.has(deviceId)),
+    blockedDeviceIds: normalizedIds.filter(deviceId => !allowedSet.has(deviceId))
+  };
+}
+
+export function planDeviceAccessSnapshotChanged(previous, next) {
+  if (!previous || !next) return true;
+  if (previous.deviceLimit !== next.deviceLimit) return true;
+  if (previous.allowedDeviceIds.length !== next.allowedDeviceIds.length
+    || previous.blockedDeviceIds.length !== next.blockedDeviceIds.length) return true;
+  return previous.allowedDeviceIds.some((deviceId, index) => deviceId !== next.allowedDeviceIds[index])
+    || previous.blockedDeviceIds.some((deviceId, index) => deviceId !== next.blockedDeviceIds[index]);
+}

package/src/plan-device-access.test.mjs

@@ -0,0 +1,97 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  createPlanDeviceAccessSnapshot,
+  partitionPlanDeviceIds,
+  planDeviceAccessSnapshotChanged,
+  stablePlanAllowedDeviceIds as stableHubPlanAllowedDeviceIds
+} from './plan-device-access.mjs';
+import { stablePlanAllowedDeviceIds as stableBrowserPlanAllowedDeviceIds } from '../../../apps/web/src/wall-stream-contract.mjs';
+
+const clients = [6, 3, 1, 5, 2, 4].map(slotNumber => ({
+  deviceId: `client-${slotNumber}`,
+  slotNumber,
+  connected: true
+}));
+
+test('Hub and browser choose the same stable Free, Plus, Pro, and Team device owners', () => {
+  for (const limit of [5, 15, 50, Number.POSITIVE_INFINITY]) {
+    assert.deepEqual(
+      stableHubPlanAllowedDeviceIds(clients, limit),
+      stableBrowserPlanAllowedDeviceIds(clients, limit)
+    );
+  }
+  assert.deepEqual(
+    stableHubPlanAllowedDeviceIds(clients, 5),
+    ['client-1', 'client-2', 'client-3', 'client-4', 'client-5']
+  );
+});
+
+test('Plus stops at 15 Clients, Pro stops at 50, and Team remains unbounded', () => {
+  const manyClients = Array.from({ length: 51 }, (_, index) => ({
+    deviceId: `client-${index + 1}`,
+    slotNumber: index + 1,
+    connected: true
+  }));
+
+  assert.equal(createPlanDeviceAccessSnapshot(manyClients, 15).allowedDeviceIds.length, 15);
+  assert.equal(createPlanDeviceAccessSnapshot(manyClients, 15).blockedDeviceIds.length, 36);
+  assert.equal(createPlanDeviceAccessSnapshot(manyClients, 50).allowedDeviceIds.length, 50);
+  assert.deepEqual(createPlanDeviceAccessSnapshot(manyClients, 50).blockedDeviceIds, ['client-51']);
+  assert.equal(
+    createPlanDeviceAccessSnapshot(manyClients, Number.POSITIVE_INFINITY).blockedDeviceIds.length,
+    0
+  );
+});
+
+test('finite plans reject the exact excess Client instead of counting request width', () => {
+  const snapshot = createPlanDeviceAccessSnapshot(clients, 5, 7);
+  assert.deepEqual(snapshot.allowedDeviceIds, ['client-1', 'client-2', 'client-3', 'client-4', 'client-5']);
+  assert.deepEqual(snapshot.blockedDeviceIds, ['client-6']);
+  assert.deepEqual(partitionPlanDeviceIds(['client-1', 'client-6'], snapshot), {
+    allowedDeviceIds: ['client-1'],
+    blockedDeviceIds: ['client-6']
+  });
+  assert.deepEqual(partitionPlanDeviceIds('client-6', snapshot), {
+    allowedDeviceIds: [],
+    blockedDeviceIds: ['client-6']
+  });
+});
+
+test('a Team to Free downgrade changes one bounded snapshot and preserves stable owners', () => {
+  const unlimited = createPlanDeviceAccessSnapshot(clients, Number.POSITIVE_INFINITY, 1);
+  const downgraded = createPlanDeviceAccessSnapshot(clients, 5, 2);
+  assert.equal(planDeviceAccessSnapshotChanged(unlimited, downgraded), true);
+  assert.deepEqual(downgraded.allowedDeviceIds, ['client-1', 'client-2', 'client-3', 'client-4', 'client-5']);
+  assert.deepEqual(downgraded.blockedDeviceIds, ['client-6']);
+  assert.equal(planDeviceAccessSnapshotChanged(downgraded, {
+    ...downgraded,
+    generation: 3,
+    allowedDeviceIdSet: new Set(downgraded.allowedDeviceIds)
+  }), false, 'generation alone must not churn healthy browser lanes');
+});
+
+test('disconnected Clients do not occupy a connected-device plan slot', () => {
+  const snapshot = createPlanDeviceAccessSnapshot([
+    ...clients,
+    { deviceId: 'client-0', slotNumber: 0, connected: false }
+  ], 5);
+  assert.equal(snapshot.allowedDeviceIdSet.has('client-0'), false);
+  assert.equal(snapshot.allowedDeviceIds.length, 5);
+});
+
+test('the exact Hub manager stays controllable without consuming a Client slot', () => {
+  const snapshot = createPlanDeviceAccessSnapshot([
+    ...clients,
+    { deviceId: 'hub-manager', slotNumber: 0, connected: true }
+  ], 5, 8, { exemptDeviceIds: ['hub-manager'] });
+
+  assert.deepEqual(snapshot.connectedDeviceIds, clients.map(client => client.deviceId));
+  assert.deepEqual(snapshot.exemptConnectedDeviceIds, ['hub-manager']);
+  assert.equal(snapshot.allowedDeviceIdSet.has('hub-manager'), true);
+  assert.deepEqual(snapshot.blockedDeviceIds, ['client-6']);
+  assert.deepEqual(partitionPlanDeviceIds(['hub-manager', 'client-6'], snapshot), {
+    allowedDeviceIds: ['hub-manager'],
+    blockedDeviceIds: ['client-6']
+  });
+});