Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
feat(quality): implement strict v13 quality shadow (#291)
AAA501df27bce62
diff --git a/docs/adr/0005-automatic-hybrid-media-routing.md b/docs/adr/0005-automatic-hybrid-media-routing.mdindex dcef0a84..f8b58c3e 100644--- a/docs/adr/0005-automatic-hybrid-media-routing.md+++ b/docs/adr/0005-automatic-hybrid-media-routing.md@@ -1,8 +1,8 @@# ADR-0005: Automatic Hybrid Media Routing- Status: Base routing is deployed on strict v12. The evidence-only quality- shadow and atomic strict-v13 upgrade are accepted but not yet implemented or- deployed. Exact current identity is owned by+ shadow is implemented in canonical source on strict v13 but not yet deployed.+ Exact current identity is owned by[status](../status.md).- Date: 2026-08-20- Last updated: 2026-08-27@@ -361,8 +361,8 @@ current-candidate-start, first-decoded-frame, and final-outcome timing. A newdemand overwrites that child's record; authoritative share stop/replacement,confirmed departure, and room deletion remove it.-An authenticated Host acceptance harness may request one snapshot. The accepted-v12 product UI exposes no diagnostic download button. The response+An authenticated Host acceptance harness may request one snapshot. The current+product UI exposes no diagnostic download button. The responsereads the current graph, current operation, and latest records; the server doesnot push a periodic snapshot stream, start a timer, retain an event ring, log orpersist the result, or create a second graph. Snapshot-local ordinals express@@ -424,10 +424,10 @@ deployment-wide.## Current Source And Deployment Boundary-Production and canonical application/runtime source currently use strict-`screener-v12`; the accepted quality-shadow integration atomically replaces it-with strict `screener-v13`. Exact current source-and deployment identity is indexed by [status](../status.md).+Canonical application/runtime source uses the evidence-only strict+`screener-v13` quality shadow; production remains strict `screener-v12` until+its atomic application release. Exact current source and deployment identity is+indexed by [status](../status.md).Browser SFU PCs use empty external ICE-server lists. The controlled exact-candidate rollback/SFU commit and active-SFU cadence gates are closed. Theoperation owner remains only `route`; broader heterogeneous-network and SFUdiff --git a/docs/project-memory.md b/docs/project-memory.mdindex b8d52fac..613f9e9d 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -1,6 +1,6 @@# Project Memory-Last updated: 2026-08-26+Last updated: 2026-08-27## Current Product Truth@@ -120,13 +120,14 @@ Last updated: 2026-08-26## Current Source And Production-- Production and canonical source use the same strict `screener-v12`- application with adaptive H.264/VP8 selection, local Host codec override and+- Canonical source uses the evidence-only strict `screener-v13` quality shadow;+ production remains strict `screener-v12` until the atomic application release.+ Both retain adaptive H.264/VP8 selection, the local Host codec override andoptional SQLite room authority. Exact identities are indexed by[status](./status.md).-- The accepted quality-shadow integration atomically replaces v12 with strict- `screener-v13`; old Browser pages must fail before room authority. It adds no- active route decision until production shadow evidence is accepted.+- Strict v13 rejects old Browser pages before room authority. Its bounded+ current-edge aggregate adds no active route decision until annotated+ production shadow evidence establishes an accepted policy.- Production uses SQLite-backed random rooms, 20-Viewer admission, endpoint cap `2`,fixed 9,000-publication ingress and `9000 * 20` subscription egress admission,STUN UDP 3478, LiveKit media UDP 7882, and Web TCP 80/443. Node 8787 and@@ -137,7 +138,8 @@ Last updated: 2026-08-26## Current Priority-1. Complete the evidence-only quality-route shadow on strict `screener-v13`.+1. Deploy the evidence-only strict `screener-v13` quality shadow and collect+ annotated production samples.2. Complete the mobile Viewer lifecycle matrix and representative real-networkroute/media acceptance.diff --git a/docs/research/realtime-quality-adaptation.md b/docs/research/realtime-quality-adaptation.mdindex fe6156c9..bee00669 100644--- a/docs/research/realtime-quality-adaptation.md+++ b/docs/research/realtime-quality-adaptation.md@@ -2,8 +2,8 @@- Research date: 2026-08-26- Scope: Browser game-screen capture, encoding, P2P forwarding, and LiveKit SFU-- Status: current Browser policy accepted; real-game, weak-device, and- heterogeneous-network quality remain open+- Status: strict-v13 evidence-only quality shadow implemented in canonical+ source; production sampling and active policy remain open## Current Conclusion@@ -354,9 +354,8 @@ page refresh also rebinds the same stable participant and committed graph.Only actual recovery exhaustion enters the normal route-failure operation andtries other eligible P2P parents before SFU.-Quality-driven relay abdication or active parent switching would require-counterfactual alternative-path evidence, bounded probing, and a separate-ADR-0005 decision. It is not implemented or authorized by current diagnostics.+Quality-driven relay abdication or active parent switching requires evidence+that current diagnostics do not yet provide. No active policy is implemented.The reopened quality-selection research retains that information boundary.Current-route WebRTC stats can prove user-visible degradation but cannot prove@@ -374,7 +373,7 @@ quality ceiling as a delivered floor requires a separate product SLO. Relayingress degradation reparents that relay while retaining its subtree; onechild's degradation moves only that child.-The accepted first stage is shadow evaluation only. Viewer evidence adds the+The implemented first stage is shadow evaluation only. Viewer evidence adds thestandard cumulative-renderer deltas `freezeCount`, `totalFreezesDuration`,`pauseCount` and `totalPausesDuration` and requires continuing`framesDecoded` progress. W3C alreadydiff --git a/docs/status.md b/docs/status.mdindex 785767b2..e28e3527 100644--- a/docs/status.md+++ b/docs/status.md@@ -42,7 +42,8 @@ This is the current execution index. Git history owns completed timelines;## Current Source-- Canonical `main` contains the same application tree deployed from `267e073`.+- Canonical `main` uses the evidence-only strict `screener-v13` quality shadow;+ production remains the strict-v12 application tree deployed from `267e073`.Optional SQLite stable authority, non-expiring local preferred code, atomicroom replacement and the Host codec selector are implemented; productionselects stable storage. Graceful restart, crash, timeout and network loss use@@ -57,6 +58,10 @@ This is the current execution index. Git history owns completed timelines;quality score, layer selector, periodic rebalancing, or quality-driven parentchange. P2P and SFU recover their current route before actual failure entersnormal reassignment.+- Current Viewer freeze/pause evidence requires decoded progress and exact+ foreground presentation authority. The controller retains one bounded,+ fresh current-edge aggregate per child for the Host-only on-demand snapshot;+ it does not change route facts, capacity, candidates, SFU usage or reconcile.- Viewer hidden/freeze/pagehide suppress decoded-stall routing authority;visible/resume/pageshow rebaseline and rearm current-frame proof. SFUpagehide no longer triggers LiveKit's automatic disconnect. Native Viewer@@ -64,10 +69,8 @@ This is the current execution index. Git history owns completed timelines;## Current Milestone-1. Implement presentation-authoritative freeze/pause evidence with decoded- progress and the controller-owned shadow aggregate; collect production- samples without active route changes. This integration atomically replaces- current v12 with accepted strict `screener-v13`.+1. Atomically deploy strict `screener-v13`, then collect annotated production+ freeze/pause samples without active route changes.2. Finish the Android Chrome and iOS Safari Viewer lifecycle matrix.3. Finish representative public-network direct, peer-relay, SFU, recovery,Pause/Resume, screen-audio, real-game A/V, and all-UDP-blocked acceptancediff --git a/docs/todo.md b/docs/todo.mdindex 363aa83d..c153f327 100644--- a/docs/todo.md+++ b/docs/todo.md@@ -1,22 +1,18 @@# Current TODO Ledger-Last reviewed: 2026-08-26+Last reviewed: 2026-08-27Only **Now** is executable. A branch, old experiment, observation, or acceptedlater topic is not implementation authority by itself.## Now-1. **Quality-route evidence and shadow calibration.** Make current Viewer- quality evidence presentation-authoritative with standard freeze/pause- deltas, continuing decoded progress, exact presentation epochs and baseline- fencing. Keep one bounded- current-epoch aggregate per exact child in the existing room controller and- expose it only through the Host acceptance snapshot. It must not alter facts,- capacity, routes or SFU usage. Collect annotated production samples before- accepting an active trigger, probation, restore or cooldown policy. Ship it- only as the atomic strict `screener-v13` Browser/server contract; v12 gets no- compatibility path.+1. **Quality-route evidence and shadow calibration.** Atomically deploy the+ implemented strict `screener-v13` Browser/server quality shadow; v12 gets no+ compatibility path. Collect annotated production samples from its bounded+ current-edge freeze/pause aggregates before accepting an active trigger,+ probation, restore or cooldown policy. Shadow evidence must not alter facts,+ capacity, routes or SFU usage.2. **Mobile Viewer lifecycle.** Run Android Chrome and iOS Safari matrices forautoplay gesture, foreground/background audio, foreground video recovery,lock/page reclamation, rotation, Wi-Fi/cellular migration, and assigned-relaydiff --git a/docs/verification-status.md b/docs/verification-status.mdindex 78df91e1..70ad682e 100644--- a/docs/verification-status.md+++ b/docs/verification-status.md@@ -64,8 +64,9 @@ may be interpreted. Git and pull requests own routine completed checks.## Current Source Evidence-- Canonical source contains the same application tree deployed from `267e073`:- the adaptive H.264/VP8 sender decision with `contentHint = "motion"` reapplies the+- Canonical source uses strict `screener-v13`; production remains the strict-v12+ application tree deployed from `267e073`. The adaptive H.264/VP8 sender+ decision with `contentHint = "motion"` reapplies theselected video profile after answer negotiation, leaves SFU representationconstruction to pinned LiveKit, keeps Dynacast/send-side BWE, disablesAdaptiveStream, and disables SFU audio RED.@@ -76,6 +77,10 @@ may be interpreted. Git and pull requests own routine completed checks.authority, hidden-page stall suppression, retryable failure reporting, nativecontrols, and same-route manual reconnect are current source behavior. Mobilephysical evidence remains open.+- The evidence-only quality shadow accepts only exact foreground presentation+ windows with decoded progress, keeps one bounded fresh aggregate per current+ child, and exposes it through the Host-only anonymous route snapshot. It does+ not change route facts, capacity, candidate order, SFU admission or reconcile.## Open Physical Gatesdiff --git "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md" "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"index fcf3192d..4657e4c7 100644--- "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"+++ "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"@@ -2,7 +2,7 @@## 2026-08-18 14:45-状态:production 与 canonical source 当前使用严格 `screener-v12`;已接受的 quality-shadow 集成会把 Browser/server 原子升级为唯一 `screener-v13`,在 authority 前拒绝旧页面,不保留 v12 parser。当前已实现每分享代次的 H.264 sender gate 与 VP8 fallback、本地 pre-share `VP8 | 自动 | H264` selector、可选 SQLite stable room authority、无期限 preferred code 和换房控制;这些不新增 codec wire、自定义 SFU layer list或应用媒体质量 controller。Video 使用 `contentHint = "motion"`,audio 使用 `music`。SFU 由 pinned LiveKit 默认 representations、Dynacast、server send-side BWE 和 disabled AdaptiveStream 拥有质量适配;screen audio 使用 64/128/192 kbps ceiling、stereo、DTX off 与 RED off。精确执行状态由 `docs/status.md` 持有。+状态:canonical source 已实现唯一 strict `screener-v13` 的 evidence-only quality shadow,production 在原子应用发布前仍使用 strict `screener-v12`;旧页面在 authority 前拒绝,不保留 v12 parser。当前已实现每分享代次的 H.264 sender gate 与 VP8 fallback、本地 pre-share `VP8 | 自动 | H264` selector、可选 SQLite stable room authority、无期限 preferred code 和换房控制;这些不新增 codec wire、自定义 SFU layer list或应用媒体质量 controller。Video 使用 `contentHint = "motion"`,audio 使用 `music`。SFU 由 pinned LiveKit 默认 representations、Dynacast、server send-side BWE 和 disabled AdaptiveStream 拥有质量适配;screen audio 使用 64/128/192 kbps ceiling、stereo、DTX off 与 RED off。精确执行状态由 `docs/status.md` 持有。## 目标与边界diff --git a/src/client/media/viewer-presentation.ts b/src/client/media/viewer-presentation.tsindex 85345393..7b8d222e 100644--- a/src/client/media/viewer-presentation.ts+++ b/src/client/media/viewer-presentation.ts@@ -116,6 +116,7 @@ export type ViewerPresentationAction =}| { type: "media-bound"; generation: number; revision: number }| { type: "frame-presented"; generation: number; revision: number }+ | { type: "frame-proof-reset"; generation: number; revision: number }| { type: "autoplay-blocked"; generation: number; revision: number }| { type: "autoplay-cleared"; generation: number }| { type: "playback-failed"; generation: number; revision: number }@@ -210,8 +211,7 @@ export function reduceViewerPresentation(kind: action.kind,},routeStatus:- state.routeStatus?.revision === action.revision &&- state.routeStatus.state === "waiting"+ state.routeStatus?.revision === action.revision? state.routeStatus: null,media: preserveMedia@@ -288,7 +288,11 @@ export function reduceViewerPresentation(case "media-bound": {if ((state.revision !== null && action.revision < state.revision) ||- (state.media && action.generation <= state.media.generation)+ (state.media && action.generation <= state.media.generation) ||+ (state.routeStatus?.revision === action.revision &&+ state.routeStatus.state === "failed") ||+ (state.revision === action.revision &&+ state.failure === "ROUTE_EXHAUSTED")) {return state;}@@ -315,7 +319,9 @@ export function reduceViewerPresentation(!state.media ||state.media.generation !== action.generation ||state.media.revision !== action.revision ||- state.revision !== action.revision+ state.revision !== action.revision ||+ state.routeStatus?.state === "failed" ||+ state.failure === "ROUTE_EXHAUSTED") {return state;}@@ -326,10 +332,22 @@ export function reduceViewerPresentation(retainedFrame: false,routeStatus: null,failure:- state.failure === "PLAYBACK_FAILED" ||- state.failure === "ROUTE_EXHAUSTED"- ? null- : state.failure,+ state.failure === "PLAYBACK_FAILED" ? null : state.failure,+ };+ case "frame-proof-reset":+ if (+ !state.media ||+ state.media.generation !== action.generation ||+ state.media.revision !== action.revision ||+ state.revision !== action.revision ||+ !state.media.framePresented+ ) {+ return state;+ }+ return {+ ...state,+ media: { ...state.media, framePresented: false },+ retainedFrame: true,};case "autoplay-blocked":if (@@ -540,6 +558,15 @@ export function deriveViewerPresentation(};}+ if (state.routeStatus?.state === "failed") {+ return presentation(+ "route-failed",+ "没有可用的媒体线路",+ frameOverlay,+ state,+ );+ }+switch (state.failure) {case "ROUTE_EXHAUSTED":return presentation(@@ -607,6 +634,18 @@ export function deriveViewerPresentation(state,);}+ if (+ state.signal === "reconnecting" ||+ state.connection === "reconnecting" ||+ state.connection === "failed"+ ) {+ return presentation(+ "recovering",+ "正在恢复连接",+ frameOverlay,+ state,+ );+ }if (state.media && state.media.revision === state.revision) {return presentation("receiving",@@ -623,18 +662,6 @@ export function deriveViewerPresentation(state,);}- if (- state.signal === "reconnecting" ||- state.connection === "reconnecting" ||- state.connection === "failed"- ) {- return presentation(- "recovering",- "正在恢复连接",- frameOverlay,- state,- );- }if (state.host === "stopped" || state.host === "unknown") {return presentation("waiting-host",diff --git a/src/client/media/viewer-quality-evidence.ts b/src/client/media/viewer-quality-evidence.tsindex 5eb963c0..2ac4a873 100644--- a/src/client/media/viewer-quality-evidence.ts+++ b/src/client/media/viewer-quality-evidence.ts@@ -96,10 +96,6 @@ export function qualityEvidenceWindowFromMetrics(width !== null && height !== null? { width, height }: { width: null, height: null };- const freezeDuration = boundedNumber(- metrics.intervalFreezeDurationMs,- windowMs,- );const candidate: ViewerQualityEvidenceMetrics = {...dimensions,framesPerSecond: boundedNumber(metrics.framesPerSecond, 240),@@ -120,8 +116,22 @@ export function qualityEvidenceWindowFromMetrics(10_000,),decodeMsPerFrame: boundedNumber(metrics.intervalDecodeMs, 60_000),- freezeCountDelta: boundedInteger(metrics.intervalFreezeCount, 10_000),- freezeDurationMsDelta: freezeDuration,+ freezeCountDelta: boundedInteger(+ metrics.intervalFreezeCount,+ Number.MAX_SAFE_INTEGER,+ ),+ freezeDurationMsDelta: boundedNumber(+ metrics.intervalFreezeDurationMs,+ Number.MAX_SAFE_INTEGER,+ ),+ pauseCountDelta: boundedInteger(+ metrics.intervalPauseCount,+ Number.MAX_SAFE_INTEGER,+ ),+ pauseDurationMsDelta: boundedNumber(+ metrics.intervalPauseDurationMs,+ Number.MAX_SAFE_INTEGER,+ ),codec: boundedString(metrics.codec,64,@@ -175,7 +185,9 @@ export function qualityEvidenceWindowFromMetrics(export class ViewerQualityEvidenceReporter {private connectionId: string | null = null;- private routeRevision: number | null = null;+ private presentationEpoch = 0;+ private presentationEligible = false;+ private baselinePending = true;private sequence = 0;private lastSentAtMs: number | null = null;private lastSampleTimestampMs: number | null = null;@@ -185,11 +197,16 @@ export class ViewerQualityEvidenceReporter {private readonly now: () => number = Date.now,) {}- offer(snapshot: PeerSnapshot, routeRevision: number): boolean {+ offer(+ snapshot: PeerSnapshot,+ routeRevision: number,+ presentationEligible: boolean,+ ): boolean {return this.offerMetrics(snapshot.connectionId,snapshot.metrics,routeRevision,+ presentationEligible,);}@@ -197,6 +214,7 @@ export class ViewerQualityEvidenceReporter {connectionId: string,metrics: ConnectionMetrics,routeRevision: number,+ presentationEligible: boolean,): boolean {if (!Number.isSafeInteger(routeRevision) ||@@ -205,8 +223,14 @@ export class ViewerQualityEvidenceReporter {) {return false;}- const window = qualityEvidenceWindowFromMetrics(metrics);const sampleTimestampMs = metrics.sampleTimestampMs;+ if (this.connectionId !== connectionId) {+ this.connectionId = connectionId;+ this.sequence = 0;+ this.lastSampleTimestampMs = null;+ this.baselinePending = true;+ }+ const window = qualityEvidenceWindowFromMetrics(metrics);if (!window ||sampleTimestampMs === null ||@@ -215,27 +239,36 @@ export class ViewerQualityEvidenceReporter {) {return false;}- if (this.connectionId !== connectionId) {- this.connectionId = connectionId;- this.routeRevision = routeRevision;- this.sequence = 0;- this.lastSentAtMs = null;- this.lastSampleTimestampMs = null;- } else if (this.routeRevision !== routeRevision) {- this.routeRevision = routeRevision;- this.lastSentAtMs = null;- this.lastSampleTimestampMs = null;- }- if (this.sequence > Number.MAX_SAFE_INTEGER) {- return false;- }-if (this.lastSampleTimestampMs !== null &&sampleTimestampMs <= this.lastSampleTimestampMs) {return false;}+ this.lastSampleTimestampMs = sampleTimestampMs;+ if (!presentationEligible) {+ if (this.presentationEligible) {+ this.invalidatePresentation();+ }+ return false;+ }+ if (!this.presentationEligible) {+ this.presentationEligible = true;+ this.baselinePending = true;+ }+ const decodedProgress =+ metrics.intervalFramesDecoded !== null &&+ metrics.intervalFramesDecoded > 0;+ if (!decodedProgress) {+ return false;+ }+ if (this.baselinePending) {+ this.baselinePending = false;+ return false;+ }+ if (this.sequence > Number.MAX_SAFE_INTEGER) {+ return false;+ }const now = this.now();if (!Number.isFinite(now) ||@@ -250,6 +283,7 @@ export class ViewerQualityEvidenceReporter {guard: {connectionId,routeRevision,+ presentationEpoch: this.presentationEpoch,},sequence: this.sequence,...window,@@ -266,13 +300,26 @@ export class ViewerQualityEvidenceReporter {this.sequence += 1;this.lastSentAtMs = now;- this.lastSampleTimestampMs = sampleTimestampMs;return true;}+ invalidatePresentation(): void {+ if (!this.presentationEligible) {+ return;+ }+ if (this.presentationEpoch < Number.MAX_SAFE_INTEGER) {+ this.presentationEpoch += 1;+ }+ this.presentationEligible = false;+ this.baselinePending = true;+ this.sequence = 0;+ }+reset(): void {this.connectionId = null;- this.routeRevision = null;+ this.presentationEpoch = 0;+ this.presentationEligible = false;+ this.baselinePending = true;this.sequence = 0;this.lastSentAtMs = null;this.lastSampleTimestampMs = null;@@ -286,7 +333,8 @@ function sameViewerQualityEvidenceIdentity(return (previous.viewerPeerId === next.viewerPeerId &&qualityEvidenceUpstreamMatches(previous, next.upstream) &&- previous.guard.connectionId === next.guard.connectionId+ previous.guard.connectionId === next.guard.connectionId &&+ previous.guard.presentationEpoch === next.guard.presentationEpoch);}diff --git a/src/client/pages/ViewerPage.tsx b/src/client/pages/ViewerPage.tsxindex 5e538448..0b9fd051 100644--- a/src/client/pages/ViewerPage.tsx+++ b/src/client/pages/ViewerPage.tsx@@ -63,6 +63,7 @@ import {deriveViewerPresentation,reduceViewerPresentation,viewerFailureFromServerCode,+ type ViewerPresentationAction,type ViewerRouteKind,type ViewerStage,} from "../media/viewer-presentation";@@ -155,7 +156,7 @@ function StageOverlayIcon({ stage }: { stage: ViewerStage }) {}export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {- const [presentationState, dispatchPresentation] = useReducer(+ const [presentationState, dispatchPresentationState] = useReducer(reduceViewerPresentation,INITIAL_VIEWER_PRESENTATION_STATE,);@@ -234,6 +235,18 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {const peerRef = useRef<ViewerPeer | null>(null);const viewerSfuRouteRef = useRef<ViewerSfuRoute | null>(null);const signalRef = useRef<SignalingClient | null>(null);+ const presentationStateRef = useRef(presentationState);+ presentationStateRef.current = presentationState;+ function dispatchPresentation(action: ViewerPresentationAction): void {+ presentationStateRef.current = reduceViewerPresentation(+ presentationStateRef.current,+ action,+ );+ dispatchPresentationState(action);+ }+ const qualityEvidenceReporterRef =+ useRef<ViewerQualityEvidenceReporter | null>(null);+ const qualityFrameProofGenerationRef = useRef<number | null>(null);const displayNameRef = useRef(displayName);const remoteMediaRef = useRef<RemoteMediaBinding | null>(null);const mediaGenerationRef = useRef(0);@@ -279,6 +292,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {videoTrackKey,generation: ++mediaGenerationRef.current,};+ invalidateQualityPresentation();remoteMediaRef.current = next;setRemoteMedia(next);dispatchPresentation({@@ -289,22 +303,62 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {}function clearRemoteMedia(): void {+ invalidateQualityPresentation();remoteMediaRef.current = null;setRemoteMedia(null);dispatchPresentation({ type: "media-cleared" });}+ function resetCurrentFrameProof(): void {+ const binding = remoteMediaRef.current;+ if (!binding) {+ return;+ }+ dispatchPresentation({+ type: "frame-proof-reset",+ generation: binding.generation,+ revision: binding.revision,+ });+ }++ function invalidateQualityPresentation(): void {+ qualityEvidenceReporterRef.current?.invalidatePresentation();+ qualityFrameProofGenerationRef.current = null;+ }++ function invalidatePresentedMedia(): void {+ invalidateQualityPresentation();+ resetCurrentFrameProof();+ }++ function mediaBindingIsCurrent(binding: RemoteMediaBinding): boolean {+ const current = remoteMediaRef.current;+ return (+ current?.generation === binding.generation &&+ current.revision === binding.revision &&+ current.stream === binding.stream+ );+ }+function attemptPlayback(video: HTMLVideoElement,binding: RemoteMediaBinding,): void {void video.play().then(- () =>+ () => {+ if (!mediaBindingIsCurrent(binding)) {+ return;+ }dispatchPresentation({type: "autoplay-cleared",generation: binding.generation,- }),+ });+ },(error: unknown) => {+ if (!mediaBindingIsCurrent(binding)) {+ return;+ }+ invalidatePresentedMedia();if (isAutoplayPolicyRejection(error)) {dispatchPresentation({type: "autoplay-blocked",@@ -384,16 +438,19 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {let relayChildEvidenceCurrent: ViewerQualityEvidencePresentation | null =null;let relayChildEvidenceTimer: number | null = null;+ let sfuTransportConnected = false;let pageSuspended = document.visibilityState !== "visible";const syncDecodedFrameStallPause = (): void => {decodedFrameStall.setPaused(currentHostPaused || pageSuspended);};const suspendForPageLifecycle = (): void => {+ invalidatePresentedMedia();pageSuspended = true;syncDecodedFrameStallPause();};const recoverFromPageLifecycle = (): void => {+ invalidatePresentedMedia();pageSuspended = document.visibilityState !== "visible";syncDecodedFrameStallPause();if (pageSuspended) return;@@ -485,6 +542,50 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {const qualityEvidenceReporter = new ViewerQualityEvidenceReporter((message) => active && signal.send(message),);+ qualityEvidenceReporterRef.current = qualityEvidenceReporter;+ function qualityPresentationEligible(+ connectionConnected: boolean,+ ): boolean {+ const state = presentationStateRef.current;+ const binding = remoteMediaRef.current;+ const video = videoRef.current;+ return Boolean(+ connectionConnected &&+ !pageSuspended &&+ document.visibilityState === "visible" &&+ !currentHostPaused &&+ currentRouteAssignment !== null &&+ currentRouteAssignment.upstream.kind !== "none" &&+ currentRouteConnectionId !== null &&+ binding &&+ binding.revision === currentRouteRevision &&+ qualityFrameProofGenerationRef.current === binding.generation &&+ state.routeStatus?.state !== "failed" &&+ state.failure !== "ROUTE_EXHAUSTED" &&+ video &&+ !video.paused &&+ !video.ended,+ );+ }+ function offerPeerQualityEvidence(+ snapshot: PeerSnapshot,+ peer: ViewerPeer,+ ): void {+ const connectionHealthy =+ snapshot.connectionState === "connected" && !peer.isRecovering();+ const qualityEligible =+ qualityPresentationEligible(connectionHealthy);+ if (!connectionHealthy) {+ invalidatePresentedMedia();+ } else if (!qualityEligible) {+ invalidateQualityPresentation();+ }+ qualityEvidenceReporter.offer(+ snapshot,+ currentRouteRevision,+ qualityEligible,+ );+ }function activateRouteIdentity(revision: number,assignment: ParticipantRouteAssignment,@@ -799,6 +900,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {return;}currentAssignment = { parentPeerId: null, childPeerIds: [] };+ sfuTransportConnected = false;setSfuUpstream(null);clearPeerState();viewerRelay?.setChildren([]);@@ -838,6 +940,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {currentRouteConnectionId,metrics,revision,+ qualityPresentationEligible(sfuTransportConnected),);}}@@ -848,6 +951,13 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {},onSfuState: (state, revision) => {if (active && viewerSfuRoute === route) {+ const connected = state === "connected";+ if (sfuTransportConnected !== connected) {+ sfuTransportConnected = connected;+ if (!connected) {+ invalidatePresentedMedia();+ }+ }setSfuUpstream((current) =>current ? { ...current, connectionState: state } : null,);@@ -862,6 +972,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {if (!active || viewerSfuRoute !== route || available) {return;}+ invalidatePresentedMedia();setSfuUpstream((current) =>current ? { ...current, connectionState: "reconnecting" } : current,);@@ -889,6 +1000,9 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {const relay = ensureViewerRelay();relay?.setStream(nextStream);bindRemoteStream(nextStream, revision);+ if (initialVideoStream) {+ sfuTransportConnected = true;+ }setSfuUpstream((current) =>current ?? { connectionState: "connected", metrics: null },@@ -913,6 +1027,8 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {const route = viewerSfuRoute;discardPendingPeer();viewerSfuRoute = null;+ sfuTransportConnected = false;+ invalidatePresentedMedia();if (viewerSfuRouteRef.current === route) {viewerSfuRouteRef.current = null;}@@ -1018,7 +1134,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {snapshot.metrics.intervalFramesDecoded,snapshot.connectionId,);- qualityEvidenceReporter.offer(snapshot, currentRouteRevision);+ offerPeerQualityEvidence(snapshot, peer);setPeerSnapshot(snapshot);dispatchPresentation({type: "connection",@@ -1104,7 +1220,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {snapshot.metrics.intervalFramesDecoded,snapshot.connectionId,);- qualityEvidenceReporter.offer(snapshot, currentRouteRevision);+ offerPeerQualityEvidence(snapshot, peer);if (!currentHostOnline &&(snapshot.connectionState === "failed" ||@@ -1131,12 +1247,12 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {if (viewerSfuRoute) {return viewerSfuRoute.reportPeerFailure(parentPeerId, connectionId);}+ invalidateQualityPresentation();dispatchPresentation({type: "failure",failure: "ROUTE_EXHAUSTED",revision: currentRouteRevision,});- setFrameProofEpoch((current) => current + 1);return true;},},@@ -1209,6 +1325,9 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {currentHostOnline = message.hostOnline;setHostOnline(message.hostOnline);const sharingPaused = message.hostPaused ?? false;+ if (currentHostPaused !== sharingPaused && sharingPaused) {+ invalidatePresentedMedia();+ }currentHostPaused = sharingPaused;syncDecodedFrameStallPause();dispatchPresentation({@@ -1342,14 +1461,14 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {return;}if (message.type === "route-status") {+ if (message.state === "failed") {+ invalidateQualityPresentation();+ }dispatchPresentation({type: "route-status",revision: message.revision,state: message.state,});- if (message.state === "failed") {- setFrameProofEpoch((current) => current + 1);- }return;}if (message.type === "viewer-quality-evidence") {@@ -1452,6 +1571,9 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {}if (message.type === "host-status") {currentHostOnline = message.online;+ if (currentHostPaused !== message.paused && message.paused) {+ invalidatePresentedMedia();+ }currentHostPaused = message.paused;syncDecodedFrameStallPause();setHostOnline(message.online);@@ -1471,6 +1593,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {return;}if (message.type === "sharing-stopped") {+ invalidatePresentedMedia();currentRouteAssignment = null;currentRouteConnectionId = null;pendingRouteConnection = null;@@ -1586,6 +1709,9 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {window.removeEventListener("pageshow", recoverFromPageLifecycle);currentPeerId = null;qualityEvidenceReporter.reset();+ if (qualityEvidenceReporterRef.current === qualityEvidenceReporter) {+ qualityEvidenceReporterRef.current = null;+ }clearRelayChildEvidence();sfuStandbyPrewarmer?.dispose();signal.stop();@@ -1656,13 +1782,18 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {if (!video || !remoteMedia) {return;}- return observeCompositedVideoFrame(video, remoteMedia.stream, () =>+ const binding = remoteMedia;+ return observeCompositedVideoFrame(video, binding.stream, () => {+ if (!mediaBindingIsCurrent(binding)) {+ return;+ }+ qualityFrameProofGenerationRef.current = binding.generation;dispatchPresentation({type: "frame-presented",- generation: remoteMedia.generation,- revision: remoteMedia.revision,- }),- );+ generation: binding.generation,+ revision: binding.revision,+ });+ });}, [frameProofEpoch, presentationState.connection, remoteMedia]);function retryConnection(): void {@@ -1921,10 +2052,14 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {autoPlaycontrols={presentation.overlay === "none" ||- presentation.stage === "needs-play"+ presentation.stage === "needs-play" ||+ (presentation.stage === "receiving" &&+ presentation.hasRetainedFrame)}playsInlineonPlay={() => {+ invalidateQualityPresentation();+ setFrameProofEpoch((current) => current + 1);const binding = remoteMediaRef.current;if (binding) {dispatchPresentation({@@ -1933,6 +2068,8 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {});}}}+ onPause={invalidateQualityPresentation}+ onEnded={invalidateQualityPresentation}/>{presentation.overlay === "blocking" && (<div className="stage-placeholder" role="status">diff --git a/src/client/types.ts b/src/client/types.tsindex 920aec43..e5e521cc 100644--- a/src/client/types.ts+++ b/src/client/types.ts@@ -45,6 +45,8 @@ export interface ConnectionMetrics {intervalFramesDropped: number | null;intervalFreezeCount: number | null;intervalFreezeDurationMs: number | null;+ intervalPauseCount: number | null;+ intervalPauseDurationMs: number | null;intervalRetransmittedPackets: number | null;intervalRetransmittedBytes: number | null;codec: string | null;@@ -125,6 +127,8 @@ export const EMPTY_METRICS: ConnectionMetrics = {intervalFramesDropped: null,intervalFreezeCount: null,intervalFreezeDurationMs: null,+ intervalPauseCount: null,+ intervalPauseDurationMs: null,intervalRetransmittedPackets: null,intervalRetransmittedBytes: null,codec: null,diff --git a/src/client/webrtc/stats.ts b/src/client/webrtc/stats.tsindex c682880c..41342163 100644--- a/src/client/webrtc/stats.ts+++ b/src/client/webrtc/stats.ts@@ -26,6 +26,8 @@ export interface StatsAccumulator {previousFramesDropped: number | null;previousFreezeCount: number | null;previousTotalFreezesDuration: number | null;+ previousPauseCount: number | null;+ previousTotalPausesDuration: number | null;previousRetransmittedPackets: number | null;previousRetransmittedBytes: number | null;previousVideoJitterBufferDelay: number | null;@@ -92,6 +94,8 @@ export function createStatsAccumulator(): StatsAccumulator {previousFramesDropped: null,previousFreezeCount: null,previousTotalFreezesDuration: null,+ previousPauseCount: null,+ previousTotalPausesDuration: null,previousRetransmittedPackets: null,previousRetransmittedBytes: null,previousVideoJitterBufferDelay: null,@@ -493,6 +497,8 @@ export function collectConnectionMetricsFromReport(const framesDropped = numberValue(media, "framesDropped");const freezeCount = numberValue(media, "freezeCount");const totalFreezesDuration = numberValue(media, "totalFreezesDuration");+ const pauseCount = numberValue(media, "pauseCount");+ const totalPausesDuration = numberValue(media, "totalPausesDuration");const retransmittedPackets = numberValue(media,direction === "send"@@ -609,6 +615,22 @@ export function collectConnectionMetricsFromReport(previous.previousTotalFreezesDuration,sampleWindowMs !== null,);+ const intervalPauseCount =+ direction === "receive"+ ? intervalDelta(+ pauseCount,+ previous.previousPauseCount,+ sampleWindowMs !== null,+ )+ : null;+ const pauseDurationDelta =+ direction === "receive"+ ? intervalDelta(+ totalPausesDuration,+ previous.previousTotalPausesDuration,+ sampleWindowMs !== null,+ )+ : null;const intervalRetransmittedPackets = intervalDelta(retransmittedPackets,previous.previousRetransmittedPackets,@@ -643,6 +665,8 @@ export function collectConnectionMetricsFromReport(previous.previousFramesDropped = framesDropped;previous.previousFreezeCount = freezeCount;previous.previousTotalFreezesDuration = totalFreezesDuration;+ previous.previousPauseCount = pauseCount;+ previous.previousTotalPausesDuration = totalPausesDuration;previous.previousRetransmittedPackets = retransmittedPackets;previous.previousRetransmittedBytes = retransmittedBytes;previous.previousVideoJitterBufferDelay = videoJitterBufferDelay;@@ -840,6 +864,9 @@ export function collectConnectionMetricsFromReport(intervalFreezeCount,intervalFreezeDurationMs:freezeDurationDelta === null ? null : freezeDurationDelta * 1_000,+ intervalPauseCount,+ intervalPauseDurationMs:+ pauseDurationDelta === null ? null : pauseDurationDelta * 1_000,intervalRetransmittedPackets,intervalRetransmittedBytes,codec: codecEvidence.codec,diff --git a/src/server/hybrid-media-router.ts b/src/server/hybrid-media-router.tsindex 1b7259df..f8fa1e9e 100644--- a/src/server/hybrid-media-router.ts+++ b/src/server/hybrid-media-router.ts@@ -19,6 +19,8 @@ import {type CandidateReservation,type CandidateTuple,type OperationSnapshot,+ type RouteQualityEvidenceInput,+ type RouteQualityEvidenceResult,type RouteSnapshot,} from "./room-route-controller.js";import type { RoomStore } from "./room-store.js";@@ -263,6 +265,16 @@ export class HybridMediaRouter {);}+ observeQualityEvidence(+ input: RouteQualityEvidenceInput & { roomId: string },+ ): RouteQualityEvidenceResult {+ const { roomId, ...evidence } = input;+ return (+ this.rooms.get(roomId)?.controller?.observeQualityEvidence(evidence) ??+ "rejected"+ );+ }+isActivePeerParentOf(roomId: string,parentPeerId: string,diff --git a/src/server/room-route-controller.ts b/src/server/room-route-controller.tsindex 059f4585..537d44bd 100644--- a/src/server/room-route-controller.ts+++ b/src/server/room-route-controller.ts@@ -3,10 +3,12 @@ import { debuglog } from "node:util";import {MAX_MEDIA_ROUTE_REVISION,+ VIEWER_QUALITY_EVIDENCE_EXPIRY_MS,type RouteDemandReason,type RouteDiagnosticFinalRoute,type RouteDiagnosticRejectionBucket,type RouteDiagnosticSnapshot,+ type ViewerQualityEvidenceMetrics,} from "../shared/protocol.js";import { assertEndpointMediaCopyCapacity } from "../shared/media-copy-accounting.js";@@ -221,6 +223,46 @@ interface RouteTimingRecord {rejectionBucket: RouteDiagnosticRejectionBucket;}+interface RouteQualityObservation {+ childSessionId: string;+ upstreamKind: "peer" | "sfu";+ upstreamPeerId: string | null;+ connectionId: string;+ presentationEpoch: number;+ eligibleWindows: number;+ eligibleDurationMs: number;+ freezeWindows: number;+ freezeCount: number;+ freezeDurationMs: number;+ pauseCount: number;+ pauseDurationMs: number;+ lastAcceptedAtMs: number;+}++export interface RouteQualityEvidenceInput {+ childPeerId: string;+ childSessionId: string;+ routeRevision: number;+ connectionId: string;+ upstream: { kind: "peer"; peerId: string } | { kind: "sfu" };+ presentationEpoch: number;+ windowMs: number;+ metrics: Pick<+ ViewerQualityEvidenceMetrics,+ | "framesDecodedDelta"+ | "freezeCountDelta"+ | "freezeDurationMsDelta"+ | "pauseCountDelta"+ | "pauseDurationMsDelta"+ >;+ acceptedAtMs: number;+}++export type RouteQualityEvidenceResult =+ | "rejected"+ | "accepted"+ | "observed";+export class RoomRouteController<Resource = unknown> {private readonly participants = new Map<string, Participant>();private readonly upstreamByViewer = new Map<string, CommittedEdge<Resource>>();@@ -232,6 +274,11 @@ export class RoomRouteController<Resource = unknown> {private nextJoinOrder = 0;private paused = false;private readonly routeTimings = new Map<string, RouteTimingRecord>();+ private readonly qualityObservations = new Map<+ string,+ RouteQualityObservation+ >();+ private readonly qualityBaselinesPending = new Set<string>();private readonly directContinuations = new Map<string, DirectContinuation>();private sfuBootstrapIntent?: SfuBootstrapIntent;private sfuBootstrapExhaustedAtFactVersion?: number;@@ -311,6 +358,7 @@ export class RoomRouteController<Resource = unknown> {: "waiting": finalRoute,rejectionBucket: record?.rejectionBucket ?? "none",+ quality: this.diagnosticQuality(viewer.peerId, edge, nowMs),};},);@@ -348,6 +396,7 @@ export class RoomRouteController<Resource = unknown> {let changed = false;const previousSessionId = current.sessionId;if (previousSessionId !== input.sessionId) {+ this.clearQualityForParticipant(input.peerId);const revisionBefore = this.revision;if (this.operationUsesParticipantSession(input.peerId)) {released.push(...this.abortOperation(nowMs, "stale"));@@ -413,6 +462,7 @@ export class RoomRouteController<Resource = unknown> {const participant = this.participants.get(peerId);if (!participant || participant.sessionId !== sessionId) return false;participant.sessionId = null;+ this.clearQualityForParticipant(peerId);this.directContinuations.delete(peerId);this.clearSfuBootstrapForDemand(peerId);this.touchFacts();@@ -429,6 +479,7 @@ export class RoomRouteController<Resource = unknown> {if (participant.departureConfirmed && participant.sessionId === null &&participant.effectiveDownstreamCapacity === 0) return true;participant.sessionId = null;+ this.clearQualityForParticipant(peerId);participant.departureConfirmed = true;participant.effectiveDownstreamCapacity = 0;this.directContinuations.delete(peerId);@@ -521,6 +572,7 @@ export class RoomRouteController<Resource = unknown> {return false;}if (edge.usable) {+ this.clearQualityForParticipant(guard.childPeerId);edge.usable = false;this.directContinuations.delete(guard.childPeerId);child.blockedAtFactVersion = undefined;@@ -548,6 +600,7 @@ export class RoomRouteController<Resource = unknown> {publication.generation !== guard.generation ||publication.connectionId !== guard.connectionId) return false;if (publication.usable) {+ this.clearSfuQuality();publication.usable = false;this.directContinuations.clear();this.sfuBootstrapIntent = undefined;@@ -582,6 +635,7 @@ export class RoomRouteController<Resource = unknown> {return false;}if (input.newConnectionId === edge.connectionId) return true;+ this.clearQualityForParticipant(input.childPeerId);edge.connectionId = input.newConnectionId;const child = this.participants.get(input.childPeerId);if (child) {@@ -603,6 +657,7 @@ export class RoomRouteController<Resource = unknown> {}edge.physicalActive = false;edge.usable = false;+ this.clearQualityForParticipant(guard.childPeerId);child.blockedAtFactVersion = undefined;this.revision = this.allocateRevision();if (this.operation) this.operation.baseRevision = this.revision;@@ -624,6 +679,7 @@ export class RoomRouteController<Resource = unknown> {publication.connectionId !== guard.connectionId) return [];publication.physicalActive = false;publication.usable = false;+ this.clearSfuQuality();this.revision = this.allocateRevision();if (this.operation) this.operation.baseRevision = this.revision;this.touchFacts();@@ -633,10 +689,126 @@ export class RoomRouteController<Resource = unknown> {setPaused(paused: boolean, nowMs?: number): readonly Resource[] {if (this.paused === paused) return [];this.paused = paused;+ if (paused) {+ this.qualityObservations.clear();+ this.qualityBaselinesPending.clear();+ }this.touchFacts();return paused ? this.abortOperation(nowMs, "aborted") : [];}+ observeQualityEvidence(+ input: RouteQualityEvidenceInput,+ ): RouteQualityEvidenceResult {+ if (+ this.paused ||+ input.routeRevision !== this.revision ||+ !Number.isSafeInteger(input.presentationEpoch) ||+ input.presentationEpoch < 0 ||+ !Number.isSafeInteger(input.windowMs) ||+ input.windowMs <= 0 ||+ !Number.isSafeInteger(input.acceptedAtMs) ||+ input.acceptedAtMs < 0+ ) {+ return "rejected";+ }+ const child = this.participants.get(input.childPeerId);+ const edge = this.upstreamByViewer.get(input.childPeerId);+ if (+ !child ||+ child.sessionId !== input.childSessionId ||+ !edge ||+ !edge.usable ||+ !edge.physicalActive ||+ edge.childSessionId !== input.childSessionId ||+ edge.connectionId !== input.connectionId ||+ !this.qualityUpstreamMatches(edge, input.upstream) ||+ !this.sourceUsableForQuality(edge)+ ) {+ return "rejected";+ }++ const upstreamPeerId =+ input.upstream.kind === "peer" ? input.upstream.peerId : null;+ let observation = this.qualityObservations.get(input.childPeerId);+ const sameEdgeObservation =+ observation?.childSessionId === input.childSessionId &&+ observation.upstreamKind === input.upstream.kind &&+ observation.upstreamPeerId === upstreamPeerId &&+ observation.connectionId === input.connectionId;+ if (+ sameEdgeObservation &&+ observation &&+ input.presentationEpoch < observation.presentationEpoch+ ) {+ return "rejected";+ }+ if (+ !sameEdgeObservation ||+ !observation ||+ observation.presentationEpoch !== input.presentationEpoch+ ) {+ observation = {+ childSessionId: input.childSessionId,+ upstreamKind: input.upstream.kind,+ upstreamPeerId,+ connectionId: input.connectionId,+ presentationEpoch: input.presentationEpoch,+ eligibleWindows: 0,+ eligibleDurationMs: 0,+ freezeWindows: 0,+ freezeCount: 0,+ freezeDurationMs: 0,+ pauseCount: 0,+ pauseDurationMs: 0,+ lastAcceptedAtMs: input.acceptedAtMs,+ };+ this.qualityObservations.set(input.childPeerId, observation);+ }++ const metrics = input.metrics;+ if (+ metrics.framesDecodedDelta === null ||+ metrics.framesDecodedDelta <= 0 ||+ metrics.freezeCountDelta === null ||+ metrics.freezeDurationMsDelta === null ||+ metrics.pauseCountDelta === null ||+ metrics.pauseDurationMsDelta === null+ ) {+ return "accepted";+ }+ observation.lastAcceptedAtMs = input.acceptedAtMs;+ if (this.qualityBaselinesPending.delete(input.childPeerId)) {+ return "accepted";+ }++ observation.eligibleWindows = safeAdd(observation.eligibleWindows, 1);+ observation.eligibleDurationMs = safeAdd(+ observation.eligibleDurationMs,+ input.windowMs,+ );+ if (metrics.freezeCountDelta > 0) {+ observation.freezeWindows = safeAdd(observation.freezeWindows, 1);+ }+ observation.freezeCount = safeAdd(+ observation.freezeCount,+ metrics.freezeCountDelta,+ );+ observation.freezeDurationMs = safeAdd(+ observation.freezeDurationMs,+ metrics.freezeDurationMsDelta,+ );+ observation.pauseCount = safeAdd(+ observation.pauseCount,+ metrics.pauseCountDelta,+ );+ observation.pauseDurationMs = safeAdd(+ observation.pauseDurationMs,+ metrics.pauseDurationMsDelta,+ );+ return "observed";+ }+reconcile(nowMs: number): ReconcileResult<Resource> {const released: Resource[] = [];const validation = this.validateOrAdvance(nowMs);@@ -1164,6 +1336,8 @@ export class RoomRouteController<Resource = unknown> {for (const resource of this.committedResources()) resources.add(resource);this.operation = undefined;this.upstreamByViewer.clear();+ this.qualityObservations.clear();+ this.qualityBaselinesPending.clear();this.hostPublication = null;this.participants.clear();this.routeTimings.clear();@@ -1373,6 +1547,7 @@ export class RoomRouteController<Resource = unknown> {private commitAttempt(operation: ChildOperation<Resource>, attempt: Attempt<Resource>): Resource[] {const beforeResources = new Set(this.committedResources());const old = this.upstreamByViewer.get(operation.childPeerId);+ this.clearQualityForParticipant(operation.childPeerId);if (attempt.tuple.kind === "sfu" && attempt.tuple.publication === "replace") {this.removePublicationGeneration(this.hostPublication!.generation);@@ -2017,6 +2192,7 @@ export class RoomRouteController<Resource = unknown> {const edge = this.upstreamByViewer.get(participant.peerId);if (edge && edge.transport !== "direct" && edge.physicalActive) released.push(edge.resource);this.upstreamByViewer.delete(participant.peerId);+ this.clearQualityForParticipant(participant.peerId);this.participants.delete(participant.peerId);this.routeTimings.delete(participant.peerId);this.directContinuations.delete(participant.peerId);@@ -2027,6 +2203,7 @@ export class RoomRouteController<Resource = unknown> {}if (removed.length > 0) {if (!this.hasSfuSubscribers() && this.hostPublication) {+ this.clearSfuQuality();if (this.hostPublication.physicalActive) released.push(this.hostPublication.resource);this.hostPublication = null;}@@ -2408,6 +2585,99 @@ export class RoomRouteController<Resource = unknown> {: { kind: "viewer", ordinal };}+ private diagnosticQuality(+ childPeerId: string,+ edge: CommittedEdge<Resource> | undefined,+ nowMs: number,+ ): RouteDiagnosticSnapshot["children"][number]["quality"] {+ const observation = this.qualityObservations.get(childPeerId);+ const participant = this.participants.get(childPeerId);+ if (+ this.paused ||+ !observation ||+ observation.eligibleWindows === 0 ||+ nowMs >=+ observation.lastAcceptedAtMs + VIEWER_QUALITY_EVIDENCE_EXPIRY_MS ||+ !participant?.sessionId ||+ participant.sessionId !== observation.childSessionId ||+ !edge ||+ !edge.usable ||+ !edge.physicalActive ||+ edge.connectionId !== observation.connectionId ||+ !this.qualityObservationMatchesEdge(observation, edge) ||+ !this.sourceUsableForQuality(edge)+ ) {+ return null;+ }+ return {+ eligibleWindows: observation.eligibleWindows,+ eligibleDurationMs: observation.eligibleDurationMs,+ freezeWindows: observation.freezeWindows,+ freezeCount: observation.freezeCount,+ freezeDurationMs: observation.freezeDurationMs,+ pauseCount: observation.pauseCount,+ pauseDurationMs: observation.pauseDurationMs,+ };+ }++ private qualityUpstreamMatches(+ edge: CommittedEdge<Resource>,+ upstream: RouteQualityEvidenceInput["upstream"],+ ): boolean {+ return edge.kind === "peer"+ ? upstream.kind === "peer" && upstream.peerId === edge.parentPeerId+ : upstream.kind === "sfu";+ }++ private qualityObservationMatchesEdge(+ observation: RouteQualityObservation,+ edge: CommittedEdge<Resource>,+ ): boolean {+ return edge.kind === "peer"+ ? observation.upstreamKind === "peer" &&+ observation.upstreamPeerId === edge.parentPeerId+ : observation.upstreamKind === "sfu" &&+ observation.upstreamPeerId === null;+ }++ private sourceUsableForQuality(edge: CommittedEdge<Resource>): boolean {+ if (edge.kind === "peer") {+ return (+ edge.parentSessionId ===+ this.participants.get(edge.parentPeerId)?.sessionId &&+ this.sourceUsable(edge.parentPeerId)+ );+ }+ return Boolean(+ this.hostPublication?.usable &&+ this.hostPublication.physicalActive &&+ this.hostPublication.generation === edge.publicationGeneration,+ );+ }++ private clearQualityForParticipant(peerId: string): void {+ const affected =+ peerId === this.options.hostPeerId+ ? new Set(this.upstreamByViewer.keys())+ : this.descendantsOf(peerId).add(peerId);+ affected.forEach((childPeerId) => {+ this.qualityObservations.delete(childPeerId);+ if (this.upstreamByViewer.has(childPeerId)) {+ this.qualityBaselinesPending.add(childPeerId);+ } else {+ this.qualityBaselinesPending.delete(childPeerId);+ }+ });+ }++ private clearSfuQuality(): void {+ for (const [childPeerId, edge] of this.upstreamByViewer) {+ if (edge.kind === "sfu") {+ this.clearQualityForParticipant(childPeerId);+ }+ }+ }+private recordDemand(childPeerId: string,nowMs: number,@@ -2550,6 +2820,7 @@ export class RoomRouteController<Resource = unknown> {for (const [viewerPeerId, edge] of this.upstreamByViewer) {if (edge.kind !== "sfu" || edge.publicationGeneration !== generation) continue;if (edge.physicalActive) released.push(edge.resource);+ this.clearQualityForParticipant(viewerPeerId);this.upstreamByViewer.delete(viewerPeerId);}if (this.hostPublication?.generation === generation) {@@ -2658,6 +2929,16 @@ function elapsedMs(startedAtMs: number, endedAtMs: number): number | null {return Number.isSafeInteger(elapsed) && elapsed >= 0 ? elapsed : null;}+function safeAdd(total: number, delta: number): number {+ const rounded = Math.round(delta);+ if (!Number.isSafeInteger(rounded) || rounded < 0) {+ return total;+ }+ return rounded > Number.MAX_SAFE_INTEGER - total+ ? Number.MAX_SAFE_INTEGER+ : total + rounded;+}+function tupleKey(tuple: CandidateTuple): string {return tuple.kind === "peer" ? `peer:${tuple.parentPeerId}` : `sfu:${tuple.publication}`;}diff --git a/src/server/signaling.ts b/src/server/signaling.tsindex db8d7d1d..b9506520 100644--- a/src/server/signaling.ts+++ b/src/server/signaling.ts@@ -70,13 +70,11 @@ interface SocketState {interface ViewerQualityEvidenceGate {viewerSessionId: string;- recipientSessionId: string;upstreamKind: "peer" | "sfu";upstreamPeerId: string | null;connectionId: string;- routeRevision: number;+ presentationEpoch: number;sequence: number;- acceptedAtMs: number;}interface ViewerMediaReadyState {@@ -119,6 +117,7 @@ export class SignalingServer {string,ViewerQualityEvidenceGate>();+ private readonly viewerQualityEvidenceAttemptAtMs = new Map<string, number>();private readonly viewerMediaReadyByRoom = new Map<string,Map<string, ViewerMediaReadyState>@@ -252,6 +251,7 @@ export class SignalingServer {routeCloseError = error;}this.viewerQualityEvidenceGates.clear();+ this.viewerQualityEvidenceAttemptAtMs.clear();this.viewerMediaReadyByRoom.clear();this.shareGenerationsByRoom.clear();this.pausedShareGenerationsByRoom.clear();@@ -608,9 +608,12 @@ export class SignalingServer {viewerPresence: message.viewerPresence === true,};if (participant.role === "viewer") {- this.viewerQualityEvidenceGates.delete(- viewerConnectionKey(participant.roomId, participant.peerId),+ const viewerKey = viewerConnectionKey(+ participant.roomId,+ participant.peerId,);+ this.viewerQualityEvidenceGates.delete(viewerKey);+ this.viewerQualityEvidenceAttemptAtMs.delete(viewerKey);}this.clearViewerGrace(participant.roomId, participant.peerId);const routeParticipant = {@@ -1139,9 +1142,19 @@ export class SignalingServer {return;}- const connectionId = this.connectionIdsByViewer.get(- viewerConnectionKey(source.roomId, source.peerId),- );+ const gateKey = viewerConnectionKey(source.roomId, source.peerId);+ const now = this.now();+ const previousAttemptAtMs =+ this.viewerQualityEvidenceAttemptAtMs.get(gateKey);+ if (+ previousAttemptAtMs !== undefined &&+ now - previousAttemptAtMs < VIEWER_QUALITY_EVIDENCE_INTERVAL_MS+ ) {+ return;+ }+ this.viewerQualityEvidenceAttemptAtMs.set(gateKey, now);++ const connectionId = this.connectionIdsByViewer.get(gateKey);if (!connectionId || message.guard.connectionId !== connectionId) {return;}@@ -1179,22 +1192,19 @@ export class SignalingServer {return;}- const gateKey = viewerConnectionKey(source.roomId, source.peerId);const previous = this.viewerQualityEvidenceGates.get(gateKey);- const sameGeneration =+ const sameEdge =previous?.viewerSessionId === viewerState.sessionId &&- previous.recipientSessionId === recipient.sessionId &&previous.upstreamKind === upstream.kind &&previous.upstreamPeerId ===(upstream.kind === "peer" ? upstream.peerId : null) &&- previous.connectionId === connectionId &&- previous.routeRevision === routeRevision;- const now = this.now();+ previous.connectionId === connectionId;if (- sameGeneration &&+ sameEdge &&previous &&- (message.sequence <= previous.sequence ||- now - previous.acceptedAtMs < VIEWER_QUALITY_EVIDENCE_INTERVAL_MS)+ (message.guard.presentationEpoch < previous.presentationEpoch ||+ (message.guard.presentationEpoch === previous.presentationEpoch &&+ message.sequence <= previous.sequence))) {return;}@@ -1209,29 +1219,42 @@ export class SignalingServer {guard: {connectionId,routeRevision,+ presentationEpoch: message.guard.presentationEpoch,},sequence: message.sequence,windowMs: message.windowMs,metrics: message.metrics,};const encoded = JSON.stringify(forwarded);- if (- Buffer.byteLength(encoded, "utf8") >- MAX_VIEWER_QUALITY_EVIDENCE_BYTES ||- !this.sendEncodedToSession(recipient.sessionId, encoded)- ) {+ if (Buffer.byteLength(encoded, "utf8") > MAX_VIEWER_QUALITY_EVIDENCE_BYTES) {+ return;+ }+ const qualityResult = this.isHybridMediaEnabled()+ ? (this.hybridMediaRouter?.observeQualityEvidence({+ roomId: source.roomId,+ childPeerId: source.peerId,+ childSessionId: viewerState.sessionId,+ routeRevision,+ connectionId,+ upstream,+ presentationEpoch: message.guard.presentationEpoch,+ windowMs: message.windowMs,+ metrics: message.metrics,+ acceptedAtMs: now,+ }) ?? "rejected")+ : "accepted";+ if (qualityResult === "rejected") {return;}this.viewerQualityEvidenceGates.set(gateKey, {viewerSessionId: viewerState.sessionId,- recipientSessionId: recipient.sessionId,upstreamKind: upstream.kind,upstreamPeerId: upstream.kind === "peer" ? upstream.peerId : null,connectionId,- routeRevision,+ presentationEpoch: message.guard.presentationEpoch,sequence: message.sequence,- acceptedAtMs: now,});+ this.sendEncodedToSession(recipient.sessionId, encoded);if (!host || host.sessionId === recipient.sessionId) {return;}@@ -1976,6 +1999,11 @@ export class SignalingServer {this.viewerQualityEvidenceGates.delete(key);}}+ for (const key of this.viewerQualityEvidenceAttemptAtMs.keys()) {+ if (key.startsWith(prefix)) {+ this.viewerQualityEvidenceAttemptAtMs.delete(key);+ }+ }}private setViewerConnectionId(@@ -1986,6 +2014,7 @@ export class SignalingServer {const key = viewerConnectionKey(roomId, viewerPeerId);if (this.connectionIdsByViewer.get(key) !== connectionId) {this.viewerQualityEvidenceGates.delete(key);+ this.viewerQualityEvidenceAttemptAtMs.delete(key);}this.connectionIdsByViewer.set(key, connectionId);}@@ -1997,6 +2026,7 @@ export class SignalingServer {const key = viewerConnectionKey(roomId, viewerPeerId);this.connectionIdsByViewer.delete(key);this.viewerQualityEvidenceGates.delete(key);+ this.viewerQualityEvidenceAttemptAtMs.delete(key);}}diff --git a/src/shared/protocol.ts b/src/shared/protocol.tsindex 57deb0ff..e52d02c2 100644--- a/src/shared/protocol.ts+++ b/src/shared/protocol.ts@@ -6,7 +6,7 @@ import { isCanonicalVideoCodecEvidence } from "./video-codec-evidence.js";export const MAX_VIEWERS_PER_ROOM_LIMIT = 20;export const MAX_PARTICIPANTS_PER_ROOM_LIMIT = MAX_VIEWERS_PER_ROOM_LIMIT + 1;export const MAX_SIGNAL_BYTES = 64 * 1024;-export const SIGNALING_PROTOCOL = "screener-v12";+export const SIGNALING_PROTOCOL = "screener-v13";export const SIGNAL_CLOSE_CODES = {serviceRestart: 1012,sessionReplaced: 4001,@@ -397,6 +397,22 @@ const routeDiagnosticParentSchema = z.discriminatedUnion("kind", [}).strict(),]);+const routeDiagnosticQualityValueSchema = z+ .number()+ .int()+ .min(0)+ .max(Number.MAX_SAFE_INTEGER);+const routeDiagnosticQualitySchema = z+ .object({+ eligibleWindows: routeDiagnosticQualityValueSchema,+ eligibleDurationMs: routeDiagnosticQualityValueSchema,+ freezeWindows: routeDiagnosticQualityValueSchema,+ freezeCount: routeDiagnosticQualityValueSchema,+ freezeDurationMs: routeDiagnosticQualityValueSchema,+ pauseCount: routeDiagnosticQualityValueSchema,+ pauseDurationMs: routeDiagnosticQualityValueSchema,+ })+ .strict();const routeDiagnosticChildSchema = z.object({ordinal: routeDiagnosticOrdinalSchema,@@ -418,6 +434,7 @@ const routeDiagnosticChildSchema = zfinalMs: routeDiagnosticDurationSchema,finalRoute: routeDiagnosticFinalRouteSchema,rejectionBucket: routeDiagnosticRejectionBucketSchema,+ quality: routeDiagnosticQualitySchema.nullable(),}).strict();const routeDiagnosticOperationSchema = z@@ -524,6 +541,20 @@ const nullableSignedEvidenceNumber = (absoluteMaximum: number) =>const nullableEvidenceInteger = (maximum: number) =>z.number().int().min(0).max(maximum).nullable();+const nullableSafeEvidenceNumber = z+ .number()+ .finite()+ .min(0)+ .max(Number.MAX_SAFE_INTEGER)+ .nullable();++const nullableSafeEvidenceInteger = z+ .number()+ .int()+ .min(0)+ .max(Number.MAX_SAFE_INTEGER)+ .nullable();+export const viewerQualityEvidenceMetricsSchema = z.object({width: z.number().int().min(1).max(16_384).nullable(),@@ -537,8 +568,10 @@ export const viewerQualityEvidenceMetricsSchema = zframesDecodedDelta: nullableEvidenceInteger(10_000),framesDroppedDelta: nullableEvidenceInteger(10_000),decodeMsPerFrame: nullableEvidenceNumber(60_000),- freezeCountDelta: nullableEvidenceInteger(10_000),- freezeDurationMsDelta: nullableEvidenceNumber(5_000),+ freezeCountDelta: nullableSafeEvidenceInteger,+ freezeDurationMsDelta: nullableSafeEvidenceNumber,+ pauseCountDelta: nullableSafeEvidenceInteger,+ pauseDurationMsDelta: nullableSafeEvidenceNumber,codec: z.string().max(64)@@ -587,6 +620,11 @@ const viewerQualityEvidenceGuardSchema = z.object({connectionId: opaqueIdSchema,routeRevision: mediaRouteRevisionSchema,+ presentationEpoch: z+ .number()+ .int()+ .min(0)+ .max(Number.MAX_SAFE_INTEGER),}).strict();@@ -596,26 +634,13 @@ const viewerQualityEvidenceWindowShape = {metrics: viewerQualityEvidenceMetricsSchema,};-function freezeFitsEvidenceWindow(value: {- windowMs: number;- metrics: ViewerQualityEvidenceMetrics;-}): boolean {- return (- value.metrics.freezeDurationMsDelta === null ||- value.metrics.freezeDurationMsDelta <= value.windowMs- );-}-export const viewerQualityEvidenceMessageSchema = z.object({type: z.literal("viewer-quality-evidence"),guard: viewerQualityEvidenceGuardSchema,...viewerQualityEvidenceWindowShape,})- .strict()- .refine(freezeFitsEvidenceWindow, {- message: "Viewer freeze duration exceeds its evidence window",- });+ .strict();const authenticateMessageSchema = z.discriminatedUnion("role", [z@@ -937,10 +962,7 @@ export const serverMessageSchema = z.union([guard: viewerQualityEvidenceGuardSchema,...viewerQualityEvidenceWindowShape,})- .strict()- .refine(freezeFitsEvidenceWindow, {- message: "Viewer freeze duration exceeds its evidence window",- }),+ .strict(),z.object({type: z.literal("host-status"),diff --git a/tests/client-state.test.ts b/tests/client-state.test.tsindex 7c637068..efcd2048 100644--- a/tests/client-state.test.ts+++ b/tests/client-state.test.ts@@ -1,6 +1,9 @@import { afterEach, describe, expect, it, vi } from "vitest";-import type { QualitySettings } from "../src/shared/protocol.ts";+import {+ SIGNALING_PROTOCOL,+ type QualitySettings,+} from "../src/shared/protocol.ts";import {ApiError,@@ -42,6 +45,7 @@ import {import { qualityEvidenceWindowFromMetrics } from "../src/client/media/viewer-quality-evidence.ts";import {collectConnectionMetrics,+ collectConnectionMetricsFromReport,createStatsAccumulator,} from "../src/client/webrtc/stats.ts";@@ -887,7 +891,7 @@ describe("client signaling recovery policy", () => {socket.dispatchEvent(new Event("open"));receive(socket, {type: "authenticated",- protocol: "screener-v12",+ protocol: "screener-v13",role: "host",peerId: "host_12345678",roomExpiresAt: null,@@ -923,7 +927,7 @@ describe("client signaling recovery policy", () => {});receive(sockets[1]!, {type: "authenticated",- protocol: "screener-v12",+ protocol: "screener-v13",role: "host",peerId: "host_12345678",roomExpiresAt: null,@@ -1035,7 +1039,7 @@ describe("client signaling recovery policy", () => {Object.defineProperty(event, "data", {value: JSON.stringify({type: "authenticated",- protocol: "screener-v12",+ protocol: SIGNALING_PROTOCOL,role: "host",peerId: "host_12345678",roomExpiresAt: null,@@ -1162,7 +1166,7 @@ describe("client signaling recovery policy", () => {socket.dispatchEvent(new Event("open"));receive(socket, {type: "authenticated",- protocol: "screener-v12",+ protocol: "screener-v13",role: "host",peerId: "host_12345678",roomExpiresAt: null,@@ -1288,7 +1292,7 @@ describe("client signaling recovery policy", () => {sockets[0]!.dispatchEvent(new Event("open"));receive({type: "authenticated",- protocol: "screener-v12",+ protocol: "screener-v13",role: "viewer",peerId: "viewer_12345678",roomExpiresAt: null,@@ -1415,7 +1419,7 @@ describe("client signaling recovery policy", () => {JSON.parse(String(sockets[0]!.send.mock.calls[0]![0])),).toMatchObject({type: "authenticate",- protocol: "screener-v12",+ protocol: "screener-v13",});const message = new Event("message");Object.defineProperty(message, "data", { value: payload });@@ -2120,6 +2124,8 @@ describe("WebRTC stats parsing", () => {framesDropped: number,freezeCount: number,totalFreezesDuration: number,+ pauseCount: number,+ totalPausesDuration: number,retransmittedPacketsReceived: number,retransmittedBytesReceived: number,) =>@@ -2137,18 +2143,20 @@ describe("WebRTC stats parsing", () => {framesDropped,freezeCount,totalFreezesDuration,+ pauseCount,+ totalPausesDuration,retransmittedPacketsReceived,retransmittedBytesReceived,},],]) as unknown as RTCStatsReport;const reports = [- inbound(1_000, 101, 2, 1, 0.25, 3, 300),- inbound(2_000, 101, 5, 2, 0.75, 7, 900),- inbound(3_000, 202, 20, 8, 4, 30, 4_000),- inbound(4_000, 202, 22, 9, 4.25, 33, 4_600),- inbound(5_000, 202, 1, 0, 0.25, 2, 200),- inbound(6_000, 202, 4, 1, 0.5, 6, 1_000),+ inbound(1_000, 101, 2, 1, 0.25, 0, 0, 3, 300),+ inbound(2_000, 101, 5, 2, 2.75, 1, 5.5, 7, 900),+ inbound(3_000, 202, 20, 8, 4, 3, 16, 30, 4_000),+ inbound(4_000, 202, 22, 9, 6.25, 4, 21.5, 33, 4_600),+ inbound(5_000, 202, 1, 0, 0.25, 0, 0.25, 2, 200),+ inbound(6_000, 202, 4, 1, 2.5, 1, 6.25, 6, 1_000),];const connection = {getStats: async () => reports.shift()!,@@ -2168,6 +2176,8 @@ describe("WebRTC stats parsing", () => {intervalFramesDropped: null,intervalFreezeCount: null,intervalFreezeDurationMs: null,+ intervalPauseCount: null,+ intervalPauseDurationMs: null,intervalRetransmittedPackets: null,intervalRetransmittedBytes: null,});@@ -2175,7 +2185,9 @@ describe("WebRTC stats parsing", () => {sampleWindowMs: 1_000,intervalFramesDropped: 3,intervalFreezeCount: 1,- intervalFreezeDurationMs: 500,+ intervalFreezeDurationMs: 2_500,+ intervalPauseCount: 1,+ intervalPauseDurationMs: 5_500,intervalRetransmittedPackets: 4,intervalRetransmittedBytes: 600,});@@ -2185,6 +2197,8 @@ describe("WebRTC stats parsing", () => {intervalFramesDropped: null,intervalFreezeCount: null,intervalFreezeDurationMs: null,+ intervalPauseCount: null,+ intervalPauseDurationMs: null,intervalRetransmittedPackets: null,intervalRetransmittedBytes: null,});@@ -2192,7 +2206,9 @@ describe("WebRTC stats parsing", () => {sampleWindowMs: 1_000,intervalFramesDropped: 2,intervalFreezeCount: 1,- intervalFreezeDurationMs: 250,+ intervalFreezeDurationMs: 2_250,+ intervalPauseCount: 1,+ intervalPauseDurationMs: 5_500,intervalRetransmittedPackets: 3,intervalRetransmittedBytes: 600,});@@ -2201,6 +2217,8 @@ describe("WebRTC stats parsing", () => {intervalFramesDropped: null,intervalFreezeCount: null,intervalFreezeDurationMs: null,+ intervalPauseCount: null,+ intervalPauseDurationMs: null,intervalRetransmittedPackets: null,intervalRetransmittedBytes: null,});@@ -2208,12 +2226,73 @@ describe("WebRTC stats parsing", () => {sampleWindowMs: 1_000,intervalFramesDropped: 3,intervalFreezeCount: 1,- intervalFreezeDurationMs: 250,+ intervalFreezeDurationMs: 2_250,+ intervalPauseCount: 1,+ intervalPauseDurationMs: 6_000,intervalRetransmittedPackets: 4,intervalRetransmittedBytes: 800,});});+ it("keeps unavailable pause counters unknown and receive-only", async () => {+ const report = (+ type: "inbound-rtp" | "outbound-rtp",+ timestamp: number,+ ) =>+ new Map<string, unknown>([+ [+ "video",+ {+ id: "video",+ type,+ timestamp,+ kind: "video",+ ssrc: 101,+ ...(type === "inbound-rtp"+ ? { bytesReceived: timestamp, framesDecoded: timestamp / 100 }+ : {+ bytesSent: timestamp,+ framesEncoded: timestamp / 100,+ pauseCount: timestamp / 1_000,+ totalPausesDuration: timestamp / 1_000,+ }),+ },+ ],+ ]) as unknown as RTCStatsReport;++ const receiveAccumulator = createStatsAccumulator();+ collectConnectionMetricsFromReport(+ report("inbound-rtp", 1_000),+ "receive",+ receiveAccumulator,+ );+ const receive = collectConnectionMetricsFromReport(+ report("inbound-rtp", 2_000),+ "receive",+ receiveAccumulator,+ );+ expect(receive).toMatchObject({+ intervalPauseCount: null,+ intervalPauseDurationMs: null,+ });++ const sendAccumulator = createStatsAccumulator();+ collectConnectionMetricsFromReport(+ report("outbound-rtp", 1_000),+ "send",+ sendAccumulator,+ );+ const send = collectConnectionMetricsFromReport(+ report("outbound-rtp", 2_000),+ "send",+ sendAccumulator,+ );+ expect(send).toMatchObject({+ intervalPauseCount: null,+ intervalPauseDurationMs: null,+ });+ });+it("derives a bounded inbound C window from adjacent RTP counters", async () => {const inbound = (timestamp: number,diff --git a/tests/protocol.test.ts b/tests/protocol.test.tsindex 1a9fa633..3efdfc33 100644--- a/tests/protocol.test.ts+++ b/tests/protocol.test.ts@@ -50,6 +50,7 @@ const qualityEvidence = {guard: {connectionId: "connection_12345678",routeRevision: 0,+ presentationEpoch: 0,},sequence: 0,windowMs: 2_000,@@ -67,6 +68,8 @@ const qualityEvidence = {decodeMsPerFrame: 2.4,freezeCountDelta: 0,freezeDurationMsDelta: 0,+ pauseCountDelta: 0,+ pauseDurationMsDelta: 0,codec: "video/H264",codecProfile: "profile-level-id=42e01f",codecParameters:@@ -93,7 +96,7 @@ describe("client signaling protocol", () => {"utf8",);- expect(SIGNALING_PROTOCOL).toBe("screener-v12");+ expect(SIGNALING_PROTOCOL).toBe("screener-v13");expect(nativeWire).toMatch(/signalingProtocol\s*=\s*"screener-v6"/);});@@ -754,6 +757,28 @@ describe("client signaling protocol", () => {it("accepts only strict, bounded viewer quality evidence", () => {expect(clientMessageSchema.safeParse(qualityEvidence).success).toBe(true);+ expect(+ clientMessageSchema.safeParse({+ ...qualityEvidence,+ metrics: {+ ...qualityEvidence.metrics,+ freezeDurationMsDelta: 12_000,+ pauseDurationMsDelta: 6_000,+ },+ }).success,+ ).toBe(true);+ expect(+ clientMessageSchema.safeParse({+ ...qualityEvidence,+ metrics: {+ ...qualityEvidence.metrics,+ freezeCountDelta: null,+ freezeDurationMsDelta: null,+ pauseCountDelta: null,+ pauseDurationMsDelta: null,+ },+ }).success,+ ).toBe(true);expect(Buffer.byteLength(JSON.stringify(qualityEvidence), "utf8"),).toBeLessThanOrEqual(MAX_VIEWER_QUALITY_EVIDENCE_BYTES);@@ -776,7 +801,32 @@ describe("client signaling protocol", () => {},{...qualityEvidence,- metrics: { ...qualityEvidence.metrics, freezeDurationMsDelta: 2_001 },+ metrics: { ...qualityEvidence.metrics, freezeCountDelta: -1 },+ },+ {+ ...qualityEvidence,+ metrics: {+ ...qualityEvidence.metrics,+ freezeCountDelta: Number.MAX_SAFE_INTEGER + 1,+ },+ },+ {+ ...qualityEvidence,+ metrics: {+ ...qualityEvidence.metrics,+ freezeDurationMsDelta: Number.MAX_SAFE_INTEGER + 1,+ },+ },+ {+ ...qualityEvidence,+ metrics: { ...qualityEvidence.metrics, pauseCountDelta: -1 },+ },+ {+ ...qualityEvidence,+ metrics: {+ ...qualityEvidence.metrics,+ pauseDurationMsDelta: Number.MAX_SAFE_INTEGER + 1,+ },},{...qualityEvidence,@@ -947,7 +997,7 @@ describe("server signaling protocol", () => {}});- it("accepts only the privacy-safe two-field route snapshot payload", () => {+ it("accepts only the privacy-safe route snapshot payload", () => {const message = {type: "route-diagnostic-snapshot",snapshot: {@@ -964,6 +1014,15 @@ describe("server signaling protocol", () => {finalMs: 80,finalRoute: "direct",rejectionBucket: "none",+ quality: {+ eligibleWindows: 3,+ eligibleDurationMs: 6_000,+ freezeWindows: 1,+ freezeCount: 1,+ freezeDurationMs: 250,+ pauseCount: 0,+ pauseDurationMs: 0,+ },},{ordinal: 2,@@ -977,6 +1036,7 @@ describe("server signaling protocol", () => {finalMs: null,finalRoute: "waiting",rejectionBucket: "sfu-admission",+ quality: null,},],operation: {@@ -1006,6 +1066,36 @@ describe("server signaling protocol", () => {],},},+ {+ ...message,+ snapshot: {+ ...message.snapshot,+ children: [+ {+ ...message.snapshot.children[0],+ quality: {+ ...message.snapshot.children[0].quality,+ presentationEpoch: 1,+ },+ },+ ],+ },+ },+ {+ ...message,+ snapshot: {+ ...message.snapshot,+ children: [+ {+ ...message.snapshot.children[0],+ quality: {+ ...message.snapshot.children[0].quality,+ freezeCount: -1,+ },+ },+ ],+ },+ },{...message,snapshot: {@@ -1474,6 +1564,16 @@ describe("server signaling protocol", () => {upstream: { kind: "peer", peerId: "host_12345678" },};expect(serverMessageSchema.safeParse(forwarded).success).toBe(true);+ expect(+ serverMessageSchema.safeParse({+ ...forwarded,+ metrics: {+ ...forwarded.metrics,+ freezeDurationMsDelta: 12_000,+ pauseDurationMsDelta: 6_000,+ },+ }).success,+ ).toBe(true);expect(serverMessageSchema.safeParse({...forwarded,diff --git a/tests/room-route-controller.test.ts b/tests/room-route-controller.test.tsindex 61e65816..432a4982 100644--- a/tests/room-route-controller.test.ts+++ b/tests/room-route-controller.test.ts@@ -1,5 +1,7 @@import { describe, expect, it } from "vitest";+import type { ViewerQualityEvidenceMetrics } from "../src/shared/protocol.ts";+import {RoomRouteController,type CandidateGuard,@@ -124,7 +126,194 @@ function peerEdge(};}+type RouteQualityMetrics = Pick<+ ViewerQualityEvidenceMetrics,+ | "framesDecodedDelta"+ | "freezeCountDelta"+ | "freezeDurationMsDelta"+ | "pauseCountDelta"+ | "pauseDurationMsDelta"+>;++function qualityMetrics(+ overrides: Partial<RouteQualityMetrics> = {},+): RouteQualityMetrics {+ return {+ framesDecodedDelta: 120,+ freezeCountDelta: 1,+ freezeDurationMsDelta: 250,+ pauseCountDelta: 0,+ pauseDurationMsDelta: 0,+ ...overrides,+ };+}+describe("RoomRouteController", () => {+ it("keeps only fresh exact-edge quality shadow aggregates", () => {+ const routes = controller(2);+ addViewer(routes, A, 1, 0);+ routes.reconcile(10);+ commitCurrent(routes, 20, "a_quality_connection");+ const active = routes.snapshot();++ expect(+ routes.observeQualityEvidence({+ childPeerId: A,+ childSessionId: `${A}_session`,+ routeRevision: active.revision,+ connectionId: "a_quality_connection",+ upstream: { kind: "peer", peerId: HOST },+ presentationEpoch: 1,+ windowMs: 2_000,+ metrics: qualityMetrics(),+ acceptedAtMs: 1_000,+ }),+ ).toBe("observed");+ expect(routes.snapshot()).toMatchObject({+ revision: active.revision,+ factVersion: active.factVersion,+ });+ addViewer(routes, B, 0, 1_100);+ routes.reconcile(1_200);+ commitCurrent(routes, 1_210, "b_quality_connection");+ expect(routes.routeDiagnosticSnapshot(1_300).children[0]?.quality).toEqual({+ eligibleWindows: 1,+ eligibleDurationMs: 2_000,+ freezeWindows: 1,+ freezeCount: 1,+ freezeDurationMs: 250,+ pauseCount: 0,+ pauseDurationMs: 0,+ });+ expect(routes.routeDiagnosticSnapshot(5_999).children[0]?.quality).not.toBeNull();+ expect(routes.routeDiagnosticSnapshot(6_000).children[0]?.quality).toBeNull();++ const nextRevision = routes.snapshot().revision;+ expect(+ routes.observeQualityEvidence({+ childPeerId: A,+ childSessionId: `${A}_session`,+ routeRevision: nextRevision,+ connectionId: "a_quality_connection",+ upstream: { kind: "peer", peerId: HOST },+ presentationEpoch: 2,+ windowMs: 2_000,+ metrics: qualityMetrics({ framesDecodedDelta: null }),+ acceptedAtMs: 7_000,+ }),+ ).toBe("accepted");+ expect(routes.routeDiagnosticSnapshot(7_100).children[0]?.quality).toBeNull();+ expect(+ routes.observeQualityEvidence({+ childPeerId: A,+ childSessionId: `${A}_session`,+ routeRevision: nextRevision,+ connectionId: "a_quality_connection",+ upstream: { kind: "peer", peerId: HOST },+ presentationEpoch: 2,+ windowMs: 2_000,+ metrics: qualityMetrics(),+ acceptedAtMs: 7_100,+ }),+ ).toBe("observed");+ expect(+ routes.observeQualityEvidence({+ childPeerId: A,+ childSessionId: `${A}_session`,+ routeRevision: nextRevision,+ connectionId: "a_quality_connection",+ upstream: { kind: "peer", peerId: HOST },+ presentationEpoch: 1,+ windowMs: 2_000,+ metrics: qualityMetrics(),+ acceptedAtMs: 7_200,+ }),+ ).toBe("rejected");++ routes.setPaused(true, 7_300);+ expect(routes.routeDiagnosticSnapshot(7_301).children[0]?.quality).toBeNull();+ });++ it("clears quality shadow for a relay subtree when its source changes", () => {+ const routes = controller(2);+ addViewer(routes, A, 2);+ addViewer(routes, B, 2);+ addViewer(routes, C, 0);+ routes.hydrateEdge(A, peerEdge(HOST, "a_from_host"));+ routes.hydrateEdge(B, peerEdge(A, "b_from_a"));+ routes.hydrateEdge(C, peerEdge(B, "c_from_b"));+ const revision = routes.snapshot().revision;++ for (const [childPeerId, parentPeerId, connectionId] of [+ [B, A, "b_from_a"],+ [C, B, "c_from_b"],+ ] as const) {+ expect(+ routes.observeQualityEvidence({+ childPeerId,+ childSessionId: `${childPeerId}_session`,+ routeRevision: revision,+ connectionId,+ upstream: { kind: "peer", peerId: parentPeerId },+ presentationEpoch: 1,+ windowMs: 2_000,+ metrics: qualityMetrics(),+ acceptedAtMs: 1_000,+ }),+ ).toBe("observed");+ }+ expect(+ routes+ .routeDiagnosticSnapshot(1_001)+ .children.filter((child) => child.quality !== null),+ ).toHaveLength(2);++ expect(+ routes.adoptDirectConnection({+ childPeerId: A,+ childSessionId: `${A}_session`,+ parentSessionId: "host_session",+ routeRevision: revision,+ connectionId: "a_from_host",+ newConnectionId: "a_from_host_recovered",+ }),+ ).toBe(true);+ expect(+ routes+ .routeDiagnosticSnapshot(1_002)+ .children.every((child) => child.quality === null),+ ).toBe(true);++ for (const [acceptedAtMs, expected] of [+ [1_100, "accepted"],+ [3_100, "observed"],+ ] as const) {+ for (const [childPeerId, parentPeerId, connectionId] of [+ [B, A, "b_from_a"],+ [C, B, "c_from_b"],+ ] as const) {+ expect(+ routes.observeQualityEvidence({+ childPeerId,+ childSessionId: `${childPeerId}_session`,+ routeRevision: revision,+ connectionId,+ upstream: { kind: "peer", peerId: parentPeerId },+ presentationEpoch: 1,+ windowMs: 2_000,+ metrics: qualityMetrics(),+ acceptedAtMs,+ }),+ ).toBe(expected);+ }+ }+ expect(+ routes+ .routeDiagnosticSnapshot(3_101)+ .children.filter((child) => child.quality !== null),+ ).toHaveLength(2);+ });+it("retains one latest timing sample for a 20-Viewer burst", () => {const routes = controller(2);const viewerPeerIds = Array.from(@@ -172,6 +361,7 @@ describe("RoomRouteController", () => {finalMs: null,finalRoute: "waiting",rejectionBucket: "none",+ quality: null,},],operation: null,diff --git a/tests/server-signal.test.ts b/tests/server-signal.test.tsindex dc383879..93046e2b 100644--- a/tests/server-signal.test.ts+++ b/tests/server-signal.test.ts@@ -406,10 +406,11 @@ function viewerQualityEvidenceMessage(connectionId: string,routeRevision: number,sequence = 0,+ presentationEpoch = 0,) {return {type: "viewer-quality-evidence" as const,- guard: { connectionId, routeRevision },+ guard: { connectionId, routeRevision, presentationEpoch },sequence,windowMs: 2_000,metrics: {@@ -426,6 +427,8 @@ function viewerQualityEvidenceMessage(decodeMsPerFrame: 2.4,freezeCountDelta: 0,freezeDurationMsDelta: 0,+ pauseCountDelta: 0,+ pauseDurationMsDelta: 0,codec: "video/VP8",codecProfile: null,codecParameters: null,@@ -896,7 +899,8 @@ describe("WebSocket signaling", () => {});it("forwards exact direct Viewer receive evidence to the Host", async () => {- const harness = await startHarness();+ let now = 10_000;+ const harness = await startHarness({ now: () => now });const host = await openClient(harness.webSocketUrl);const hostAuth = await authenticate(host,@@ -914,6 +918,7 @@ describe("WebSocket signaling", () => {"viewer","evidence-direct-viewer",);+ host.inbox.ignore("viewer-presence");await host.inbox.next("peer-joined");const connectionId = "evidence_direct_connection_12345678";host.socket.send(@@ -937,12 +942,44 @@ describe("WebSocket signaling", () => {upstream: { kind: "peer", peerId: hostAuth.peerId },guard: { connectionId, routeRevision: 0 },});++ viewer.socket.send(+ JSON.stringify(viewerQualityEvidenceMessage(connectionId, 0, 0, 1)),+ );+ await host.inbox.expectNone(40);+ now += 2_000;+ viewer.socket.send(+ JSON.stringify(viewerQualityEvidenceMessage(connectionId, 0, 7, 1)),+ );+ expect(await host.inbox.next("viewer-quality-evidence")).toMatchObject({+ guard: { connectionId, routeRevision: 0, presentationEpoch: 1 },+ sequence: 7,+ });+ now += 2_000;+ viewer.socket.send(+ JSON.stringify(viewerQualityEvidenceMessage(connectionId, 0, 1, 0)),+ );+ await host.inbox.expectNone(40);+ viewer.socket.send(+ JSON.stringify(viewerQualityEvidenceMessage(connectionId, 0, 0, 2)),+ );+ await host.inbox.expectNone(40);+ now += 2_000;+ viewer.socket.send(+ JSON.stringify(viewerQualityEvidenceMessage(connectionId, 0, 9, 2)),+ );+ expect(await host.inbox.next("viewer-quality-evidence")).toMatchObject({+ guard: { connectionId, routeRevision: 0, presentationEpoch: 2 },+ sequence: 9,+ });});it("forwards a relayed child receive report to its exact parent and Host", async () => {+ let now = 10_000;const harness = await startHarness({peerAssistedMedia: true,endpointMediaCopyCapacity: 1,+ now: () => now,});const host = await openClient(harness.webSocketUrl);await authenticate(@@ -1020,6 +1057,45 @@ describe("WebSocket signaling", () => {expect(await host.inbox.next("viewer-quality-evidence")).toMatchObject(expected,);+ host.socket.send(JSON.stringify({ type: "request-route-diagnostic" }));+ const diagnostic = await host.inbox.next("route-diagnostic-snapshot");+ expect(+ diagnostic.snapshot.children.find((entry) => entry.quality !== null)+ ?.quality,+ ).toEqual({+ eligibleWindows: 1,+ eligibleDurationMs: 2_000,+ freezeWindows: 0,+ freezeCount: 0,+ freezeDurationMs: 0,+ pauseCount: 0,+ pauseDurationMs: 0,+ });++ now += 2_000;+ const incomplete = viewerQualityEvidenceMessage(+ childPrepare.candidate.connectionId,+ childPrepare.revision,+ 1,+ );+ child.socket.send(+ JSON.stringify({+ ...incomplete,+ metrics: { ...incomplete.metrics, pauseCountDelta: null },+ }),+ );+ expect(await parent.inbox.next("viewer-quality-evidence")).toMatchObject({+ metrics: { pauseCountDelta: null },+ });+ expect(await host.inbox.next("viewer-quality-evidence")).toMatchObject({+ metrics: { pauseCountDelta: null },+ });+ host.socket.send(JSON.stringify({ type: "request-route-diagnostic" }));+ const unchanged = await host.inbox.next("route-diagnostic-snapshot");+ expect(+ unchanged.snapshot.children.find((entry) => entry.quality !== null)+ ?.quality?.eligibleWindows,+ ).toBe(1);});it("shares an opted-in Host name with Host and Viewer roster subscribers", async () => {@@ -2908,7 +2984,7 @@ describe("WebSocket signaling", () => {expect(await closeCode).toBe(1009);});- it("terminates stale v10 before authentication", async () => {+ it("terminates stale v12 before authentication", async () => {const harness = await startHarness();const invalidClient = await openClient(harness.webSocketUrl);const closed = new Promise<{ code: number; reason: string }>((resolve) =>@@ -2920,7 +2996,7 @@ describe("WebSocket signaling", () => {invalidClient.socket.send(JSON.stringify({type: "authenticate",- protocol: "screener-v10",+ protocol: "screener-v12",roomId: harness.room.roomId,role: "viewer",clientId: "invalid-client",diff --git a/tests/viewer-presentation.test.ts b/tests/viewer-presentation.test.tsindex f1354b1e..c9005e1d 100644--- a/tests/viewer-presentation.test.ts+++ b/tests/viewer-presentation.test.ts@@ -370,6 +370,50 @@ describe("Viewer presentation reducer", () => {});});+ it("requires a new composited frame after presentation proof resets", () => {+ const playing = apply(+ { type: "access", access: "ready" },+ { type: "signal", signal: "connected" },+ { type: "host", host: "online" },+ { type: "route", revision: 3, phase: "active", kind: "p2p" },+ { type: "media-bound", generation: 2, revision: 3 },+ { type: "frame-presented", generation: 2, revision: 3 },+ );+ const reset = reduceViewerPresentation(playing, {+ type: "frame-proof-reset",+ generation: 2,+ revision: 3,+ });++ expect(deriveViewerPresentation(reset)).toMatchObject({+ hasCurrentFrame: false,+ hasRetainedFrame: true,+ });+ expect(+ deriveViewerPresentation(+ reduceViewerPresentation(reset, {+ type: "connection",+ revision: 3,+ connection: "reconnecting",+ }),+ ).stage,+ ).toBe("recovering");+ expect(+ reduceViewerPresentation(reset, {+ type: "frame-proof-reset",+ generation: 1,+ revision: 3,+ }),+ ).toBe(reset);+ expect(+ reduceViewerPresentation(reset, {+ type: "frame-presented",+ generation: 2,+ revision: 3,+ }).media?.framePresented,+ ).toBe(true);+ });+it("demotes the current frame when an exact route terminally fails", () => {const playing = apply({ type: "access", access: "ready" },@@ -394,18 +438,40 @@ describe("Viewer presentation reducer", () => {failureCode: "ROUTE_EXHAUSTED",});- const stillPlaying = reduceViewerPresentation(failed, {+ const lateFrame = reduceViewerPresentation(failed, {type: "frame-presented",generation: 3,revision: 4,});- expect(deriveViewerPresentation(stillPlaying)).toMatchObject({- stage: "playing",- overlay: "none",- hasCurrentFrame: true,- hasRetainedFrame: false,- failureCode: null,+ expect(lateFrame).toBe(failed);+ expect(+ reduceViewerPresentation(failed, {+ type: "media-bound",+ generation: 4,+ revision: 4,+ }),+ ).toBe(failed);+ expect(+ reduceViewerPresentation(failed, {+ type: "route",+ revision: 4,+ phase: "active",+ kind: "sfu",+ }).routeStatus,+ ).toEqual({ revision: 4, state: "failed" });++ const localFailure = reduceViewerPresentation(playing, {+ type: "failure",+ failure: "ROUTE_EXHAUSTED",+ revision: 4,});+ expect(+ reduceViewerPresentation(localFailure, {+ type: "media-bound",+ generation: 4,+ revision: 4,+ }),+ ).toBe(localFailure);});it("honors terminal access, Host pause, and typed route status priority", () => {diff --git a/tests/viewer-quality-evidence.test.ts b/tests/viewer-quality-evidence.test.tsindex 8a4b2b46..ee2b5ab8 100644--- a/tests/viewer-quality-evidence.test.ts+++ b/tests/viewer-quality-evidence.test.ts@@ -55,6 +55,8 @@ function receiveMetrics(intervalDecodeMs: 2.4,intervalFreezeCount: 0,intervalFreezeDurationMs: 0,+ intervalPauseCount: 0,+ intervalPauseDurationMs: 0,codec: "video/H264",codecProfile: "profile-level-id=42e01f",codecParameters:@@ -84,6 +86,7 @@ function serverEvidence(upstream?: { kind: "peer"; peerId: string } | { kind: "sfu" };connectionId?: string;routeRevision?: number;+ presentationEpoch?: number;sequence?: number;metrics?: Partial<ViewerQualityEvidenceMetrics>;} = {},@@ -99,6 +102,7 @@ function serverEvidence(guard: {connectionId: overrides.connectionId ?? "connection_12345678",routeRevision: overrides.routeRevision ?? 0,+ presentationEpoch: overrides.presentationEpoch ?? 0,},sequence: overrides.sequence ?? 0,windowMs: window.windowMs,@@ -124,6 +128,8 @@ describe("viewer quality evidence", () => {decodeMsPerFrame: 2.4,freezeCountDelta: 0,freezeDurationMsDelta: 0,+ pauseCountDelta: 0,+ pauseDurationMsDelta: 0,codec: "video/H264",codecProfile: "profile-level-id=42e01f",codecParameters:@@ -189,7 +195,7 @@ describe("viewer quality evidence", () => {expect(JSON.stringify(bounded)).not.toContain("203.0.113.20");});- it("rate-limits, deduplicates, and resets sequence per connection", () => {+ it("baselines each presentation epoch and keeps rate limits across it", () => {let now = 10_000;const sent: ClientMessage[] = [];const reporter = new ViewerQualityEvidenceReporter(@@ -201,48 +207,102 @@ describe("viewer quality evidence", () => {);const first = snapshot("connection_first_12345678");- expect(reporter.offer(first, 0)).toBe(true);- expect(reporter.offer(first, 0)).toBe(false);- now += 1_000;+ expect(reporter.offer(first, 0, true)).toBe(false);+ expect(reporter.offer(first, 0, true)).toBe(false);+ now += 2_000;expect(reporter.offer(snapshot(first.connectionId,- receiveMetrics({ sampleTimestampMs: 11_000, bitrateKbps: 7_000 }),+ receiveMetrics({ sampleTimestampMs: 12_000, bitrateKbps: 7_000 }),),0,+ true,),- ).toBe(false);- now += 1_000;+ ).toBe(true);+ now += 2_000;expect(reporter.offer(snapshot(first.connectionId,- receiveMetrics({ sampleTimestampMs: 12_000, bitrateKbps: 6_500 }),+ receiveMetrics({ sampleTimestampMs: 14_000, bitrateKbps: 6_500 }),),- 0,+ 2,+ true,),).toBe(true);expect(reporter.offer(snapshot(first.connectionId,- receiveMetrics({ sampleTimestampMs: 12_000, bitrateKbps: 6_000 }),+ receiveMetrics({ sampleTimestampMs: 14_000, bitrateKbps: 6_000 }),),2,+ true,),- ).toBe(true);+ ).toBe(false);expect(- reporter.offer(snapshot("connection_second_12345678"), 2),+ reporter.offer(+ snapshot(+ "connection_second_12345678",+ receiveMetrics({ sampleTimestampMs: 16_000 }),+ ),+ 2,+ true,+ ),+ ).toBe(false);+ now += 2_000;+ expect(+ reporter.offer(+ snapshot(+ "connection_second_12345678",+ receiveMetrics({ sampleTimestampMs: 18_000 }),+ ),+ 2,+ true,+ ),).toBe(true);now += 2_000;expect(reporter.offer(snapshot("connection_second_12345678",- receiveMetrics({ sampleTimestampMs: 14_000 }),+ receiveMetrics({ sampleTimestampMs: 20_000 }),+ ),+ 2,+ false,+ ),+ ).toBe(false);+ expect(+ reporter.offer(+ snapshot(+ "connection_second_12345678",+ receiveMetrics({ sampleTimestampMs: 20_000 }),+ ),+ 2,+ true,+ ),+ ).toBe(false);+ now += 2_000;+ expect(+ reporter.offer(+ snapshot(+ "connection_second_12345678",+ receiveMetrics({ sampleTimestampMs: 22_000 }),),2,+ true,+ ),+ ).toBe(false);+ now += 2_000;+ expect(+ reporter.offer(+ snapshot(+ "connection_second_12345678",+ receiveMetrics({ sampleTimestampMs: 24_000 }),+ ),+ 2,+ true,),).toBe(true);@@ -252,6 +312,7 @@ describe("viewer quality evidence", () => {? {connectionId: message.guard.connectionId,revision: message.guard.routeRevision,+ epoch: message.guard.presentationEpoch,sequence: message.sequence,}: null,@@ -260,27 +321,26 @@ describe("viewer quality evidence", () => {{connectionId: "connection_first_12345678",revision: 0,+ epoch: 0,sequence: 0,},- {- connectionId: "connection_first_12345678",- revision: 0,- sequence: 1,- },{connectionId: "connection_first_12345678",revision: 2,- sequence: 2,+ epoch: 0,+ sequence: 1,},{connectionId: "connection_second_12345678",revision: 2,+ epoch: 0,sequence: 0,},{connectionId: "connection_second_12345678",revision: 2,- sequence: 1,+ epoch: 1,+ sequence: 0,},]);});@@ -297,6 +357,15 @@ describe("viewer quality evidence", () => {"sfu_connection_12345678",receiveMetrics(),3,+ true,+ ),+ ).toBe(false);+ expect(+ reporter.offerMetrics(+ "sfu_connection_12345678",+ receiveMetrics({ sampleTimestampMs: 12_000 }),+ 3,+ true,),).toBe(true);expect(sent).toEqual([@@ -305,12 +374,87 @@ describe("viewer quality evidence", () => {guard: {connectionId: "sfu_connection_12345678",routeRevision: 3,+ presentationEpoch: 0,},sequence: 0,}),]);});+ it("reports a recovered freeze only after decoded-frame progress resumes", () => {+ let now = 10_000;+ const sent: ClientMessage[] = [];+ const reporter = new ViewerQualityEvidenceReporter(+ (message) => {+ sent.push(message);+ return true;+ },+ () => now,+ );+ const connectionId = "decoded_progress_connection_12345678";++ expect(reporter.offer(snapshot(connectionId), 4, true)).toBe(false);+ now += 2_000;+ expect(+ reporter.offer(+ snapshot(+ connectionId,+ receiveMetrics({ sampleTimestampMs: 12_000 }),+ ),+ 4,+ true,+ ),+ ).toBe(true);+ now += 2_000;+ expect(+ reporter.offer(+ snapshot(+ connectionId,+ receiveMetrics({+ sampleTimestampMs: 14_000,+ intervalFramesDecoded: 0,+ intervalFreezeCount: 1,+ intervalFreezeDurationMs: 2_000,+ }),+ ),+ 4,+ true,+ ),+ ).toBe(false);+ now += 2_000;+ expect(+ reporter.offer(+ snapshot(+ connectionId,+ receiveMetrics({+ sampleTimestampMs: 16_000,+ intervalFreezeCount: 1,+ intervalFreezeDurationMs: 2_000,+ }),+ ),+ 4,+ true,+ ),+ ).toBe(true);++ expect(+ sent.flatMap((message) =>+ message.type === "viewer-quality-evidence"+ ? [+ {+ epoch: message.guard.presentationEpoch,+ sequence: message.sequence,+ freezeDurationMs: message.metrics.freezeDurationMsDelta,+ },+ ]+ : [],+ ),+ ).toEqual([+ { epoch: 0, sequence: 0, freezeDurationMs: 0 },+ { epoch: 0, sequence: 1, freezeDurationMs: 2_000 },+ ]);+ });+it("pairs and renders only the current upstream connection", () => {const evidence = {type: "viewer-quality-evidence",@@ -319,6 +463,7 @@ describe("viewer quality evidence", () => {guard: {connectionId: "connection_12345678",routeRevision: 0,+ presentationEpoch: 0,},sequence: 3,...qualityEvidenceWindowFromMetrics(receiveMetrics())!,@@ -525,6 +670,21 @@ describe("viewer quality evidence", () => {);expect(changedRoute.evidence.metrics.codec).toBe("video/H264");+ const changedPresentation = presentViewerQualityEvidence(+ first,+ serverEvidence({+ sequence: 0,+ presentationEpoch: 1,+ metrics: {+ codec: null,+ codecProfile: null,+ codecParameters: null,+ },+ }),+ 2_000,+ );+ expect(changedPresentation.evidence.metrics.codec).toBeNull();+const changedConnection = presentViewerQualityEvidence(first,serverEvidence({