feat(ui): pick any participant layout from a menu

[renefloor]

StreamLayoutButton flipped between two layouts and drew one of two icons. It now draws the layout in effect and offers the rest through a StreamAdaptiveMenuAnchor: a context menu on a desktop platform, a bottom sheet on Android and iOS. Given two layouts it toggles instead of opening a menu, which is what its default pair does.

Design: menu, sheet.

The seven layouts

Mode	Label	Renders
auto	Default	Speaker full-frame in a one-on-one call, a grid otherwise. The self-view floats over the speaker, and over the grid on mobile while at most two other people are in the call.
grid	Grid	Even grid, local participant as an ordinary tile.
speakerTop / speakerBottom / speakerLeft / speakerRight	Speaker (…)	Spotlight on that edge, with the participants bar along the opposite one.
speakerOneToOne	Speaker 1:1	Spotlight alone, local participant floating over it.

A layout is named after where the speaker sits, not the bar — that is what the design's icons draw, so speakerTop sets ParticipantsBarAlignment.bottom. The four map onto the alignment CallParticipantsSpotlightView already had and RegularCallParticipantsContent never set. Screen share is untouched: StreamCallParticipants.build returns ScreenShareCallParticipantsContent before layoutMode is read, and that widget picks its own alignment from the window aspect ratio.

Notes for review

• auto is the new default for StreamCallContent, StreamCallParticipants and RegularCallParticipantsContent. grid now gives the local participant a tile instead of floating them. The livestream widgets still default to grid, and are otherwise untouched — the new layouts there are for a later PR with designs of their own.
• spotlight → speakerTop, pictureInPicture → speakerOneToOne, both deprecated with fix_data.yaml transforms. spotlight took the spotlight view's default bottom bar, which is speakerTop under the naming above. dart fix --apply migrates call sites; verified end to end on a probe file.
• enableLocalVideo is enableFloatingSelfView now, and localVideoParticipantBuilder is floatingSelfViewBuilder. The flag decides whether the self-view floats over the layout or the local participant takes a tile like anybody else — the old name read as "show my video at all", which the grid and the four bar layouts ignore because those give them a tile either way. dart fix --apply renames both.
• Only auto and speakerOneToOne read it, the two layouts that leave the local participant out of the arrangement. Under speakerOneToOne it defaults to on; under auto in a group call, to on for mobile with at most two other people and off beyond that. That threshold matches the other SDKs: Android gates on callParticipants.size in 2..3, React Native on remoteParticipants.length < 3, Swift on participants.count <= 3.
• speakerOneToOne floats the self-view on desktop too, where the flag otherwise defaults to off. The inset is that layout — without it the local participant, who gets no tile and no bar either, disappears from the call. An explicit false still wins.
• A speaker layout needs somebody to spotlight. participants.first threw StateError on an empty list; five layouts reach that branch now and each is one tap away, so it falls through to the grid instead.
• A layout with no bar always spotlights a remote. With the self-view off, the speaker sort could put the local participant first and spotlight them, and since that layout draws no bar, every remote fell off the screen.
• Changing the layout re-sorts. StreamCallParticipants derives its sort from layoutMode but recalculated only when the participants or the call changed, so picking a speaker layout swapped the preset without reordering and spotlighted whoever the previous preset had first. On a quiet call nothing arrived to correct it. Pre-existing, but a seven-entry menu makes it reachable.
• StreamContextMenuAnchor.defaultActionStyle is new and is the interesting bit. The design fills the selected row, which the sheet did via StreamListTile(selected:) but the anchored menu could not — StreamContextMenuAction has no selected state, and the radio indicator that would otherwise mark it is suppressed by a per-row leading icon. Nesting a second StreamContextMenuActionTheme does not work: .of uses dependOnInheritedWidgetOfExactType, so it shadows rather than layers, and the selected row would drop to core's 40px/242px/20px defaults while its siblings keep the design's 32px/200px/16px. Hoisting the row style makes it re-mergeable. A test pins the metrics alongside the fill.
• menuDirection, not direction, matching the device split buttons, and defaulting to down alongside them so every call control with a menu defaults the same way.
• The sample offers every layout, minus speakerLeft/speakerRight below 768px, where a column of participants beside the speaker leaves the speaker too narrow.

Testing

flutter analyze clean for stream_video_flutter and the sample. 399 tests pass locally; the 38 golden tests need CI to generate their baselines.

Four test files cover the menu, the toggle, menuDirection, what each layout renders, the self-view rules including the mobile threshold and the desktop default, the re-sort on a layout change, and the enum's own derivations — canonical, selectable, barAlignment, isSpeakerLayout and sorting. The two fixes above each have a test that fails without the change. The menu is asserted rather than snapshotted — the CI golden capture drops anything painted into an Overlay.

Checked by eye on macOS and iOS against the Figma: seven rows on the menu, five on the sheet at phone width, per-row icons, active row filled.

🤖 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: ee0d9a14-e7ac-4bb6-9be0-411803356a6e

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 89.37500% with 17 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (v2@11c1f90). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
...zations/stream_video_flutter_localizations_nl.dart	0.00%	9 Missing ⚠️
...l_participants/layout/participant_layout_mode.dart	90.76%	6 Missing ⚠️
...r/lib/src/call_participants/call_participants.dart	85.71%	1 Missing ⚠️
...er/lib/src/call_participants/livestream_hosts.dart	0.00%	1 Missing ⚠️

Additional details and impacted files

@@          Coverage Diff          @@
##             v2    #1332   +/-   ##
=====================================
  Coverage      ?   29.08%           
=====================================
  Files         ?      374           
  Lines         ?    28922           
  Branches      ?        0           
=====================================
  Hits          ?     8413           
  Misses        ?    20509           
  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.