@robono/calling 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.2.0
+
+- Add bounded, best-effort transport counters for operational relay visibility. Reports contain no media or network addresses and are not used for billing.
+
+Voice and video calls, group calls, screen sharing, participant-based usage reporting and shared-budget call admission. Existing one-to-one voice APIs remain available.
+
+- Keep group calls alive during successful signaling, with bounded parallel ICE
+  submission and retry recovery. Unrelated requests and stale responses cannot
+  extend an active call's authorization lease.
+- Preserve native remote streams so video tracks remain attached to mobile video views.
+- Reuse the original session description after a lost response; ICE gathering cannot change the retried payload.
+- Negotiate group peers independently and prevent pre-start state polling from clearing a new call’s local media.
+- Cap transmitted video when native cameras capture above the selected resolution; reapply the same limits when sharing a screen or restoring the camera.
+- Enforce request deadlines even when native networking ignores cancellation, including stalled response bodies, so signaling can recover instead of remaining stuck.
+
+
+## Unreleased
+
+- Optional video, group voice/video (two to eight members), separate screen-sharing permissions, and per-participant history. Group signaling preserves isolated peer legs and current relationship permissions. Screen sharing replaces video tracks without changing microphone transport; restored cameras keep their prior choice. Group invitation deadlines and expired-session cleanup stop stale UI and media.
+
 ## 0.1.2
 
 - Add an optional availability reason while preserving voiceAvailable and existing call-control behavior.

package/README.md

@@ -1,6 +1,6 @@
 # Robono Calling SDK
 
-Add one-to-one voice calls within your app or between people connected across Robono Bridge networks. The SDK manages WebRTC negotiation, direct connections, relay fallback, call state and microphone cleanup. Your app keeps its identity and platform notification integration. Use your own interface, or choose the separate optional mobile screen package. The calling engine never requires a Robono interface.
+Add voice and video calls within your app or between people connected across Robono Bridge networks, with optional group calls and screen sharing. The SDK manages WebRTC negotiation, direct connections, relay fallback, call state and microphone cleanup. Your app keeps its identity and platform notification integration. Use your own interface, or choose the separate optional mobile screen package. The calling engine never requires a Robono interface.
 
 ## Install
 
