Give each viewport its own say in what a track needs

[renefloor]

Rebased on v2 now that #1351 has landed there. All five commits are this PR's own.

A participant can be drawn by several viewports at once — a tile in the grid, a picture-in-picture overlay, a livestream's host strip — while the call holds a single viewportVisibility per participant and a single subscription per track, keyed '$trackIdPrefix:$trackType'.

Every renderer wrote both directly, so whichever spoke last decided them:

• an overlay that is not showing a participant could record them hidden — taking them out of the running for a speaker's tile and unsubscribing a track the grid is plainly drawing;
• a small overlay that is showing them could pull a full-screen tile's subscription down to its own resolution.

#1339 worked around the first half by having a renderer re-assert upwards only — a renderer showing the participant insists, one that is not stays quiet. That stops two renderers ping-ponging, but only because it takes the argument away from one of them; it does nothing for the second half, and it is why the guards in didUpdateWidget read as an odd asymmetry.

The change

Call.viewportVisibility is a ViewportVisibilityRegistry: one ViewportMeasurement per viewport per track, and one ViewportAggregate derived from all of them.

• visible while any viewport has the track on screen;
• sized for the largest viewport that does — anything smaller scales down, nothing scales up;
• persistWhenHidden if any viewport asked for it, so a screen share still overrides.

Call._applyViewportAggregate is the single writer into updateViewportVisibility / updateSubscription / removeSubscription, keeping the existing "only a remote track is subscribed to" guard. It answers whether the write landed, and the registry forgets an answer that did not — so a write that failed or was declined is driven again rather than deduplicated against.

Measuring and reporting a viewport is its own widget, ViewportVisibilityReporter: it holds the detector, the name it reports under, the deferral that keeps a report out of a build, and the release when it goes away. StreamVideoRenderer wraps its child in one and is a StatelessWidget again — there was nothing left for it to keep. The reporter is exported, so a custom widget drawing a participant's track can take part in what the call subscribes to instead of being invisible to it.

It takes a ViewportVisibilityRegistry rather than a Call, since that is all it ever used, and attach()es for a ViewportHandle of its own to report through. A reporter handed a different registry retires its old handle and attaches to the new one, rather than leaving a track recorded as on screen in a call it has left.

Two things fall out, and they are the argument for the shape:

• The re-assert is gone. It existed so two renderers overwriting one field would settle instead of arguing. With one writer over a registry there is nothing to argue about, so the asymmetry disappears rather than being explained in a comment.
• A new session is told every track again — reapplyAll(), called at the end of join, once the join response has rebuilt the participant list. A viewport reports what changes about itself, so a tile that sat on screen across a reconnect would never speak again on its own. That dropped report is the damage #1339 was really patching over, now repaired at the source. The placement matters: a join response builds every participant afresh from the SFU carrying no viewport visibility, so anything reapplied before it is overwritten while the registry believes it was said.

Review follow-up

The fourth commit is review follow-up, on top of the shape above:

• Call._applyViewportAggregate logs its failures, treats a disconnected call as not applied, and tells a participant the call does not have apart from a local or unpublished track.
• The subscription is dropped on the aggregate being hidden rather than on an empty dimension, so a visible track cannot be unsubscribed.
• ViewportVisibilityReporter ignores the last, hidden report a VisibilityDetector delivers after it is gone — dispose() there does not forget(key) — which otherwise put the viewport back with nothing left alive to release it.
• Each reporter keys its own detector rather than keying it by track, so two viewports drawing one track cannot drop each other's reports whatever the caller passes for scopePrefix, and a reporter pointed at a new track re-reports instead of relying on the key changing. That also covers a trackIdPrefix-only change, which an SFU migration produces and the old key would not have noticed.

The viewport handle

The fifth commit is a follow-up of its own, on the registry's public shape.

A viewport used to be keyed by a String the registry minted and never recorded, so report created an entry for any string at all and release took out whichever one it was handed — and the names were '0', '1', '2'. Since the registry is exported, the invariant the class exists to protect, one measurement per viewport with none overwriting another, was stated in a doc comment and enforced nowhere.

attach() now hands out a ViewportHandle, and the handle is the key. There is no name to forge or collide with, a handle can take out only what it put in, and it belongs to the registry that made it. nextViewportId() and the viewportId: arguments are gone; the API is unreleased, so there is nothing to deprecate.

The handle also holds the track it last reported for, so reporting a new one releases the one before it and dispose() releases whatever is left. That bookkeeping used to live in the reporter's own field and its didUpdateWidget, which is why the commit is a net deletion — every consumer now gets it from the handle rather than reproducing it.

The nine reporter widget tests pass unchanged, which is the argument that this is a refactor and not a behaviour change.

Testing

• 19 unit tests for the registry: aggregation, release, reapply for a track only now published, the reconnect flush, a viewport letting go of the track it drew before, a disposed handle saying nothing more, and an answer the call could not act on being offered again.
• video_renderer_visibility_test.dart rewritten around what each renderer reports rather than what it writes. The load-bearing one puts the same participant in a grid tile and a smaller scrolling strip and scrolls the strip away — mutating the registry to last-writer-wins makes it fail on the visibility, and mutating it to let the last reporter size the track makes it fail on the size.
• a renderer moved to another call stops speaking to the old one covers the registry swap: the call it leaves is told hidden, the one it joins is told visible at a real size.
• 710 tests in stream_video, 444 in stream_video_flutter. The 38 golden failures in call_control_bar_golden_test.dart are the same ones v2 has.

One thing worth a reviewer's eye: MockCall now default-stubs viewportVisibility with a no-op registry, like it already does for isTrackPaused. Without it every widget test that pumps a tile throws, and a throw inside a VisibilityDetector callback wedges the detector for every later test in the file.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: af537001-8cf8-4247-b22e-ec25d26dfe2f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 87.69231% with 24 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (v2@3fcff16). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
...video_flutter/lib/src/renderer/video_renderer.dart	55.55%	12 Missing ⚠️
...eam_video/lib/src/models/viewport_measurement.dart	58.82%	7 Missing ⚠️
packages/stream_video/lib/src/call/call.dart	87.80%	5 Missing ⚠️

Additional details and impacted files

@@          Coverage Diff          @@
##             v2    #1353   +/-   ##
=====================================
  Coverage      ?   32.80%           
=====================================
  Files         ?      380           
  Lines         ?    29051           
  Branches      ?        0           
=====================================
  Hits          ?     9531           
  Misses        ?    19520           
  Partials      ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Brazol]

This guard makes persistWhenHidden a snapshot taken at report time — nothing re-reports when only that flag changes, so a runtime change to persistTrackIfNotVisible never reaches the registry. The renderer this replaces read it live, at the moment it chose between removeSubscription and updateSubscription.

ScreenShareContent flips it at runtime, off InteractiveViewer.onInteractionUpdate (persistTrackIfNotVisible: _isZoomed). Zoom into a screen share and scroll it off screen: the registry still holds persistWhenHidden: false, the aggregate comes out hidden-and-not-persisted, and the subscription is dropped — which is what the flag exists to prevent. Un-zooming is the mirror case: a stale true keeps a track subscribed that should have been let go.

One more clause covers it, and it belongs in standing's true case since what the viewport measures hasn't moved — only what it asks for:

final persistChanged =
    oldWidget.persistWhenHidden != widget.persistWhenHidden;
if (!registryChanged && !trackChanged && !publishedNow && !persistChanged) {
  return;
}

_report reads widget.persistWhenHidden live, so the deferred report picks the new value up on its own.