fix(calls): harden video join without pairwise WebRTC churn

packages/core/src/matrix/client/hooks/__tests__/call-camera-access.test.ts

@@ -1,6 +1,35 @@
 import { describe, expect, it, vi } from 'vitest';
 import { resolveMatrixCameraVideoConstraints } from '../call-video-capture-constraints';
-import { requestLocalCameraAccess } from '../call-camera-access';
+import {
+  isLocalCameraPermissionDenied,
+  requestLocalCameraAccess,
+} from '../call-camera-access';
+
+describe('isLocalCameraPermissionDenied', () => {
+  it('returns true when the Permissions API reports denied', async () => {
+    Object.defineProperty(navigator, 'permissions', {
+      configurable: true,
+      value: {
+        query: vi.fn().mockResolvedValue({ state: 'denied' }),
+      },
+    });
+    await expect(isLocalCameraPermissionDenied()).resolves.toBe(true);
+  });
+
+  it('returns false when permission is granted or prompt', async () => {
+    Object.defineProperty(navigator, 'permissions', {
+      configurable: true,
+      value: {
+        query: vi
+          .fn()
+          .mockResolvedValueOnce({ state: 'granted' })
+          .mockResolvedValueOnce({ state: 'prompt' }),
+      },
+    });
+    await expect(isLocalCameraPermissionDenied()).resolves.toBe(false);
+    await expect(isLocalCameraPermissionDenied()).resolves.toBe(false);
+  });
+});
 
 describe('requestLocalCameraAccess', () => {
   it('returns unavailable when getUserMedia is missing', async () => {

packages/core/src/matrix/client/hooks/__tests__/screenshare-capture-exclusion.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it, vi } from 'vitest';
 
 import {
   HYPHA_SCREEN_SHARE_CAPTURE_ROOT_ID,
+  HYPHA_SCREEN_SHARE_MAIN_CONTENT_ID,
   applyScreenShareCaptureRootRestriction,
   clearScreenShareCaptureRootRestriction,
 } from '../screenshare-capture-exclusion';
@@ -50,6 +51,46 @@ describe('screenshare capture exclusion', () => {
     ).RestrictionTarget;
   });
 
+  it('prefers the main content column over the legacy shell root', async () => {
+    const shell = document.createElement('div');
+    shell.id = HYPHA_SCREEN_SHARE_CAPTURE_ROOT_ID;
+    const main = document.createElement('div');
+    main.id = HYPHA_SCREEN_SHARE_MAIN_CONTENT_ID;
+    shell.appendChild(main);
+    document.body.appendChild(shell);
+
+    const restrictTo = vi.fn().mockResolvedValue(undefined);
+    const target = {};
+    const fromElement = vi.fn().mockResolvedValue(target);
+    (
+      globalThis as typeof globalThis & {
+        RestrictionTarget: {
+          fromElement: (element: Element) => Promise<object>;
+        };
+      }
+    ).RestrictionTarget = { fromElement };
+
+    const track = {
+      readyState: 'live',
+      getSettings: () => ({ displaySurface: 'browser' }),
+      restrictTo,
+    } as unknown as MediaStreamTrack;
+
+    const ok = await applyScreenShareCaptureRootRestriction({
+      getVideoTracks: () => [track],
+    } as MediaStream);
+
+    expect(ok).toBe(true);
+    expect(fromElement).toHaveBeenCalledWith(main);
+
+    shell.remove();
+    delete (
+      globalThis as typeof globalThis & {
+        RestrictionTarget?: unknown;
+      }
+    ).RestrictionTarget;
+  });
+
   it('skips restriction for monitor/window capture', async () => {
     const root = document.createElement('div');
     root.id = HYPHA_SCREEN_SHARE_CAPTURE_ROOT_ID;

packages/core/src/matrix/client/hooks/__tests__/screenshare-capture.test.ts

@@ -59,6 +59,8 @@ describe('buildDisplayMediaConstraints', () => {
       audio: {
         suppressLocalAudioPlayback: false,
       },
+      preferCurrentTab: false,
+      selfBrowserSurface: 'exclude',
       systemAudio: 'include',
     });
   });

packages/core/src/matrix/client/hooks/call-camera-access.ts

@@ -6,8 +6,27 @@ export type LocalCameraAccessResult =
   | { ok: false; reason: 'unavailable' | 'permission_denied' | 'failed' };
 
 /**
- * Prompt for camera access so the browser registers the site permission and
- * Matrix can acquire a fresh video track afterward.
+ * Read camera permission without opening a second getUserMedia stream.
+ * When state is `prompt` or `granted`, Matrix `enter()` should be the only
+ * capture prompt during join.
+ */
+export async function isLocalCameraPermissionDenied(): Promise<boolean> {
+  if (typeof navigator === 'undefined') return false;
+  try {
+    const permissions = navigator.permissions;
+    if (!permissions?.query) return false;
+    const status = await permissions.query({
+      name: 'camera' as PermissionName,
+    });
+    return status.state === 'denied';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Prompt for camera access when the user turns the camera on mid-call.
+ * Avoid calling this before `GroupCall.enter()` — it causes a duplicate prompt.
  */
 export async function requestLocalCameraAccess(): Promise<LocalCameraAccessResult> {
   if (

packages/core/src/matrix/client/hooks/group-call-webrtc-diagnostics.ts

@@ -132,6 +132,128 @@ type InboundRtpVideoStats = {
   ssrc?: number;
 };
 
+type IceTransportSummary = {
+  iceConnectionState: RTCIceConnectionState;
+  iceGatheringState: RTCIceGatheringState;
+  connectionState: RTCPeerConnectionState;
+  localCandidateType?: string;
+  remoteCandidateType?: string;
+  pairState?: string;
+  inboundAudioBytes?: number;
+  inboundVideoBytes?: number;
+};
+
+function readIceTransportSummary(
+  peerConnection: RTCPeerConnection,
+  stats: RTCStatsReport,
+): IceTransportSummary {
+  const candidates = new Map<string, string>();
+  let selectedPairId: string | undefined;
+  let nominatedPairId: string | undefined;
+  let nominatedLocalCandidateId: string | undefined;
+  let nominatedRemoteCandidateId: string | undefined;
+
+  for (const report of stats.values()) {
+    if (
+      report.type === 'local-candidate' ||
+      report.type === 'remote-candidate'
+    ) {
+      const candidateType = report.candidateType;
+      if (typeof candidateType === 'string') {
+        candidates.set(report.id, candidateType);
+      }
+      continue;
+    }
+    if (report.type === 'transport' && 'selectedCandidatePairId' in report) {
+      const id = report.selectedCandidatePairId;
+      if (typeof id === 'string' && id.length > 0) {
+        selectedPairId = id;
+      }
+      continue;
+    }
+    if (report.type !== 'candidate-pair') continue;
+    if (report.nominated === true && report.state === 'succeeded') {
+      nominatedPairId = report.id;
+      nominatedLocalCandidateId =
+        typeof report.localCandidateId === 'string'
+          ? report.localCandidateId
+          : undefined;
+      nominatedRemoteCandidateId =
+        typeof report.remoteCandidateId === 'string'
+          ? report.remoteCandidateId
+          : undefined;
+    }
+  }
+
+  const pairId = selectedPairId ?? nominatedPairId;
+  let localCandidateType: string | undefined;
+  let remoteCandidateType: string | undefined;
+  let pairState: string | undefined;
+
+  if (pairId) {
+    const pair = stats.get(pairId);
+    if (pair?.type === 'candidate-pair') {
+      pairState = typeof pair.state === 'string' ? pair.state : undefined;
+      const localId =
+        typeof pair.localCandidateId === 'string'
+          ? pair.localCandidateId
+          : nominatedLocalCandidateId;
+      const remoteId =
+        typeof pair.remoteCandidateId === 'string'
+          ? pair.remoteCandidateId
+          : nominatedRemoteCandidateId;
+      if (localId) localCandidateType = candidates.get(localId);
+      if (remoteId) remoteCandidateType = candidates.get(remoteId);
+    }
+  }
+
+  let inboundAudioBytes = 0;
+  let inboundVideoBytes = 0;
+  stats.forEach((report) => {
+    if (report.type !== 'inbound-rtp') return;
+    const bytes = report.bytesReceived;
+    if (typeof bytes !== 'number' || bytes <= 0) return;
+    if (report.kind === 'audio') inboundAudioBytes += bytes;
+    if (report.kind === 'video') inboundVideoBytes += bytes;
+  });
+
+  return {
+    iceConnectionState: peerConnection.iceConnectionState,
+    iceGatheringState: peerConnection.iceGatheringState,
+    connectionState: peerConnection.connectionState,
+    localCandidateType,
+    remoteCandidateType,
+    pairState,
+    inboundAudioBytes: inboundAudioBytes || undefined,
+    inboundVideoBytes: inboundVideoBytes || undefined,
+  };
+}
+
+async function logIceTransportForPeerConnection(options: {
+  roomId: string;
+  groupCallId: string;
+  userId: string | null;
+  peerConnection: RTCPeerConnection;
+}): Promise<void> {
+  const { roomId, groupCallId, userId, peerConnection } = options;
+  const stats = await peerConnection.getStats();
+  const transport = readIceTransportSummary(peerConnection, stats);
+  logSpaceGroupCallEvent({
+    name: 'hypha.group_call.ice_transport',
+    roomId,
+    groupCallId,
+    remoteUserId: userId ?? undefined,
+    iceConnectionState: transport.iceConnectionState,
+    iceGatherState: transport.iceGatheringState,
+    connectionState: transport.connectionState,
+    localCandidateType: transport.localCandidateType,
+    remoteCandidateType: transport.remoteCandidateType,
+    pairState: transport.pairState,
+    inboundAudioBytes: transport.inboundAudioBytes,
+    inboundVideoBytes: transport.inboundVideoBytes,
+  });
+}
+
 export function readInboundRtpVideoFrameSizes(
   stats: RTCStatsReport,
 ): InboundRtpVideoStats[] {
@@ -247,9 +369,28 @@ export function attachGroupCallWebRtcDiagnostics(options: {
     }
   };
 
+  const logIceTransport = () => {
+    if (!enumeratePeerConnections) return;
+    for (const { userId, peerConnection } of enumeratePeerConnections(gc)) {
+      void logIceTransportForPeerConnection({
+        roomId,
+        groupCallId: gc.groupCallId,
+        userId,
+        peerConnection,
+      });
+    }
+  };
+
   if (inboundRtpFrameLogIntervalMs > 0 && enumeratePeerConnections) {
     logFrameSizes();
-    frameLogInterval = setInterval(logFrameSizes, inboundRtpFrameLogIntervalMs);
+    logIceTransport();
+    frameLogInterval = setInterval(() => {
+      logFrameSizes();
+      logIceTransport();
+    }, inboundRtpFrameLogIntervalMs);
+  } else if (summaryStatsIntervalMs > 0 && enumeratePeerConnections) {
+    logIceTransport();
+    frameLogInterval = setInterval(logIceTransport, summaryStatsIntervalMs);
   }
 
   return () => {

packages/core/src/matrix/client/hooks/index.ts

@@ -67,6 +67,7 @@ export {
 } from './call-reactions-client';
 export {
   HYPHA_SCREEN_SHARE_CAPTURE_ROOT_ID,
+  HYPHA_SCREEN_SHARE_MAIN_CONTENT_ID,
   applyScreenShareCaptureRootRestriction,
   applyScreenShareCaptureRootRestrictionWithRetry,
   clearScreenShareCaptureRootRestriction,

packages/core/src/matrix/client/hooks/screenshare-capture-exclusion.ts

@@ -1,7 +1,14 @@
-/** Main app shell root — screen share is restricted to this element when supported. */
+/** Legacy app shell wrapper (includes side panels). */
 export const HYPHA_SCREEN_SHARE_CAPTURE_ROOT_ID =
   'hypha-screen-share-capture-root';
 
+/**
+ * Main content column — tab capture is cropped here so Human Chat / call UI in the
+ * right sidebar is not transmitted to remote participants.
+ */
+export const HYPHA_SCREEN_SHARE_MAIN_CONTENT_ID =
+  'hypha-screen-share-main-content';
+
 /** Opaque handle from Element Capture `RestrictionTarget.fromElement` (not in all TS DOM libs). */
 type ScreenShareRestrictionTarget = object;
 
@@ -11,7 +18,10 @@ type RestrictableMediaStreamTrack = MediaStreamTrack & {
 
 function getCaptureRootElement(): HTMLElement | null {
   if (typeof document === 'undefined') return null;
-  return document.getElementById(HYPHA_SCREEN_SHARE_CAPTURE_ROOT_ID);
+  return (
+    document.getElementById(HYPHA_SCREEN_SHARE_MAIN_CONTENT_ID) ??
+    document.getElementById(HYPHA_SCREEN_SHARE_CAPTURE_ROOT_ID)
+  );
 }
 
 function isTabCaptureTrack(track: MediaStreamTrack): boolean {
@@ -22,8 +32,8 @@ function isTabCaptureTrack(track: MediaStreamTrack): boolean {
 }
 
 /**
- * Crop tab self-capture to the main Hypha shell so the floating call dock (a
- * sibling outside this root) is not transmitted to remote participants.
+ * Crop tab self-capture to the main content column so side panels, call chrome,
+ * and the floating call dock are not transmitted to remote participants.
  */
 export async function applyScreenShareCaptureRootRestriction(
   stream: MediaStream | null | undefined,

packages/core/src/matrix/client/hooks/screenshare-capture.ts

@@ -101,7 +101,11 @@ export function buildDisplayMediaConstraints(
 
   switch (surfaceMode) {
     case 'browser':
-      return base;
+      return {
+        ...base,
+        preferCurrentTab: false,
+        selfBrowserSurface: 'exclude',
+      };
     case 'window':
       return {
         ...base,

packages/core/src/matrix/client/hooks/space-group-call-telemetry.ts

@@ -25,6 +25,7 @@ export type SpaceGroupCallTelemetryEvent = {
     | 'hypha.group_call.remote_media_recover'
     | 'hypha.group_call.turn_probe'
     | 'hypha.group_call.ice_gather_probe'
+    | 'hypha.group_call.ice_transport'
     | 'hypha.group_call.webrtc_summary'
     | 'hypha.group_call.inbound_rtp_frame_size'
     | 'hypha.group_call.simulcast_audit'
@@ -73,6 +74,13 @@ export type SpaceGroupCallTelemetryEvent = {
   forceTurn?: boolean;
   fallbackIceAllowed?: boolean;
   iceGatherState?: RTCIceGatheringState | 'unsupported' | 'timeout';
+  iceConnectionState?: RTCIceConnectionState;
+  connectionState?: RTCPeerConnectionState;
+  localCandidateType?: string;
+  remoteCandidateType?: string;
+  pairState?: string;
+  inboundAudioBytes?: number;
+  inboundVideoBytes?: number;
   /** Matrix SDK summary stats (subset); see `SummaryStatsReport`. */
   percentageReceivedMedia?: number;
   percentageReceivedAudioMedia?: number;