@@ -127,3 +127,40 @@ Unanswered calls expire 30 seconds after creation. Stop ringing at `ringRemainin
 For an established call, `client.hold()` silences local and remote tracks immediately and acknowledges the interruption to the service. A held endpoint can stop polling for up to five minutes; retries do not extend that deadline. The other endpoint keeps its normal signaling lease and may hang up. Show Call on hold when `localHeld` or `remoteHeld` is true. Keep the user's manual mute preference separate from hold.
 
 Call `client.resume(prepareAudio)` only when the OS permits audio to return, or when the person explicitly requests resume. The client first refreshes authorization and call state, then awaits your `prepareAudio` callback, acknowledges resume and restores tracks. The callback must reject if another call still owns audio. A stale response, remote hangup, expired session or ended call cannot restart capture. The optional mobile package supplies this wiring and a Resume call control. No voicemail is involved.
+
+### Optional video
+
+Check `availability(connectionId).videoAvailable` separately from `voiceAvailable`. Start a video call with `client.call(connectionId, {kind: 'video'})`. Ordinary `client.call(connectionId)` remains voice-only. The host's media adapter receives `{kind, isCurrent}`; a video call requires one audio track and one video track. Use `onLocalStream` and `onRemoteStream` to render previews, `setCamera(enabled)` to control outgoing video, and `setVideoForeground(active)` when application visibility changes. Disposal stops all captured tracks.
+
+Both apps and the relationship must allow video. Voice-only sessions do not receive video invitations. When using your own WebRTC client, send `mediaKinds: ['voice', 'video']` with `/state`, `kind: 'video'` with `/ice` and `/start`, and supply one audio and one video SDP media section. Voice requests omit `kind` or use `voice`. No data channel or additional camera tracks are admitted. Media travels directly when possible, using the configured relay fallback when needed.
+
+Final call history includes `kind`; older records without it are voice calls. Usage records distinguish voice and video and retain connection duration, not the media itself.
+
+## Usage protection and operational visibility
+
+The service applies the same protections to own-network and cross-network calls.
+Preserve the request ID when retrying a lost call-start response. Honor
+`Retry-After`; a deliberate new call needs a new request ID. Call status and
+hangup have separate limits so a start loop does not block cleanup.
+
+The SDK sends bounded, best-effort transport byte counters every fifteen seconds
+while connected. They contain no audio, video, transcripts, IP addresses or ICE
+candidates. Counters are approximate and are not used to calculate charges.
+
+Use the Server SDK from your backend for `monitoring()` and revision-numbered
+`setUserPermissions()`. See [limits, costs and alerts](https://robono.com/docs#calling-reliability).
+
+## Event-based listening
+
+Use `@robono/calling@0.1.3` with `@robono/calling-react-native@0.2.2` when using the optional mobile interface. Existing custom interfaces remain supported. See https://robono.com/docs#calling-events for the lifecycle and recovery contract.
+
+- Foreground, idle: an authenticated WebSocket listens for incoming calls. No periodic state polling. A ping/pong every 20 seconds maintains presence.
+- Active calls: events trigger state reconciliation immediately; a state health check runs every 3 seconds. The optional native runtime also provides a three-second background recovery check when device timers are suspended; simultaneous refreshes share one request.
+- Idle in background: call `setForeground(false)`. The event socket and state checks stop. Your backend delivers Robono's signed incoming-call events through your app's APNs/FCM notifications. A WebSocket does not replace push delivery.
+- Return to foreground: call `setForeground(true)`. The socket reconnects and current state is checked. Do not create a new call to recover a listening session. The optional controller forwards this lifecycle method to the engine.
+- Event reconnection: delays start at 1 second, double to 30 seconds (plus up to 20% jitter), honor Retry-After, and stop after eight retries. Foreground re-entry can restart recovery. State recovery stops after six consecutive failed idle checks.
+- Expired idle sessions: `onSessionExpired` requests new admission without presenting a failed-call screen. Dispose the expired client and create a new one with a new session from your backend. Use bounded backoff for admission failures. Authorization revocation is not a retryable session expiration. An active call cannot be transferred to a new session.
+
+`createHttpTransport` supplies the event subscription automatically. If wrapping it, preserve `request.subscribe = transport.subscribe`. A custom request without `subscribe`, or `{events:false}`, retains the compatibility polling interval (`pollMs`, default 1000 ms).
+
+The 0.1.2 engine had polling and retry backoff but did not include this event transport. No native permissions or rebuild are added by this JavaScript patch to an app already using the native calling package.

package/SBOM.spdx.json

@@ -2,24 +2,24 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@robono/calling@0.1.2",
-  "documentNamespace": "http://spdx.org/spdxdocs/@robono%2fcalling-0.1.2-***",
+  "name": "@robono/calling@0.2.0",
+  "documentNamespace": "http://spdx.org/spdxdocs/@robono%2fcalling-0.2.0-***",
   "creationInfo": {
-    "created": "2026-10-25T10:32:11.266Z",
+    "created": "2026-10-28T21:07:59.755Z",
     "creators": [
       "Tool: npm/cli-11.6.2"
     ]
   },
   "documentDescribes": [
-    "SPDXRef-Package-robono.calling-0.1.2"
+    "SPDXRef-Package-robono.calling-0.2.0"
   ],
   "packages": [
     {
       "name": "@robono/calling",
-      "SPDXID": "SPDXRef-Package-robono.calling-0.1.2",
-      "versionInfo": "0.1.2",
+      "SPDXID": "SPDXRef-Package-robono.calling-0.2.0",
+      "versionInfo": "0.2.0",
       "packageFileName": "",
-      "description": "One-to-one WebRTC voice calling for connected Robono Bridge networks.",
+      "description": "WebRTC voice, video, group calling and screen sharing within apps and across Robono Bridge networks.",
       "primaryPackagePurpose": "LIBRARY",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
@@ -29,7 +29,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40robono/calling@0.1.2"
+          "referenceLocator": "pkg:npm/%40robono/calling@0.2.0"
         }
       ]
     }
@@ -37,7 +37,7 @@
   "relationships": [
     {
       "spdxElementId": "SPDXRef-DOCUMENT",
-      "relatedSpdxElement": "SPDXRef-Package-robono.calling-0.1.2",
+      "relatedSpdxElement": "SPDXRef-Package-robono.calling-0.2.0",
       "relationshipType": "DESCRIBES"
     }
   ]

package/dist/events.js

@@ -0,0 +1,38 @@
+/** Authenticated event hints with bounded reconnects. No idle state polling. */
+export function subscribeCallingEvents({baseUrl,token,WebSocketImpl}, {onEvent,onStatus=()=>{},onError=()=>{}}) {
+  let socket,timer,deadline,stable,stale,closed=false,paused=false,failures=0,retryAfter=0,terminal=false;
+  const url=baseUrl.replace(/^http/, 'ws').replace(/\/$/,'')+'/events';
+  function clear(){clearTimeout(timer);clearTimeout(deadline);clearTimeout(stable);clearTimeout(stale);}
+  function disconnect(){const previous=socket;socket=null;if(previous){previous.onclose=null;previous.onmessage=null;previous.onerror=()=>{};previous.close();}}
+  function retry(){
+    clear();if(closed||paused||terminal)return;
+    if(failures>=8){onStatus('disconnected');return;}
+    const delay=Math.max(retryAfter,Math.min(30000,1000*2**failures++)*(1+Math.random()*.2));retryAfter=0;
+    onStatus('reconnecting');timer=setTimeout(connect,delay);
+  }
+  function touch(){clearTimeout(stale);stale=setTimeout(()=>{disconnect();retry();},50000);}
+  function connect(){
+    if(closed||paused||terminal)return;
+    try{socket=new WebSocketImpl(url);}catch{retry();return;}
+    const ws=socket;onStatus('connecting');
+    deadline=setTimeout(()=>{disconnect();retry();},10000);
+    ws.onopen=()=>{if(ws===socket)ws.send(JSON.stringify({type:'authenticate',token}));};
+    ws.onmessage=event=>{
+      if(ws!==socket)return;
+      let data;try{data=JSON.parse(event.data);}catch{return;}
+      if(data.type==='ready'){clearTimeout(deadline);touch();stable=setTimeout(()=>{failures=0;},60000);onStatus('listening');onEvent();}
+      else if(data.type==='changed')onEvent();
+      else if(data.type==='ping'){touch();ws.send(JSON.stringify({type:'pong'}));}
+      else if(data.type==='error'){
+        retryAfter=Math.max(0,Number(data.retryAfterMs)||0);
+        if(data.status===401||data.status===403){terminal=true;clear();disconnect();onStatus(data.status===403?'access_revoked':'session_expired');onError(Object.assign(Error(data.error),{status:data.status}));}
+      }
+    };
+    ws.onerror=()=>{};ws.onclose=()=>{if(ws!==socket)return;socket=null;retry();};
+  }
+  connect();
+  return {
+    setEnabled(enabled){if(closed||terminal)return;if(enabled&&!paused&&socket)return;paused=!enabled;clear();disconnect();if(enabled){failures=0;connect();}else onStatus('paused');},
+    close(){closed=true;clear();disconnect();},
+  };
+}

package/dist/groups.d.ts

@@ -0,0 +1,7 @@
+import type {Request,EventStatus} from './index.js';
+export interface GroupCall {screenSharingAvailable?:boolean;sharing?:boolean[];id:string;connectionId:string;group:true;kind:'voice'|'video';version:number;state:'ringing'|'connecting'|'connected'|'ended';reason?:string;createdAt:number;connectedAt:number|null;endedAt:number|null;ringRemainingMs:number;holdExpiresAt:number|null;self:number;controlled:boolean;memberState:'invited'|'joined'|'left'|'declined';localHeld:boolean;members:Array<{id:number;appId:string;userId:string;state:string;held:boolean;connectedAt:number|null}>;peers:Array<{id:string;participant:number;offerer:boolean;remoteDescription:RTCSessionDescriptionInit|null;remoteCandidates:RTCIceCandidateInit[];connected:boolean}>}
+export interface GroupSnapshot {listeningStatus?:EventStatus;screenSharing?:boolean;screenSharePending?:boolean;displayStream?:MediaStream|null;call:GroupCall|null;muted:boolean;cameraEnabled:boolean;localHeld:boolean;localStream:MediaStream|null;remoteStreams:Record<number,MediaStream>;error:string|null;preparing:boolean;connectedAt:number|null}
+export class RobonoGroupCallingClient {
+ constructor(options:{videoQuality?:'480p'|'720p';request:Request;onSessionExpired?:(error:Error)=>void;onChange?:(state:GroupSnapshot)=>void;getDisplayMedia?:(context?:{isCurrent:()=>boolean})=>Promise<MediaStream>;getUserMedia?:(context:{kind:'voice'|'video';videoQuality?:'480p'|'720p';isCurrent:()=>boolean})=>Promise<MediaStream>;createPeerConnection?:(config:RTCConfiguration)=>RTCPeerConnection;createRemoteStream?:(track:MediaStreamTrack)=>MediaStream;createId?:()=>string;forceRelay?:boolean;pollMs?:number});
+ availability(connectionId:string,kind?:'voice'|'video'):Promise<{available:boolean;maxParticipants:number}>;startScreenSharing():Promise<void>;stopScreenSharing():Promise<void>;state:GroupSnapshot;closed:boolean;listen():Promise<void>;refresh():Promise<boolean>;call(connectionId:string,options?:{kind?:'voice'|'video'}):Promise<void>;answer():Promise<void>;leave():Promise<void>;hold():Promise<void>;resume(prepareAudio?:()=>Promise<void>):Promise<void>;mute(value?:boolean):void;setCamera(value:boolean):void;setForeground(value:boolean):void;setVideoForeground(value:boolean):void;dispose():Promise<void>;
+}

package/dist/groups.js

@@ -0,0 +1,153 @@
+import {createTransportTelemetry} from './telemetry.js';
+import {mediaProfile,videoConstraints,limitSender} from './media-profile.js';
+import {createScreenSharing} from './sharing.js';
+/** Optional multiparty engine. It shares admission/transport with direct calls, not their UI. */
+export class RobonoGroupCallingClient {
+ constructor({request,onSessionExpired=()=>{},onChange=()=>{},videoQuality='720p',getUserMedia=({kind,videoQuality})=>navigator.mediaDevices.getUserMedia({audio:true,video:kind==='video'?videoConstraints(videoQuality):false}),createPeerConnection=c=>new RTCPeerConnection(c),createRemoteStream=track=>new MediaStream([track]),createId=()=>crypto.randomUUID(),forceRelay=false,pollMs=1000,getDisplayMedia=()=>navigator.mediaDevices.getDisplayMedia({video:true,audio:false})}={}){
+  Object.assign(this,{onSessionExpired,onChange,getUserMedia,createPeerConnection,createRemoteStream,createId,forceRelay,pollMs});
+  this.request=async(operation,input)=>{
+   const epoch=this.epoch,result=await request(operation,input);
+   // Negotiation also proves the call is authorized and the server is reachable.
+   // Availability checks and late replies from a previous call must not extend it.
+   if(!this.closed&&epoch===this.epoch&&['state','start','join','description','candidate','connected','hold','sharing'].some(name=>operation==='groups/'+name))this.lastSuccess=Date.now();
+   return result;
+  };
+  this.request.subscribe=request.subscribe;
+  this.videoQuality=mediaProfile(videoQuality).quality;
+  this.reportTransport=createTransportTelemetry(request);this.peers=new Map();this.pendingRTC=new Set();this.state={call:null,muted:false,cameraEnabled:true,localHeld:false,localStream:null,remoteStreams:{},error:null,preparing:false,connectedAt:null};
+  this.sharing=createScreenSharing({limitVideo:sender=>limitSender(sender,this.ice?.videoQuality==='480p'?'480p':this.videoQuality),request:input=>this.request('groups/sharing',input),call:()=>this.state.call,peers:()=>[...this.peers.values()].map(p=>p.pc),stream:()=>this.stream,capture:getDisplayMedia,emit:()=>this.emit(),fail:e=>{this.state.error=e.message;this.emit();}});
+  this.closed=false;this.epoch=0;this.foreground=true;this.failures=0;this.notBefore=0;this.lastSuccess=Date.now();this.holdRevision=0;
+ }
+ rtc(promise,phase){return new Promise((resolve,reject)=>{let finished=false;const finish=(fn,value)=>{if(finished)return;finished=true;clearTimeout(timer);this.pendingRTC.delete(cancel);fn(value);};const cancel=()=>finish(reject,Error('call_cancelled'));const timer=setTimeout(()=>finish(reject,Error(phase+'_timeout')),8000);this.pendingRTC.add(cancel);Promise.resolve(promise).then(v=>finish(resolve,v),e=>finish(reject,e));});}
+ emit(){if(this.events&&this.state.call&&this.state.call.state!=='ended'&&!this.timer&&!this.polling&&!this.closed)this.timer=setTimeout(()=>this.poll(),3000);this.scheduleRingDeadline();Object.assign(this.state,this.sharing.state());this.onChange({...this.state,remoteStreams:{...this.state.remoteStreams}});}
+ scheduleRingDeadline(){
+  const call=this.state.call;
+  if(!call?.controlled||call.state==='ended'||!(call.memberState==='invited'||call.state==='ringing')){clearTimeout(this.ringTimer);this.ringCallId=null;return;}
+  if(!Number.isFinite(call.ringRemainingMs))return;
+  const remaining=Math.max(0,call.ringRemainingMs),deadline=Date.now()+remaining;
+  if(this.ringCallId===call.id&&this.ringDeadline<=deadline)return;
+  clearTimeout(this.ringTimer);this.ringCallId=call.id;this.ringDeadline=deadline;
+  this.ringTimer=setTimeout(()=>{
+   const current=this.state.call;if(current?.id!==call.id||current.state==='ended'||!(current.memberState==='invited'||current.state==='ringing'))return;
+   this.ended??=new Set();this.ended.add(call.id);while(this.ended.size>256)this.ended.delete(this.ended.values().next().value);
+   this.reset();this.state.call={...current,state:'ended',reason:'no_answer',endedAt:Date.now()};this.emit();
+  },Math.min(2147483647,remaining));
+ }
+ syncTracks(){for(const t of this.stream?.getTracks()??[])t.enabled=!this.state.localHeld&&(t.kind==='audio'?!this.state.muted:this.state.cameraEnabled&&this.foreground);}
+ mute(value=true){this.state.muted=value;this.syncTracks();this.emit();}
+ setCamera(value){this.state.cameraEnabled=value;this.syncTracks();this.emit();}
+ setVideoForeground(value){this.foreground=value;this.syncTracks();}
+ async availability(connectionId,kind='voice'){if(this.closed)throw Error('calling_client_closed');return this.request('groups/availability',{connectionId,kind});}
+ async listen(){if(this.started||this.closed)return;this.started=true;this.watch=setInterval(()=>{if(!this.state.preparing&&this.state.call&&this.stream&&(!(this.state.localHeld&&this.holdDeadline>Date.now())&&Date.now()-this.lastSuccess>10000)){void this.leave().catch(()=>{});}},500);if(this.request.subscribe)this.events=this.request.subscribe({onEvent:()=>this.wake(),onStatus:status=>{this.state.listeningStatus=status;this.emit();},onError:e=>this.sessionError(e)});await this.poll();}
+ sessionError(e){const active=this.state.call&&this.state.call.state!=='ended';this.state.error=active?e.message:null;this.state.listeningStatus=e.status===403?'access_revoked':'session_expired';this.reset();this.closed=true;clearTimeout(this.timer);clearInterval(this.watch);this.events?.close();this.emit();if(e.status===401)this.onSessionExpired(e);}
+ wake(){if(this.closed)return;clearTimeout(this.timer);if(this.polling||this.state.preparing){this.eventPending=true;return;}void this.poll();}
+ setForeground(value){this.foreground=value;this.setVideoForeground(value);this.events?.setEnabled(value||!!this.state.call&&this.state.call.state!=='ended');if(value)this.wake();else if(!this.state.call||this.state.call.state==='ended')clearTimeout(this.timer);}
+ async poll(){
+  if(this.closed||this.polling)return;this.polling=true;this.timer=null;
+  try{await this.refresh();this.reportTransport(this.state.call?.state==='connected'?this.state.call.id:null,[...this.peers].map(([id,p])=>[id,p.pc]));}finally{this.polling=false;}
+  if(this.closed)return;const active=this.state.call&&this.state.call.state!=='ended';
+  if(!this.foreground&&!active){this.events?.setEnabled(false);return;}
+  const pending=this.eventPending;this.eventPending=false;
+  if(active||!this.events||this.failures>0&&this.failures<6||pending)this.timer=setTimeout(()=>this.poll(),Math.min(2147483647,Math.max(pending?0:this.events?3000:this.pollMs,this.notBefore-Date.now())));
+ }
+ async refresh(){
+  if(this.closed||this.state.preparing||Date.now()<this.notBefore)return false;
+  if(this.refreshing)return this.refreshing;
+  const work=this.refreshState();this.refreshing=work;try{return await work;}finally{if(this.refreshing===work)this.refreshing=null;}
+ }
+ async refreshState(){
+  const epoch=this.epoch;
+  try{const result=await this.request('groups/state',{});if(this.closed)return false;this.failures=0;this.notBefore=0;
+   if(epoch!==this.epoch||this.state.preparing)return false;
+   await this.apply(result.call);this.state.error=null;this.emit();return true;
+  }catch(e){if(this.closed||epoch!==this.epoch||this.state.preparing)return false;this.notBefore=Date.now()+Math.max(Number(e.retryAfterMs)||0,Math.min(30000,1000*2**Math.min(this.failures++,5)));this.state.error=this.state.call&&this.state.call.state!=='ended'?e.message:null;
+   if(e.status===401||e.status===403){this.sessionError(e);return false;}
+   if(e.status===401){this.closed=true;clearTimeout(this.timer);clearInterval(this.watch);}
+   if([401,403].includes(e.status)||/_timeout$/.test(e.message)){const call=this.state.call;this.reset();this.state.call=null;if(call)void this.request('groups/leave',{callId:call.id}).catch(()=>{});}
+   this.emit();return false;}
+ }
+ async capture(kind,epoch){
+  const stream=await this.getUserMedia({kind,videoQuality:this.ice?.videoQuality==='480p'?'480p':this.videoQuality,isCurrent:()=>epoch===this.epoch&&!this.closed});
+  if(epoch!==this.epoch||this.closed){stream.getTracks().forEach(t=>t.stop());throw Error('call_cancelled');}
+  if(!stream.getAudioTracks().length||kind==='video'&&!stream.getVideoTracks().length){stream.getTracks().forEach(t=>t.stop());throw Error('media_unavailable');}
+  this.stream=stream;this.state.localStream=stream;this.syncTracks();
+ }
+ async call(connectionId,{kind='voice'}={}){
+  if(this.state.preparing||this.stream||this.closed)throw Error('busy');
+  const epoch=++this.epoch;this.state.preparing=true;this.state.error=null;this.state.connectedAt=null;this.emit();
+  try{
+   this.ice=await this.request('groups/ice',{connectionId,kind});await this.capture(kind,epoch);
+   if(epoch!==this.epoch)throw Error('call_cancelled');
+   const input={connectionId,kind,requestId:this.createId()};
+   // Same request ID on a lost response; never start a second group call.
+   let call;try{call=await this.request('groups/start',input);}catch(e){if(e.status&&e.status<500)throw e;call=await this.request('groups/start',input);}
+   if(epoch!==this.epoch){await this.request('groups/leave',{callId:call.id});return;}
+   await this.apply(call);
+  }catch(e){this.reset();this.state.call=null;this.state.error=e.message;throw e;}
+  finally{this.state.preparing=false;this.emit();if(this.eventPending){this.eventPending=false;this.wake();}}
+ }
+ async answer(){
+  const call=this.state.call;if(!call||call.memberState!=='invited'||!call.controlled||this.state.preparing)throw Error('call_unavailable');
+  const epoch=++this.epoch;this.state.preparing=true;this.emit();
+  try{this.ice=await this.request('groups/ice',{callId:call.id,kind:call.kind});await this.capture(call.kind,epoch);
+   if(epoch!==this.epoch)throw Error('call_cancelled');
+   let joined;try{joined=await this.request('groups/join',{callId:call.id});}catch(e){if(e.status&&e.status<500)throw e;joined=await this.request('groups/join',{callId:call.id});}
+   if(epoch!==this.epoch){await this.request('groups/leave',{callId:call.id});return;}
+   await this.apply(joined);
+  }catch(e){this.reset();this.state.call=null;void this.request('groups/leave',{callId:call.id}).catch(()=>{});this.state.error=e.message;throw e;}finally{this.state.preparing=false;this.emit();if(this.eventPending){this.eventPending=false;this.wake();}}
+ }
+ async apply(call){
+  if(call?.id&&this.ended?.has(call.id))return;
+  this.state.call=call;this.sharing.sync();
+  if(!call||call.state==='ended'||!call.controlled||['left','declined'].includes(call.memberState)){this.reset();this.emit();return;}
+  if(call.memberState!=='joined'||!this.stream){this.emit();return;}
+  const epoch=this.epoch;
+  for(const [id,p] of this.peers)if(!call.peers.some(x=>x.id===id)){p.pc.close();this.peers.delete(id);delete this.state.remoteStreams[p.participant];}
+  // Each peer negotiates independently; a slow leg must not hold up the others.
+  const negotiations=await Promise.allSettled(call.peers.map(async remote=>{
+   if(epoch!==this.epoch)return;
+   let p=this.peers.get(remote.id);
+   if(!p){
+    const pc=this.createPeerConnection({iceServers:this.ice?.iceServers??[],iceTransportPolicy:this.forceRelay?'relay':'all'});
+    p={pc,participant:remote.participant,remoteCount:0,candidates:[],localSent:false,connectedSent:false};this.peers.set(remote.id,p);
+    for(const track of this.stream.getTracks()){const sender=pc.addTrack(track.kind==='video'?this.sharing.track()||track:track,this.stream);if(track.kind==='video')await limitSender(sender,this.ice?.videoQuality==='480p'?'480p':this.videoQuality);}
+    pc.onicecandidate=e=>{if(e.candidate)p.candidates.push(e.candidate.toJSON?.()??e.candidate);};
+    pc.ontrack=e=>{if(epoch!==this.epoch)return;let stream=this.state.remoteStreams[p.participant];if(e.streams?.[0])stream=e.streams[0];else if(!stream)stream=this.createRemoteStream(e.track);else if(!stream.getTracks().some(t=>t.id===e.track.id))stream.addTrack(e.track);this.state.remoteStreams[p.participant]=stream;this.emit();};
+    pc.onconnectionstatechange=()=>{if(epoch!==this.epoch)return;if(pc.connectionState==='connected'){this.state.connectedAt??=Date.now();this.emit();}else if(pc.connectionState==='failed'){void this.request('groups/failed',{callId:call.id,peerId:remote.id}).catch(()=>{});this.reset();this.state.call=null;this.state.error='media_failed';this.emit();}};
+   }
+   const {pc}=p;
+   if(remote.offerer&&!pc.localDescription){const offer=await this.rtc(pc.createOffer(),'offer');if(epoch!==this.epoch)return;await this.rtc(pc.setLocalDescription(offer),'local_description');}
+   if(remote.remoteDescription&&!pc.remoteDescription){await this.rtc(pc.setRemoteDescription(remote.remoteDescription),'remote_description');if(epoch!==this.epoch)return;if(!remote.offerer){const answer=await this.rtc(pc.createAnswer(),'answer');if(epoch!==this.epoch)return;await this.rtc(pc.setLocalDescription(answer),'local_description');}}
+   if(epoch!==this.epoch)return;
+   if(pc.localDescription&&!p.localSent){p.description??={type:pc.localDescription.type,sdp:pc.localDescription.sdp};await this.request('groups/description',{callId:call.id,peerId:remote.id,description:p.description});p.localSent=true;}
+   await this.flushCandidates(p,call.id,remote.id,epoch);if(epoch!==this.epoch)return;
+   if(pc.remoteDescription)while(p.remoteCount<remote.remoteCandidates.length){await this.rtc(pc.addIceCandidate(remote.remoteCandidates[p.remoteCount]),'candidate');if(epoch!==this.epoch)return;p.remoteCount++;}
+   if(pc.connectionState==='connected'&&!p.connectedSent){await this.request('groups/connected',{callId:call.id,peerId:remote.id});p.connectedSent=true;}
+  }));
+  const failure=negotiations.find(result=>result.status==='rejected');if(failure)throw failure.reason;
+  this.emit();
+ }
+ async flushCandidates(peer,callId,peerId,epoch){
+  if(peer.sendingCandidates)return peer.sendingCandidates;
+  const work=Promise.resolve().then(async()=>{
+   while(peer.candidates.length&&epoch===this.epoch&&!this.closed){
+    // A bounded batch avoids one network round trip per ICE address. The server
+    // deduplicates retries, including a response lost after accepting a candidate.
+    const batch=peer.candidates.slice(0,4);
+    const results=await Promise.allSettled(batch.map(candidate=>this.request('groups/candidate',{callId,peerId,candidate})));
+    if(epoch!==this.epoch||this.closed)return;
+    results.forEach((result,index)=>{if(result.status==='fulfilled'){const i=peer.candidates.indexOf(batch[index]);if(i>=0)peer.candidates.splice(i,1);}});
+    const failed=results.find(result=>result.status==='rejected');if(failed)throw failed.reason;
+   }
+  });
+  peer.sendingCandidates=work;
+  try{return await work;}finally{if(peer.sendingCandidates===work)peer.sendingCandidates=null;}
+ }
+ async startScreenSharing(){const result=await this.sharing.start();if(result)await this.apply(result);}
+ stopScreenSharing(){return this.sharing.stop();}
+ async hold(){if(!this.state.call||this.state.localHeld)return;this.state.localHeld=true;this.syncTracks();this.emit();await this.sharing.stop().catch(()=>{});try{await this.request('groups/hold',{callId:this.state.call.id,held:true,revision:++this.holdRevision});this.holdDeadline=this.state.call.holdExpiresAt||Date.now()+300000;}catch(e){await this.leave();throw e;}}
+ async resume(prepareAudio){if(!this.state.localHeld)return;await prepareAudio?.();await this.request('groups/hold',{callId:this.state.call.id,held:false,revision:++this.holdRevision});this.lastSuccess=Date.now();this.state.localHeld=false;this.syncTracks();this.emit();}
+ async leave(){const call=this.state.call;++this.epoch;this.ended??=new Set();if(call)this.ended.add(call.id);while(this.ended.size>256)this.ended.delete(this.ended.values().next().value);this.reset();this.state.call=null;this.state.error=null;this.emit();if(call)await this.request('groups/leave',{callId:call.id});}
+ reset(){clearTimeout(this.ringTimer);this.ringCallId=null;this.sharing.reset();++this.epoch;for(const cancel of this.pendingRTC)cancel();this.pendingRTC.clear();this.holdDeadline=0;for(const p of this.peers.values())p.pc.close();this.peers.clear();this.stream?.getTracks().forEach(t=>t.stop());this.stream=null;Object.assign(this.state,{localStream:null,remoteStreams:{},localHeld:false,connectedAt:null});this.holdRevision=0;}
+ async dispose(){this.events?.close();if(this.closed)return;this.closed=true;clearTimeout(this.timer);clearInterval(this.watch);try{await this.leave();}finally{await this.request('close',{}).catch(()=>{});}}
+}

package/dist/history.js

@@ -18,10 +18,10 @@ export function mergeCallHistory(saved, page) {
   return { cursor: page.nextCursor, entries: [...byId.values()].sort((a,b) => a.sequence - b.sequence) };
 }
 export function describeCall(entry) {
-  const incoming = entry.role === 'callee';
-  if (entry.connectedAt != null) return { label: incoming ? 'Incoming voice call' : 'Outgoing voice call',
+  const incoming = entry.role === 'callee', kind = entry.kind === 'video' ? 'video' : 'voice';
+  if (entry.connectedAt != null) return { label: incoming ? `Incoming ${kind} call` : `Outgoing ${kind} call`,
     detail: `${Math.floor(entry.durationMs / 60000)}:${String(Math.floor(entry.durationMs / 1000) % 60).padStart(2, '0')}`, missed: false };
-  if (entry.reason === 'declined') return { label: incoming ? 'Declined voice call' : 'Call declined', detail: '', missed: incoming };
-  if (['cancelled', 'no_answer'].includes(entry.reason)) return { label: incoming ? 'Missed voice call' : entry.reason === 'cancelled' ? 'Cancelled voice call' : 'No answer', detail: '', missed: incoming };
+  if (entry.reason === 'declined') return { label: incoming ? `Declined ${kind} call` : 'Call declined', detail: '', missed: incoming };
+  if (['cancelled', 'no_answer'].includes(entry.reason)) return { label: incoming ? `Missed ${kind} call` : entry.reason === 'cancelled' ? `Cancelled ${kind} call` : 'No answer', detail: '', missed: incoming };
   return { label: 'Call couldn’t connect', detail: '', missed: incoming };
 }

package/dist/index.d.ts

@@ -1,23 +1,30 @@
-export interface CallHistoryEntry { id: string; sequence: number; connectionId: string; role: 'caller' | 'callee'; reason: string; createdAt: number; answeredAt: number | null; connectedAt: number | null; endedAt: number; durationMs: number }
+export interface CallHistoryEntry { id: string; sequence: number; connectionId: string; kind?: 'voice' | 'video'; role: 'caller' | 'callee'; reason: string; createdAt: number; answeredAt: number | null; connectedAt: number | null; endedAt: number; durationMs: number }
 export interface CallHistoryPage { entries: CallHistoryEntry[]; nextCursor: number; hasMore: boolean }
 export type CallState = 'ringing' | 'connecting' | 'connected' | 'ended';
-export interface Call { id: string; version: number; connectionId: string; state: CallState; role: 'caller' | 'callee'; controlled: boolean; reason?: string; remoteDescription: RTCSessionDescriptionInit | null; remoteCandidates: RTCIceCandidateInit[]; createdAt: number; ringExpiresAt?: number; ringRemainingMs?: number; localHeld?: boolean; remoteHeld?: boolean; holdExpiresAt?: number | null; holdRevision?: number; answeredAt?: number; connectedAt?: number; endedAt?: number }
-export interface Snapshot { voiceAvailable: boolean; call: Call | null; muted: boolean; localHeld?: boolean; error: string | null; preparing?: boolean; nativePresentation?: { mode?: string; dismissedCallIds?: string[]; speakerEnabled?: boolean; callerNames?: Record<string, string>; appOwnedCallIds?: string[]; appAnsweringCallIds?: string[]; appRingingCallIds: string[]; systemRingingCallIds: string[] } | null }
-export type Request = (operation: string, payload?: Record<string, unknown>) => Promise<any>;
-export function createHttpTransport(options: { baseUrl: string; token: string; fetcher?: typeof fetch }): Request;
+export interface Call {
+  self?:number;screenSharingAvailable?:boolean;sharing?:boolean[]; id: string; version: number; connectionId: string; kind?: 'voice' | 'video'; state: CallState; role: 'caller' | 'callee'; controlled: boolean; reason?: string; remoteDescription: RTCSessionDescriptionInit | null; remoteCandidates: RTCIceCandidateInit[]; createdAt: number; ringExpiresAt?: number; ringRemainingMs?: number; localHeld?: boolean; remoteHeld?: boolean; holdExpiresAt?: number | null; holdRevision?: number; answeredAt?: number; connectedAt?: number; endedAt?: number }
+export interface Snapshot { listeningStatus?: EventStatus;screenSharing?:boolean;screenSharePending?:boolean;displayStream?:MediaStream|null; voiceAvailable: boolean; videoAvailable?: boolean; cameraEnabled?: boolean; call: Call | null; muted: boolean; localHeld?: boolean; error: string | null; preparing?: boolean; nativePresentation?: { mode?: string; dismissedCallIds?: string[]; speakerEnabled?: boolean; callerNames?: Record<string, string>; appOwnedCallIds?: string[]; appAnsweringCallIds?: string[]; appRingingCallIds: string[]; systemRingingCallIds: string[] } | null }
+export interface EventSubscription { setEnabled(enabled: boolean): void; close(): void }
+export type EventStatus = 'connecting' | 'listening' | 'reconnecting' | 'disconnected' | 'paused' | 'session_expired' | 'access_revoked';
+export interface Request { (operation: string, payload?: Record<string, unknown>): Promise<any>; subscribe?: (callbacks: {onEvent: () => void; onStatus?: (status: EventStatus) => void; onError?: (error: Error & {status?: number}) => void}) => EventSubscription }
+export function createHttpTransport(options: { baseUrl: string; token: string; fetcher?: typeof fetch; events?: boolean; WebSocketImpl?: typeof WebSocket }): Request;
 export class RobonoCallingClient {
-  constructor(options: { request: Request; onChange?: (state: Snapshot) => void; onRemoteStream?: (stream: MediaStream | null) => void; getUserMedia?: (context?: { isCurrent: () => boolean }) => Promise<MediaStream>; createPeerConnection?: (config: RTCConfiguration) => RTCPeerConnection; pollMs?: number; forceRelay?: boolean; createId?: () => string; createRemoteStream?: (track: MediaStreamTrack) => MediaStream });
+  constructor(options: { videoQuality?: '480p' | '720p'; request: Request; onSessionExpired?: (error: Error) => void; onChange?: (state: Snapshot) => void; onLocalStream?: (stream: MediaStream | null) => void; onRemoteStream?: (stream: MediaStream | null) => void; getDisplayMedia?:(context?:{isCurrent:()=>boolean})=>Promise<MediaStream>;getUserMedia?: (context?: { kind?: 'voice' | 'video'; videoQuality?: '480p'|'720p'; isCurrent: () => boolean }) => Promise<MediaStream>; createPeerConnection?: (config: RTCConfiguration) => RTCPeerConnection; pollMs?: number; forceRelay?: boolean; createId?: () => string; createRemoteStream?: (track: MediaStreamTrack) => MediaStream });
   state: Snapshot;
   readonly closed: boolean;
   listen(): Promise<void>;
   refresh(): Promise<boolean>;
-  call(connectionId?: string): Promise<void>;
+  call(connectionId?: string, options?: {kind?: 'voice' | 'video'}): Promise<void>;
   history(query?: { after?: number; limit?: number; connectionId?: string }): Promise<CallHistoryPage>;
-  availability(connectionId: string): Promise<{ voiceAvailable: boolean; reason?: 'ready' | 'calling_not_enabled' | 'contact_unavailable' }>;
+  availability(connectionId: string): Promise<{ voiceAvailable: boolean; videoAvailable?: boolean; reason?: 'ready' | 'calling_not_enabled' | 'contact_unavailable'; videoReason?: 'ready' | 'calling_not_enabled' | 'contact_unavailable' }>;
   answer(): Promise<void>;
   hangUp(): Promise<void>;
   hold(): Promise<void>;
   resume(prepareAudio?: () => Promise<void>): Promise<void>;
+  setForeground(value: boolean): void;
+  setVideoForeground(value: boolean): void;
+  startScreenSharing():Promise<void>;stopScreenSharing():Promise<void>;
+  setCamera(enabled: boolean): void;
   mute(muted?: boolean): void;
   dispose(): Promise<void>;
 }

package/dist/index.js

@@ -1,9 +1,13 @@
-/** Audio-only calling client. Media and identity adapters are supplied by the host. */
-export function createHttpTransport({ baseUrl, token, fetcher = fetch }) {
-  return async (operation, payload = {}) => {
+import {subscribeCallingEvents} from './events.js';
+import {createTransportTelemetry} from './telemetry.js';
+import {mediaProfile,videoConstraints,limitSender} from './media-profile.js';
+import {createScreenSharing} from './sharing.js';
+/** Voice and video calling client. Media and identity adapters are supplied by the host. */
+export function createHttpTransport({ baseUrl, token, fetcher = fetch, events = true, WebSocketImpl = globalThis.WebSocket }) {
+  const request = async (operation, payload = {}) => {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 4500);
-    try {
+    let timer;
+    const work = (async () => {
       const response = await fetcher(`${baseUrl}/${operation}`, {
       method: 'POST', headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
       body: JSON.stringify(payload), signal: controller.signal, redirect: 'error',
@@ -29,23 +33,36 @@ export function createHttpTransport({ baseUrl, token, fetcher = fetch }) {
         throw e;
       }
       return data;
-    } finally { clearTimeout(timer); }
+    })();
+    // Native fetch cancellation may abort the socket without settling its promise.
+    // Bound the complete operation ourselves, including response-body decoding.
+    const deadline = new Promise((_, reject) => { timer = setTimeout(() => {
+      controller.abort(); reject(Error('request_timeout'));
+    }, 4500); });
+    try { return await Promise.race([work, deadline]); } finally { clearTimeout(timer); }
   };
+  if(events && WebSocketImpl) request.subscribe = callbacks => subscribeCallingEvents({baseUrl,token,WebSocketImpl},callbacks);
+  return request;
 }
 
 export class RobonoCallingClient {
-  constructor({ request, onChange = () => {}, onRemoteStream = () => {},
-    getUserMedia = () => navigator.mediaDevices.getUserMedia({ audio: true, video: false }),
+  constructor({ request, onSessionExpired = () => {}, onChange = () => {}, onRemoteStream = () => {}, onLocalStream = () => {},
+    getUserMedia = context => navigator.mediaDevices.getUserMedia({ audio: true, video: context?.kind === 'video' ? videoConstraints(context.videoQuality) : false }),
+    videoQuality = '720p',
     createPeerConnection = config => new RTCPeerConnection(config), pollMs = 1000, forceRelay = false, createId = () => crypto.randomUUID(),
+    getDisplayMedia = ()=>navigator.mediaDevices.getDisplayMedia({video:true,audio:false}),
     createRemoteStream = track => new MediaStream([track]) } = {}) {
-    Object.assign(this, { request, onChange, onRemoteStream, getUserMedia, createPeerConnection, pollMs, forceRelay, createId, createRemoteStream });
-    this.state = { voiceAvailable: false, call: null, muted: false, error: null };
+    Object.assign(this, { request, onSessionExpired, onChange, onRemoteStream, onLocalStream, getUserMedia, createPeerConnection, pollMs, forceRelay, createId, createRemoteStream });
+    this.videoQuality=mediaProfile(videoQuality).quality;
+    this.state = { voiceAvailable: false, call: null, muted: false, cameraEnabled: true, error: null };
     this.pc = null; this.stream = null; this.epoch = 0; this.busy = false; this.closed = false;
     this.lastSuccess = Date.now(); this.started = false; this.remoteCount = 0;
     this.pendingRTC = new Set(); this.mediaTimers = new Set();
     this.locallyEnded = new Set(); this.endRequests = new Map();
     this.expiredRings = new Set();
-    this.pollFailures = 0; this.pollNotBefore = 0;
+    this.pollFailures = 0; this.pollNotBefore = 0; this.foreground = true;
+    this.sharing=createScreenSharing({limitVideo:sender=>limitSender(sender,this.activeVideoQuality??this.videoQuality),request:input=>this.retry('sharing',input),call:()=>this.state.call,peers:()=>this.pc?[this.pc]:[],stream:()=>this.stream,capture:getDisplayMedia,emit:()=>this.emit(),fail:e=>{this.state.error=e.message;this.emit();}});
+    this.reportTransport=createTransportTelemetry(request);
     this.localHeld = false; this.holdRevision = 0; this.holdDeadline = 0;
   }
   rtc(promise, phase, timeoutMs = 8000) {
@@ -58,12 +75,13 @@ export class RobonoCallingClient {
   }
   emit() {
     const call = this.state.call;
+    if(this.events && call && call.state!=='ended' && !this.timer && !this.polling && !this.closed)this.timer=setTimeout(()=>this.poll(),3000);
     this.scheduleRingDeadline(call);
     // The local WebRTC transport, not a later server poll, determines when this
     // device can communicate. Keep the server snapshot separate for sequencing.
     const connected = this.mediaConnectedAt != null && this.mediaCallId === call?.id &&
       call.controlled && ['connecting', 'connected'].includes(call.state);
-    this.onChange({ ...this.state, preparing: this.busy, localHeld: this.localHeld,
+    this.onChange({ ...this.state,...this.sharing.state(), preparing: this.busy, localHeld: this.localHeld,
       call: connected ? { ...call, state: this.pc?.connectionState === 'disconnected' ? 'connecting' : 'connected', connectedAt: this.mediaConnectedAt } : call });
   }
   scheduleRingDeadline(call) {
@@ -96,13 +114,26 @@ export class RobonoCallingClient {
       // Explicit authorization failures still stop media immediately in refresh.
       const heldLease = this.localHeld && this.holdDeadline > Date.now();
       const unconfirmedHold = this.pendingHold && Date.now() - this.pendingHold.at > 10000;
-      if ((this.pc || this.stream) && (unconfirmedHold || !heldLease && Date.now() - this.lastSuccess > 10000)) {
+      if (!this.busy && this.mediaCallId && (this.pc || this.stream) && (unconfirmedHold || !heldLease && Date.now() - this.lastSuccess > 10000)) {
         const id = this.state.call?.id; this.finishLocal('connection_lost');
         if (id) this.request('end', { callId: id }).catch(() => {});
       }
     }, 500);
+    if(this.request.subscribe) this.events=this.request.subscribe({
+      onEvent:()=>this.wake(), onStatus:status=>{this.state.listeningStatus=status;this.emit();},
+      onError:e=>this.sessionError(e),
+    });
     await this.poll();
   }
+  sessionError(e) {
+    const active=this.state.call && this.state.call.state!=='ended';
+    this.state.error=active?e.message:null;this.state.listeningStatus=e.status===403?'access_revoked':'session_expired';
+    this.resetMedia();this.closed=true;clearTimeout(this.timer);clearInterval(this.watchdog);this.events?.close();this.emit();
+    if(e.status===401)this.onSessionExpired(e);
+  }
+  wake(){if(this.closed)return;clearTimeout(this.timer);if(this.polling||this.busy){this.eventPending=true;return;}void this.poll();}
+  setForeground(value){this.foreground=value;this.setVideoForeground(value);this.events?.setEnabled(value||!!this.state.call&&this.state.call.state!=='ended');if(value)this.wake();else if(!this.state.call||this.state.call.state==='ended')clearTimeout(this.timer);}
+
   // Refresh without scheduling a second poll loop (also used for native wake races).
   // False means the cached snapshot is not authoritative for this attempt.
   async refresh() {
@@ -115,14 +146,14 @@ export class RobonoCallingClient {
     if (this.closed || Date.now() < this.pollNotBefore) return false;
     const epoch = this.epoch;
     try {
-      const state = await this.request('state');
+      const state = await this.request('state', {mediaKinds:['voice','video']});
       if (this.closed) return false;
       this.lastSuccess = Date.now();
       this.pollFailures = 0; this.pollNotBefore = 0;
       if (epoch === this.epoch) {
         this.state.error = null;
         if (!this.busy && !(state.version < (this.state.call?.version ?? -1))) {
-          this.state.voiceAvailable = state.voiceAvailable;
+          this.state.voiceAvailable = state.voiceAvailable; this.state.videoAvailable = state.videoAvailable === true;
           await this.apply(state.call);
           if (this.pendingHold) await this.confirmHold(this.pendingHold);
           return true;
@@ -134,16 +165,26 @@ export class RobonoCallingClient {
       this.pollNotBefore = Date.now() + Math.max(delay, Number.isFinite(e.retryAfterMs) ? e.retryAfterMs : 0);
       // Credential revocations remain authoritative even after a local action.
       if (epoch === this.epoch || e.status === 401 || e.status === 403) {
-        this.state.error = e.message;
-        if (e.status === 401 || e.status === 403) { this.resetMedia(); this.closed = true; clearInterval(this.watchdog); }
+        if(e.status===401||e.status===403){this.sessionError(e);return false;}
+        this.state.error = this.state.call && this.state.call.state!=='ended' ? e.message : null;
         this.emit();
       }
     }
     return false;
   }
   async poll() {
-    await this.refresh();
-    if (!this.closed) this.timer = setTimeout(() => this.poll(), Math.min(2147483647, Math.max(this.pollMs, this.pollNotBefore - Date.now())));
+    if(this.closed||this.polling)return;
+    this.polling=true;this.timer=null;
+    try{await this.refresh();
+      this.reportTransport(this.state.call?.state==='connected'?this.state.call.id:null,this.pc?[['direct',this.pc]]:[]);
+    }finally{this.polling=false;}
+    if(this.closed)return;
+    const active=this.state.call&&this.state.call.state!=='ended';
+    if(!this.foreground&&!active){this.events?.setEnabled(false);return;}
+    const eventPending=this.eventPending;this.eventPending=false;
+    const retry=this.pollFailures>0&&this.pollFailures<6;
+    const delay=Math.max(eventPending?0:this.events?3000:this.pollMs,this.pollNotBefore-Date.now());
+    if(active||!this.events||retry||eventPending)this.timer=setTimeout(()=>this.poll(),Math.min(2147483647,delay));
   }
   async apply(call) {
     // A pending/late server poll cannot reopen a call the person already ended.
@@ -168,12 +209,13 @@ export class RobonoCallingClient {
       }
     }
     if (wasHeld && !call.remoteHeld && !this.localHeld) this.checkResumedTransport();
-    this.syncAudioTracks();
+    this.sharing.sync();this.syncAudioTracks();
     this.emit();
   }
   syncAudioTracks() {
     const held = this.localHeld || this.state.call?.localHeld || this.state.call?.remoteHeld;
     this.stream?.getAudioTracks().forEach(t => { t.enabled = !held && !this.state.muted; });
+    this.stream?.getVideoTracks().forEach(t => { t.enabled = !held && this.videoForeground !== false && this.state.cameraEnabled; });
     this.remoteStream?.getAudioTracks().forEach(t => { t.enabled = !held; });
   }
   /** Silence immediately; only a server-acknowledged hold relaxes the lease. */
@@ -181,6 +223,7 @@ export class RobonoCallingClient {
     const call = this.state.call;
     if (!call?.controlled || call.state !== 'connected' || !this.pc) throw Error('call_not_connected');
     this.localHeld = true; this.syncAudioTracks(); this.emit();
+    await this.sharing.stop().catch(()=>{});
     const revision = this.holdRevision = Math.max(this.holdRevision, call.holdRevision || 0) + 1;
     const intent = this.pendingHold = {callId: call.id, held: true, revision, at: Date.now()};
     await this.confirmHold(intent);
@@ -224,6 +267,7 @@ export class RobonoCallingClient {
     }
   }
   resetMedia() {
+    this.sharing.reset();
     this.epoch++;
     for (const timer of this.mediaTimers) clearTimeout(timer); this.mediaTimers.clear();
     for (const cancel of this.pendingRTC) cancel();
@@ -231,25 +275,31 @@ export class RobonoCallingClient {
     if (pc) { pc.onicecandidate = pc.onconnectionstatechange = pc.ontrack = null; pc.close(); }
     this.stream?.getTracks().forEach(t => t.stop()); this.stream = null;
     this.remoteStream = null; this.localHeld = false; this.holdDeadline = 0; this.holdRevision = 0; this.pendingHold = null;
-    this.candidates = []; this.remoteCount = 0; this.mediaCallId = null; this.mediaConnectedAt = null; this.state.muted = false;
-    this.onRemoteStream(null);
+    this.candidates = []; this.remoteCount = 0; this.mediaCallId = null; this.mediaConnectedAt = null; this.state.muted = false; this.state.cameraEnabled = true;
+    this.onRemoteStream(null); this.onLocalStream(null);
   }
-  async prepare(connectionId) {
+  async prepare(connectionId, kind = 'voice') {
     this.resetMedia(); const epoch = this.epoch;
-    const ice = await this.request('ice', connectionId ? { connectionId } : {});
+    const ice = await this.request('ice', { ...(connectionId ? { connectionId } : {}), kind });
     if (this.closed || epoch !== this.epoch) throw Error('call_cancelled');
     if (this.forceRelay && !ice.relayAvailable) throw Error('relay_not_configured');
-    const stream = await this.rtc(this.getUserMedia({ isCurrent: () => !this.closed && epoch === this.epoch }).then(stream => {
+    this.activeVideoQuality=ice.videoQuality==='480p'?'480p':this.videoQuality;
+    const stream = await this.rtc(this.getUserMedia({ kind, videoQuality: ice.videoQuality === '480p' ? '480p' : this.videoQuality, isCurrent: () => !this.closed && epoch === this.epoch }).then(stream => {
       if (this.closed || epoch !== this.epoch) stream.getTracks().forEach(t => t.stop());
       return stream;
     }), 'microphone', 30000);
     if (this.closed || epoch !== this.epoch) { stream.getTracks().forEach(t => t.stop()); throw Error('call_cancelled'); }
-    if (!stream.getAudioTracks().length || stream.getVideoTracks().length) { stream.getTracks().forEach(t => t.stop()); throw Error('audio_only'); }
-    this.stream = stream;
+    if (stream.getAudioTracks().length !== 1 || stream.getVideoTracks().length !== (kind === 'video' ? 1 : 0)) { stream.getTracks().forEach(t => t.stop()); throw Error(kind === 'video' ? 'camera_required' : 'audio_only'); }
+    this.stream = stream; this.syncAudioTracks(); this.onLocalStream(stream);
     const pc = this.pc = this.createPeerConnection({ iceServers: ice.iceServers, iceTransportPolicy: this.forceRelay ? 'relay' : 'all' });
     this.candidates = []; this.sendTail = Promise.resolve();
-    for (const track of stream.getAudioTracks()) pc.addTrack(track, stream);
-    pc.ontrack = e => { if (this.pc === pc) { this.remoteStream = e.streams[0] || this.createRemoteStream(e.track); this.syncAudioTracks(); this.onRemoteStream(this.remoteStream); } };
+    for (const track of stream.getTracks()){const sender=pc.addTrack(track, stream);if(track.kind==='video')await limitSender(sender,ice.videoQuality==='480p'?'480p':this.videoQuality);}
+    pc.ontrack = e => { if (this.pc === pc) {
+      if (e.streams?.[0]) this.remoteStream = e.streams[0];
+      else if (!this.remoteStream) this.remoteStream = this.createRemoteStream(e.track);
+      else if (!this.remoteStream.getTracks().some(t => t.id === e.track.id)) this.remoteStream.addTrack(e.track);
+      this.syncAudioTracks(); this.onRemoteStream(this.remoteStream);
+    } };
     pc.onicecandidate = e => {
       if (!e.candidate || this.pc !== pc) return;
       this.candidates.push(e.candidate.toJSON()); this.flushCandidates();
@@ -304,7 +354,7 @@ export class RobonoCallingClient {
     this.busy = true; this.state.error = null; this.emit();
     try { return await fn(); }
     catch (e) { this.mediaError(e); throw e; }
-    finally { this.busy = false; this.emit(); }
+    finally { this.busy = false; this.emit(); if(this.eventPending){this.eventPending=false;this.wake();} }
   }
   async history(query = {}) { return this.request('history', query); }
   async availability(connectionId) { return this.request('availability', { connectionId }); }
@@ -312,15 +362,16 @@ export class RobonoCallingClient {
     try { return await this.request(operation, payload); }
     catch (e) { if (e.status && e.status < 500) throw e; return this.request(operation, payload); }
   }
-  async call(connectionId) {
+  async call(connectionId, {kind = 'voice'} = {}) {
+    if (!['voice','video'].includes(kind)) throw Error('invalid_call_kind');
     if (this.state.call && this.state.call.state !== 'ended') throw Error('busy');
     return this.action(async () => {
-      const pc = await this.prepare(connectionId); const epoch = this.epoch;
+      const pc = await this.prepare(connectionId, kind); const epoch = this.epoch;
       await this.rtc(pc.setLocalDescription(await this.rtc(pc.createOffer(), 'create_offer')), 'local_description');
       if (this.epoch !== epoch || this.closed) throw Error('call_cancelled');
-      const payload = { ...(connectionId ? { connectionId } : {}), requestId: this.createId(), description: { type: 'offer', sdp: pc.localDescription.sdp } };
+      const payload = { ...(connectionId ? { connectionId } : {}), kind, requestId: this.createId(), description: { type: 'offer', sdp: pc.localDescription.sdp } };
       // Retrying this exact request is safe: the service deduplicates requestId.
-      const call = await this.retry('start', payload);
+      const call = await this.retry('start', payload); this.lastSuccess = Date.now();
       if (this.epoch !== epoch) { await this.retry('end', { callId: call.id }); return; }
       this.state.call = call; this.mediaCallId = call.id; this.flushCandidates(); this.reportMediaConnection(pc); this.emit();
     });
@@ -329,11 +380,11 @@ export class RobonoCallingClient {
     const call = this.state.call;
     if (!call || call.role !== 'callee' || call.state !== 'ringing' || !call.controlled) throw Error('no_incoming_call');
     return this.action(async () => {
-      const pc = await this.prepare(call.connectionId), epoch = this.epoch;
+      const pc = await this.prepare(call.connectionId, call.kind || 'voice'), epoch = this.epoch;
       await this.rtc(pc.setRemoteDescription(call.remoteDescription), 'remote_description');
       await this.rtc(pc.setLocalDescription(await this.rtc(pc.createAnswer(), 'create_answer')), 'local_description');
       if (this.epoch !== epoch || this.closed) throw Error('call_cancelled');
-      const result = await this.retry('answer', { callId: call.id, description: { type: 'answer', sdp: pc.localDescription.sdp } });
+      const result = await this.retry('answer', { callId: call.id, description: { type: 'answer', sdp: pc.localDescription.sdp } }); this.lastSuccess = Date.now();
       if (this.epoch !== epoch) { await this.retry('end', { callId: call.id }); return; }
       this.state.call = result; this.mediaCallId = call.id; this.flushCandidates(); this.reportMediaConnection(pc); await this.apply(result);
     });
@@ -359,8 +410,16 @@ export class RobonoCallingClient {
     }
     this.emit();
   }
+  async startScreenSharing(){const result=await this.sharing.start();if(result&&this.state.call?.id===result.id)this.state.call=result;this.emit();}
+  stopScreenSharing(){return this.sharing.stop();}
+  setVideoForeground(value) { this.videoForeground = value; this.syncAudioTracks(); }
+  setCamera(enabled) {
+    if (typeof enabled !== 'boolean' || !this.stream?.getVideoTracks().length) return;
+    this.state.cameraEnabled = enabled; this.syncAudioTracks(); this.emit();
+  }
   mute(muted = true) { this.state.muted = muted; this.syncAudioTracks(); this.emit(); }
   async dispose() {
+    this.events?.close();
     this.closed = true; clearTimeout(this.timer); clearInterval(this.watchdog);
     clearTimeout(this.ringTimer);
     await this.hangUp();

package/dist/media-profile.js

@@ -0,0 +1,18 @@
+/** Shared capture and per-peer send limits. Resolution is a ceiling, not a promise. */
+export function mediaProfile(quality='720p') {
+ if(!['480p','720p'].includes(quality))throw Error('invalid_video_quality');
+ return quality==='480p'?{quality,width:854,height:480,frameRate:24,maxBitrate:600000}:{quality,width:1280,height:720,frameRate:24,maxBitrate:1500000};
+}
+export function videoConstraints(quality){const p=mediaProfile(quality);return {facingMode:'user',width:{ideal:p.width,max:p.width},height:{ideal:p.height,max:p.height},frameRate:{ideal:p.frameRate,max:p.frameRate}};}
+export async function limitSender(sender,quality){
+ // Some hosts supply a custom transport. A real RTCRtpSender supports these APIs.
+ if(!sender?.getParameters||!sender?.setParameters)return;
+ const profile=mediaProfile(quality),settings=sender.track?.getSettings?.()??{};
+ // Native cameras may select a supported capture size above the requested one.
+ // Limit what is transmitted, including portrait and replacement display tracks.
+ const width=Number(settings.width)||0,height=Number(settings.height)||0;
+ const scale=Math.max(1,Math.max(width,height)/profile.width,Math.min(width,height)/profile.height);
+ const p=sender.getParameters();if(!p.encodings?.length)p.encodings=[{}];
+ for(const encoding of p.encodings){encoding.maxBitrate=profile.maxBitrate;encoding.maxFramerate=profile.frameRate;encoding.scaleResolutionDownBy=scale;}
+ await sender.setParameters(p);
+}

package/dist/sharing.js

@@ -0,0 +1,46 @@
+/** Replaces the existing video track. Microphone routing and call transport stay intact. */
+export function createScreenSharing({request,call,peers,stream,capture,emit,fail,limitVideo=async()=>{}}) {
+ let display=null,camera=null,generation=0,revision=0,pending=null,stopping=null,active=false,replaceTail=Promise.resolve();
+ const stopTracks=s=>s?.getTracks().forEach(t=>{t.onended=null;t.stop();});
+ const state=()=>({screenSharing:active,screenSharePending:!!pending||!!stopping,displayStream:display});
+ const replace=track=>{const targets=[...peers()];const work=replaceTail.catch(()=>{}).then(async()=>{for(const pc of targets){const sender=pc.getSenders().find(s=>s.track?.kind==='video');if(!sender)throw Error('video_track_required');await sender.replaceTrack(track);await limitVideo(sender);}});replaceTail=work;return work;};
+ const stop=(notify=true)=>{
+  if(stopping)return stopping;
+  if(!display&&!pending&&!active)return Promise.resolve();
+  ++generation;const old=display,restore=camera,c=call();display=null;camera=null;active=false;
+  stopTracks(old);
+  const work=Promise.resolve().then(async()=>{
+   // Serialize against an in-flight replacement; never restore over a newer share.
+   if(restore&&stream()?.getVideoTracks().includes(restore))try{await replace(restore);}catch(e){fail(e);}
+   if(notify&&c?.id&&c.state!=='ended')await request({callId:c.id,sharing:false,revision:++revision});
+  }).finally(()=>{if(stopping===work){stopping=null;emit();}});
+  stopping=work;emit();return work;
+ };
+ return {state,
+  async start(){
+   const c=call();if(pending||stopping||active)throw Error('screen_share_busy');
+   if(!c||c.kind!=='video'||c.state!=='connected'||!c.controlled||!c.screenSharingAvailable||c.localHeld||c.remoteHeld)throw Error('screen_share_unavailable');
+   if(c.sharing?.some(Boolean))throw Error('screen_already_shared');
+   if(!capture)throw Error('screen_capture_adapter_required');
+   const epoch=++generation,token={};pending=token;emit();let captured;
+   try{
+    // Invoked immediately from the person's tap; browsers require user activation.
+    captured=await capture({isCurrent:()=>epoch===generation&&call()?.id===c.id});
+    if(epoch!==generation||call()?.id!==c.id){stopTracks(captured);throw Error('call_cancelled');}
+    const track=captured.getVideoTracks()[0];if(!track||track.readyState==='ended')throw Error('screen_capture_unavailable');
+    // Never accidentally include system sound or another microphone track.
+    captured.getAudioTracks().forEach(t=>{t.stop();captured.removeTrack(t);});
+    const granted=await request({callId:c.id,sharing:true,revision:++revision});
+    if(epoch!==generation||call()?.id!==c.id){stopTracks(captured);await request({callId:c.id,sharing:false,revision:++revision});throw Error('call_cancelled');}
+    camera=stream()?.getVideoTracks()[0];if(!camera)throw Error('video_track_required');
+    display=captured;await replace(track);
+    if(epoch!==generation){stopTracks(captured);return;}
+    active=true;track.onended=()=>{void stop().catch(fail);};emit();return granted;
+   }catch(e){stopTracks(captured);if(epoch===generation)await stop().catch(fail);throw e;}
+   finally{if(pending===token){pending=null;emit();}}
+  },stop,
+  sync(){const c=call();if(active&&(!c?.screenSharingAvailable||!c.sharing?.[c.self]||c.localHeld||c.remoteHeld||c.state==='ended'))void stop(false).catch(fail);},
+  reset(){++generation;stopTracks(display);display=camera=null;active=false;pending=stopping=null;revision=0;},
+  track(){return active?display?.getVideoTracks()[0]:null;}
+ };
+}

package/dist/telemetry.js

@@ -0,0 +1,24 @@
+/** Transport counters only. Never sends candidates, addresses, media, or transcripts. */
+export function createTransportTelemetry(request){
+ let after=0,busy=false;
+ return function report(callId,peers){
+  if(!callId||busy||Date.now()<after||!peers.length)return;
+  after=Date.now()+15000;busy=true;
+  void (async()=>{
+   const samples=[];
+   for(const [id,pc] of peers){
+    if(typeof pc?.getStats!=='function'||pc.connectionState!=='connected')continue;
+    let timer;const stats=await Promise.race([pc.getStats(),new Promise((_,reject)=>{timer=setTimeout(()=>reject(Error('stats_timeout')),1000);})]).finally(()=>clearTimeout(timer));
+    const rows=[];stats.forEach(r=>rows.push(r));const byId=new Map(rows.map(r=>[r.id,r]));
+    const sample={id,sentBytes:0,receivedBytes:0,relaySentBytes:0,relayReceivedBytes:0};
+    for(const r of rows)if(r.type==='candidate-pair'&&r.state==='succeeded'){
+     const sent=Number.isSafeInteger(r.bytesSent)&&r.bytesSent>=0?r.bytesSent:0,received=Number.isSafeInteger(r.bytesReceived)&&r.bytesReceived>=0?r.bytesReceived:0;
+     sample.sentBytes+=sent;sample.receivedBytes+=received;
+     if([r.localCandidateId,r.remoteCandidateId].some(key=>byId.get(key)?.candidateType==='relay')){sample.relaySentBytes+=sent;sample.relayReceivedBytes+=received;}
+    }
+    samples.push(sample);
+   }
+   if(samples.length)await request('telemetry',{callId,samples});
+  })().catch(()=>{}).finally(()=>{busy=false;});
+ };
+}

package/package.json

@@ -17,8 +17,8 @@
     "provenance": true
   },
   "name": "@robono/calling",
-  "version": "0.1.2",
-  "description": "One-to-one WebRTC voice calling for connected Robono Bridge networks.",
+  "version": "0.2.0",
+  "description": "WebRTC voice, video, group calling and screen sharing within apps and across Robono Bridge networks.",
   "homepage": "https://robono.com/docs#calling",
   "repository": {
     "type": "git",
@@ -35,6 +35,10 @@
     "./history": {
       "types": "./dist/history.d.ts",
       "import": "./dist/history.js"
+    },
+    "./groups": {
+      "types": "./dist/groups.d.ts",
+      "import": "./dist/groups.js"
     }
   },
   "files": [
@@ -49,8 +53,7 @@
   },
   "scripts": {
     "build": "node build.mjs",
-    "test": "npm run build && node --test test/client.test.mjs test/package.test.mjs",
-    "test:integration": "node --test test/*.test.mjs",
+    "test": "npm run build && node --test test/client.test.mjs test/package.test.mjs test/group-client.test.mjs test/sharing.test.mjs test/telemetry.test.mjs test/events.test.mjs",
     "prepack": "npm run build && node ../../scripts/generate-package-sbom.mjs",
     "prepublishOnly": "npm test"
   }