Stop the focus border test assuming a second device row

Firefox in CI reports one microphone and no outputs, so the menu has a
single selectable row and hovering the second timed out. The test now
drives the pointer by coordinate over the first row, which holds however
many devices a browser reports.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.github/PULL_REQUEST_TEMPLATE.md

@@ -5,7 +5,7 @@
 > Every PR must have a linked issue
 > that a maintainer has reviewed and approved **before you started writing code**.
 > PRs that don't meet this requirement will not be reviewed.
-> See [CONTRIBUTING.md](https://github.com/element-hq/element-call/blob/livekit/CONTRIBUTING.md) for ElementCall decided for this approach.
+> See [CONTRIBUTING.md](https://github.com/element-hq/element-call/blob/main/CONTRIBUTING.md) for ElementCall decided for this approach.
 
 ## Content
 
@@ -39,7 +39,7 @@ Uncomment the markdown table below and fill in the last line:
 ## Checklist
 
 - [ ] A linked, pre-approved issue exists for this feature or UI change.
-- [ ] I have read [CONTRIBUTING.md](https://github.com/element-hq/element-call/blob/livekit/CONTRIBUTING.md) in full.
+- [ ] I have read [CONTRIBUTING.md](https://github.com/element-hq/element-call/blob/main/CONTRIBUTING.md) in full.
 - [ ] Pull request includes screenshots or videos for any UI changes.
 - [ ] Tests written for new code (and existing touched code where feasible).
 - [ ] Linter and other CI checks pass.

.github/workflows/build.yaml

@@ -6,7 +6,7 @@ on:
       - opened
       - labeled
   push:
-    branches: [livekit, full-mesh]
+    branches: [main]
 jobs:
   build_full_element_call:
     # Use the full package vite build
@@ -22,8 +22,8 @@ jobs:
       SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
   deploy_develop:
-    # Deploy livekit branch to call.element.dev after build completes
-    if: github.ref == 'refs/heads/livekit'
+    # Deploy main branch to call.element.dev after build completes
+    if: github.ref == 'refs/heads/main'
     needs: build_full_element_call
     runs-on: ubuntu-latest
     steps:
@@ -43,8 +43,8 @@ jobs:
                 }
             })
   docker_for_develop:
-    # Build docker and publish docker for livekit branch after build completes
-    if: github.ref == 'refs/heads/livekit'
+    # Build docker and publish docker for main branch after build completes
+    if: github.ref == 'refs/heads/main'
     needs: build_full_element_call
     permissions:
       contents: write

.gitignore

@@ -10,6 +10,9 @@ public/config.json
 backend/synapse_tmp/*
 backend/synapse_tmp_othersite/*
 /coverage
+
+# Transient agent scratch files
+/agent-workspace/
 config.json
 
 # Yarn

.oxfmtrc.json

@@ -2,5 +2,5 @@
   "$schema": "./node_modules/oxfmt/configuration_schema.json",
   "printWidth": 80,
   "sortPackageJson": false,
-  "ignorePatterns": ["pnpm-lock.yaml", "node_modules", "dist"]
+  "ignorePatterns": ["pnpm-lock.yaml", "node_modules", "dist", "FEATURES_SPEC"]
 }

.oxlintrc.json

@@ -39,6 +39,17 @@
     "jsdoc/check-property-names": "error",
     "jsdoc/require-param-description": "warn",
     "react/display-name": "error",
+    // TODO: These React Compiler-based rules joined oxlint's correctness
+    // category in v1.81 and flag many pre-existing patterns, including hooks
+    // like useLatest/useInitial/useReactiveState that intentionally access
+    // refs during render. Re-evaluate them when adopting the React Compiler.
+    "react/immutability": "off",
+    "react/no-deriving-state-in-effects": "off",
+    "react/preserve-manual-memoization": "off",
+    "react/refs": "off",
+    "react/set-state-in-effect": "off",
+    "react/static-components": "off",
+    "react/use-memo": "off",
     // TODO: Re-enable once oxlint supports lint rules that rely on TypeScript type-awareness.
     // "rxjs/no-exposed-subjects": "error",
     // "rxjs/finnish": [

.storybook/preview.tsx

@@ -7,14 +7,16 @@ Please see LICENSE in the repository root for full details.
 
 import type { Preview } from "@storybook/react-vite";
 import { TooltipProvider } from "@vector-im/compound-web";
-import i18n from "i18next";
 import { logger } from "matrix-js-sdk/lib/logger";
 
 import EN from "../locales/en/app.json";
 import { initReactI18next } from "react-i18next";
+import { i18n } from "../src/utils/i18n";
 import "../src/index.css";
 
-// Bare-minimum i18n config
+// Bare-minimum i18n config.
+// Unlike the app, stories register the instance as react-i18next's default
+// rather than wrapping every story in an <I18nextProvider>.
 i18n
   .use(initReactI18next)
   .init({

AGENTS.md

@@ -0,0 +1,52 @@
+# AGENTS.md — Element Call
+
+MatrixRTC (MSC4143) + LiveKit video calling, shipped standalone, as a widget in
+Element Web and Element X, as embedded packages, and as a React component in a
+host's page. It is the MatrixRTC reference implementation.
+
+## Non-negotiables
+
+- Features and UI changes need a pre-approved issue. No issue, no review.
+- Exactly one `PR-*` label per PR. CI enforces it; it drives the changelog.
+- New behaviour ships with unit tests, a story if it renders, and an e2e spec if it
+  is user-facing. All three.
+- Reuse an existing component. If you genuinely cannot, say so in the PR body and
+  name what you rejected — never add a new one silently.
+- Nothing reads the page. No `window.location`, `document.body`, `window.inner*`,
+  `@media`, global `i18next` or the `widget` global — take it from a provider.
+- The change works standalone, as a widget and as a component. Say what you checked.
+- Every gate below is green before you push.
+- Hand off after the first implementation, before the quality pass. Commit when the
+  user confirms direction, not before.
+
+## Read before you
+
+| …                                | …                                                          |
+| -------------------------------- | ---------------------------------------------------------- |
+| start a task of any size         | [docs/agents/workflow.md](docs/agents/workflow.md)         |
+| touch call logic or a view model | [docs/agents/architecture.md](docs/agents/architecture.md) |
+| write any code                   | [docs/agents/code-style.md](docs/agents/code-style.md)     |
+| write a test, story or e2e spec  | [docs/agents/testing.md](docs/agents/testing.md)           |
+| open a PR                        | [CONTRIBUTING.md](CONTRIBUTING.md)                         |
+| implement from a feature spec    | [FEATURES_SPEC/AGENTS.md](FEATURES_SPEC/AGENTS.md)         |
+
+## Gates
+
+```sh
+pnpm lint            # tsc, oxlint, knip, component externals
+pnpm format          # oxfmt
+pnpm test            # vitest: unit and storybook projects
+pnpm i18n:check
+```
+
+`knip` fails on dead code; a file deliberately inert ahead of its consumer goes in
+`knip.ts` `ignoreFiles` with a reason.
+
+## A good PR
+
+- One slice, under ~400 changed lines, green on its own, linked to its issue.
+- View model + marble tests, thin view, a story per state, an e2e spec.
+- Any new shared component called out explicitly, with why nothing existing fit.
+- Template filled for real: what, why, before/after screenshots, repro steps.
+- Branch `<handle>/<topic>`. Plain imperative commit subjects, no prefixes.
+- Once review starts, fix forward. Never force-push a regeneration over a review.

FEATURES_SPEC/2026-09_Audio_Quick_Menu.md

@@ -0,0 +1,356 @@
+---
+status: implement
+blocked_from: null
+title: Audio quick menu
+owner: fkwp
+signoff:
+  eng: ok
+  design: ok
+  product: ok
+experiment_ref: fkwp/feature/audio_quick_menu_exploration
+base: 029622f07b44f58f8a84e7e167e5b66374479b63
+repos: [element-call]
+specs: []
+supersedes: []
+superseded_by: null
+---
+
+## Problem
+
+- `MediaMuteAndSwitchButton` populates its menu from `audioInput.available$` only. On
+  desktop, audio output is reachable only through `SettingsModal` → audio tab, which covers
+  the call view; the footer's `audioOutputSwitcher$` is an earpiece/loudspeaker toggle that
+  only materialises for controlled (mobile) devices.
+- No input-level indicator exists anywhere in the app: a participant cannot tell whether the
+  selected microphone captures sound without unmuting and asking another participant.
+- `soundEffectVolume` is adjustable only in `SettingsModal`, which replaces the call view.
+- `DeviceSelection` renders nothing when `available.size <= 1`, and `AudioOutput.available$`
+  is emptied on Safari, so those users get no indication of where call audio is going.
+- The in-call chevron is suppressed off desktop and in PiP via `disableDeviceSwitcher$`
+  (`CallFooterViewModel`), while `createLobbyFooterViewModel` passes `constant(false)`; the
+  two surfaces already disagree about when the menu exists.
+
+## Decisions
+
+- D1 — The level indicator captures from the microphone only while the menu is open, muted or
+  not — bounds the capture and the microphone-in-use indicator to a deliberate user action
+  while still answering "is my microphone working?" before unmuting.
+- D2 — The menu appears both before joining and during a call — pre-join is where a device
+  check matters most, in-call is where the settings detour costs most.
+- D3 — Before joining, the full menu appears on every platform, including mobile; during a
+  call it stays web/desktop only — the pre-join chevron already exists everywhere, so
+  suppressing sections there would be new work for no user gain.
+- D4 — Sound-effects volume appears in the menu and stays in settings, both reading and
+  writing one stored value — no migration, and neither audience loses the control it knows.
+- D5 — Where the audio output cannot be changed, the menu still shows the active output as a
+  non-selectable row — knowing where audio goes is useful even when it cannot be redirected.
+- D6 — The menu carries no disclosure that the microphone is sampled while muted — mute state
+  and the operating system's microphone-in-use indicator are independent of each other.
+- D7 — A microphone producing no signal shows an idle indicator; one held exclusively by
+  another application shows a greyed-out indicator — two distinguishable states, the second
+  rare on current operating systems.
+- D8 — A denied microphone permission shows a hint rather than a silent idle indicator —
+  silence is otherwise indistinguishable from a broken microphone.
+- D9 — The level indicator is focusable and announces its state to a screen reader while
+  focused — it is the one control in the menu with no non-visual equivalent.
+- D10 — No numeric latency target for the level indicator; it must move visibly while the
+  person is still speaking — perceived latency is not critical for a presence check.
+- D11 — Only the device lists scroll; the menu's heading and the sound-effect slider stay
+  in place — a list longer than the screen otherwise carries both out of view.
+- D12 — The level indicator belongs to the microphone group and stays visible while that
+  group is on screen, rather than sitting with the output controls — pinned next to the
+  sound-effect slider it reads as one of them.
+- D13 — Keyboard navigation marks the current item with a border, pointer use marks it with
+  a background and no border — the menu moves focus to whatever the pointer is over, so
+  without the distinction both appear at once.
+
+## Acceptance criteria
+
+Test names are the anchor; tests are created with exactly these names.
+
+- AC1 [FR-001] — The chevron beside the microphone button opens a menu headed "Audio controls".
+  - check: `pnpm vitest run --project=unit -t "audio menu is headed Audio controls"`
+- AC2 [FR-002] — The menu lists every available microphone, marks the active one, and selecting
+  another switches input without closing the menu.
+  - check: `pnpm vitest run --project=unit -t "audio menu switches microphone and stays open"`
+- AC3 [FR-003] — The menu lists every available audio output, marks the active one, and
+  selecting another switches output without closing the menu.
+  - check: `pnpm vitest run --project=unit -t "audio menu switches audio output and stays open"`
+- AC4 [FR-004] — The menu renders a separator between the microphone, speaker and
+  sound-effects groups.
+  - check: `pnpm vitest run --project=unit -t "audio menu separates microphone speaker and sound effects groups"`
+- AC5 [FR-005] — With exactly one audio output available, the speaker group still names the
+  active output and offers no selectable row.
+  - check: `pnpm vitest run --project=unit -t "audio menu shows single audio output as non-selectable"`
+- AC6 [FR-005] — In a browser that does not permit choosing an audio output, the speaker group
+  names the active output and offers no selectable row.
+  - check: manual, on Safari: join a call, open the microphone chevron, confirm the speaker
+    group names the output in use and that no row responds to a click.
+- AC7 [FR-006] — An output selected in the menu is shown as active in settings, and an output
+  selected in settings is shown as active in the menu.
+  - check: `pnpm vitest run --project=unit -t "audio output selection is shared between menu and settings"`
+- AC8 [FR-007] — While the menu is open, the level indicator's reported level follows the
+  signal level of the selected microphone.
+  - check: `pnpm vitest run --project=unit -t "level indicator follows the microphone signal level"`
+- AC9 [FR-008] — The level indicator responds to the microphone signal while the participant
+  is muted.
+  - check: `pnpm vitest run --project=unit -t "level indicator responds while muted"`
+- AC10 [FR-009] — Opening the menu starts capturing from the selected microphone; closing it
+  stops the capture.
+  - check: `pnpm vitest run --project=unit -t "audio menu starts capture on open and stops on close"`
+- AC11 [internal] — No microphone capture started by the menu outlives the menu, including
+  when the menu is closed while a device switch is in flight.
+  - check: `pnpm vitest run --project=unit -t "menu capture is released when closed during a device switch"`
+- AC12 [FR-010] — Selecting a different microphone re-points the level indicator at it without
+  closing the menu.
+  - check: `pnpm vitest run --project=unit -t "level indicator follows a microphone change"`
+- AC13 [FR-011] — A selected microphone that produces no signal leaves the indicator in its
+  idle state and produces no error.
+  - check: `pnpm vitest run --project=unit -t "level indicator stays idle for a silent microphone"`
+- AC14 [FR-018] — With microphone permission denied, the menu shows a hint in place of the
+  idle indicator.
+  - check: `pnpm vitest run --project=unit -t "audio menu hints when microphone permission is denied"`
+- AC15 [D7] — When the selected microphone cannot be opened because another application holds
+  it, the indicator renders in a greyed-out state.
+  - check: `pnpm vitest run --project=storybook -t "Microphone Unavailable"`, which reads
+    the greying a browser applies. The unit test
+    `-t "level indicator greys out when the microphone is unavailable"` covers the state
+    the stylesheet keys off, and cannot fail on the greying itself.
+- AC16 [FR-012] — Moving the sound-effects slider changes the level at which the next sound
+  effect plays.
+  - check: `pnpm vitest run --project=unit -t "sound effects volume from the menu applies to the next effect"`
+- AC17 [FR-013] — Sound-effects volume set in the menu is shown in settings and vice versa.
+  - check: `pnpm vitest run --project=unit -t "sound effects volume is shared between menu and settings"`
+- AC18 [FR-014] — The full menu is present before joining on every platform, and during a call
+  on web and desktop.
+  - check: `pnpm vitest run --project=unit -t "audio menu is present pre-join on every platform"`
+- AC19 [FR-015] — During a call on mobile, the microphone chevron offers no menu.
+  - check: `pnpm test:playwright --project=mobile -g "no audio menu during a call on mobile"`
+- AC20 [FR-016] — Every control in the menu — device rows, level indicator and sound-effects
+  slider — is reachable and operable from the keyboard alone.
+  - check: `pnpm vitest run --project=unit -t "audio menu is fully operable from the keyboard"`
+- AC21 [FR-017] — The level indicator takes focus and announces its current state to a screen
+  reader while focused.
+  - check: manual, with VoiceOver active: open the menu, tab to the level indicator, speak,
+    confirm the announced state changes with the signal.
+- AC22 [D11] — With more devices than fit on screen, the heading and the sound-effect slider
+  stay visible while the device lists scroll.
+  - check: `pnpm vitest run --project=storybook -t "With Many Devices"`, which measures the
+    layout in a browser with the device count fixed. The unit test
+    `-t "audio menu keeps its title and volume slider out of the scrolling area"` and the
+    e2e `-g "audio menu stays inside a short window"` cover the structure and the window
+    bound; neither can fail on layout alone.
+- AC23 [D12] — The level indicator stays with the microphone list and never sits among the
+  output controls.
+  - check: `pnpm vitest run --project=unit -t "level indicator stays with the microphone list rather than the speakers"`
+- AC24 [D13] — Moving through the menu by keyboard marks the current item with a border;
+  moving over it with a pointer marks it with a background and no border.
+  - check: `pnpm test:playwright --project=chromium --project=firefox -g "the focus border follows the keyboard and not the pointer"`
+- AC25 [SC-001] — Selecting an output from the menu during a call leaves the other
+  participants visible throughout.
+  - check: `pnpm test:playwright --project=chromium -g "audio menu leaves participants visible while switching output"`
+- AC26 [SC-002] — In a real browser with the menu open, sound at the microphone moves the
+  level indicator.
+  - check: `pnpm test:playwright --project=chromium --project=firefox -g "level indicator moves with microphone input"`
+- AC27 [SC-003] — Every menu control is reachable and operable by keyboard alone in
+  Chromium and Firefox.
+  - check: `pnpm test:playwright --project=chromium --project=firefox -g "audio menu is keyboard operable in a real browser"`
+- AC28 [review: #4254] — With no microphone present, the menu names the absence in place
+  of the level indicator, rather than an indicator at rest.
+  - check: `pnpm vitest run --project=unit -t "audio menu says when there is no microphone"`
+
+## Rejected alternatives
+
+- Driving the level meter from the microphone track the call already publishes — the
+  track is muted exactly when the user is muted, so the meter reads flat in the one
+  situation it exists for (D1, FR-008). A capture of its own is what makes a muted
+  check possible.
+- Gating the audio menu on there being more than one microphone, as the chevron did
+  before — leaves no menu at all where there are no input devices to list but an
+  output section is still worth showing, which is the pre-join case on iOS (D3).
+- Naming the sound-effects slider with `aria-label` — the shared slider takes its
+  accessible name from its tooltip, so the label was overridden and the control
+  announced itself as "50%". The tooltip text now carries the control's name.
+- Bounding the height of the menu as a whole — keeps it on screen, but scrolls the
+  heading away with the device list, which is what the bound was meant to prevent (D11).
+- Pinning the level meter beside the sound-effect slider — always visible, but read as
+  one of the output controls rather than as a reading of the microphone (D12).
+- Letting the level meter scroll with the microphone list — on a machine with many
+  devices it is off screen for most of the interaction (D12).
+- Fixed-width meter bars spread across the row — all leftover width lands in the gaps,
+  so the bars read as thin lines separated by wide spaces. The bars share the row
+  instead, and the gap and bar count together set their thickness.
+
+## Measurements
+
+- Unit suite: ≥ 771 passing, 0 failing, ≥ 98 files (method: `pnpm vitest run --project=unit`
+  on the experiment branch rebased onto `base`, 2026-09-10; measured 771 / 0 / 98, 9 skipped).
+- SC-001: holds (method: manual, owner, 2026-09-10 — output switched from the microphone
+  chevron menu during a call; the other participants stayed visible throughout).
+- SC-002: holds (method: manual, owner, 2026-09-10 — menu open, speaking, muted and
+  unmuted; the level indicator moved while still speaking).
+- SC-003: holds (method: manual, owner, 2026-09-10 — every menu control reached and
+  operated by keyboard alone on the supported desktop browsers).
+- Not measured: what the meter's second concurrent capture costs alongside the call's own
+  — CPU of the second capture, analyser and per-frame poll during a call, and any glitch
+  on the call's own track when the capture opens or closes.
+
+## Out of scope
+
+- The in-call chevron on mobile (`platform` `android` / `ios`), which stays suppressed by
+  `disableDeviceSwitcher$` — FR-015. The lobby chevron is in scope on every platform
+  (FR-014), so whatever `audioOutput.available$` reports there — including the
+  speaker/earpiece entries of `AndroidControlledAudioOutput` / `IOSControlledAudioOutput` —
+  is rendered by the same menu.
+- The iOS native audio-device picker button (`showNativeAudioDevicePicker`); it stays in
+  `SettingsModal`.
+- The camera chevron menu and the background-blur toggle it carries.
+- PiP layout; the menu stays suppressed there.
+- An output test tone or "play test sound" affordance.
+- Noise suppression, echo cancellation and gain controls.
+- Restructuring the settings dialog beyond keeping the sound-effects slider in place.
+
+## Open questions
+
+None.
+
+## Slicing plan
+
+Re-derived 2026-09-10 against head 029622f (see Drift log). Owner decision 2026-09-10: the
+feature lands as one PR into `fkwp/feature/audio_quick_menu`, one commit per slice, each
+commit building and passing the unit suite on its own. Order follows story priority: US1
+(P1) first, US2 (P2) second, US3 (P3) third; FR-014's pre-join surface last. Both footers
+read one `MediaDevices` helper, so slice 1 lights the menu up on either surface and slice 5
+is what holds it there.
+
+1. Audio menu: "Audio controls" heading, microphone and speaker groups, active output as
+   a non-selectable row where it cannot be changed, outputs derived in
+   `CallFooterViewModel` — covers AC1, AC2, AC3, AC5, AC6, AC7, AC25 — depends on: none
+2. Level meter component and its capture hook, unused until slice 3 — covers AC8, AC11,
+   AC13, AC15 — depends on: none
+3. Level meter in the microphone group: capture bound to the menu being open, placement
+   with the microphone list, keyboard and pointer focus states — covers AC9, AC10, AC12,
+   AC14, AC23, AC24, AC26 — depends on: 1, 2
+4. Sound-effects volume in the menu, with only the device lists scrolling — covers AC4,
+   AC16, AC17, AC20, AC21, AC22, AC27 — depends on: 3
+5. Surface coverage: the menu reaches every platform before joining and stays gated to
+   desktop during a call — covers AC18, AC19 — depends on: 4
+
+## Drift log
+
+### 2026-09-10 — drift check (base 029622f → head 029622f)
+- `origin/main` is at `base`; `base..head` is empty. Every file and symbol named in
+  `## Problem`, `## Measurements` and the provisional slicing plan exists unchanged; no
+  decision is contradicted.
+- AC check commands: vitest project `unit` and playwright projects `chromium`, `firefox`
+  and `mobile` exist; every command runs.
+- Slicing plan re-derived on size and story priority, not on drift: the provisional
+  slice 2 (menu, speakers and meter, plus the `LobbyView` and `InCallView` snapshot
+  churn) exceeds the 800-line hard stop, and the P1 story (output selection) did not
+  lead. The pre-join surface moves to its own slice so the lobby snapshots change once.
+- Implementation base: `fkwp/feature/audio_quick_menu` = head + the repo agent contract
+  and the FEATURES_SPEC process, which are in review of their own. No source file differs
+  from head. The slices and this spec ride on one branch that opens a PR against it.
+
+### 2026-09-10 — owner decision: single PR
+- The five slices land as one PR with one commit per slice, at roughly 2000 changed lines.
+  Deviates from the 800-line hard stop in `FEATURES_SPEC/AGENTS.md` ("Turning a spec into
+  PRs", step 3); accepted by the owner for a feature of this size. Review is per commit.
+- The meter's capture cost stays unmeasured (see `## Measurements`): it needs a real-browser
+  CPU profile during a call, which the implementation environment cannot produce.
+
+### 2026-09-10 — implementation findings (head 029622f)
+- The level meter reads zero on Firefox in CI, and neither the test device nor the code is
+  the reason: Firefox's fake stream carries a 1 kHz tone at about a tenth of full scale,
+  and the same test drives the meter to 0.62 against Firefox off the runner, including
+  against the Docker image over plain HTTP that CI serves. The runner has no audio backend
+  for Firefox. AC26 is therefore skipped there, a deviation from its check.
+- Firefox starts an `AudioContext` suspended, which feeds the analyser silence until it
+  resumes of its own accord seconds later. The capture is now resumed on creation, so the
+  meter answers while the person is still speaking (D10).
+- AC27 is skipped on Firefox too, a deviation from its check, because headless Firefox
+  drives Tab unreliably, as `reconnect.spec.ts` records. AC25 skips Firefox, whose fake
+  stream enumerates no audio outputs and so has nothing to switch; its check names only
+  Chromium, so that is not a deviation.
+- Keyboard reach: the Radix menu swallows Tab and walks only its own items with the arrow
+  keys, so the meter and the slider were unreachable by keyboard alone. The audio menu
+  keeps Tab from the menu so the browser's focus order reaches them (AC20, AC27); the
+  exploration's keyboard test had only asserted that the controls exist.
+- Unit suite on the PR head: 99 files, 784 passing, 0 failing, 9 skipped (method:
+  `pnpm vitest run --project=unit`, 2026-09-10). The ≥ 771 / ≥ 98 floor holds.
+
+### 2026-09-10 — finding: menu taller than the viewport (AC22, D11)
+- With many devices the menu overflowed the viewport and carried the heading off the top:
+  its height bound applied to the content box, leaving the menu's own padding outside it.
+  Fixed by bounding the border box. AC22's check runs in jsdom, which lays nothing out, so
+  it passed throughout. The story `CallFooter › With Many Devices` now measures the layout
+  in a browser with the device count fixed; owner to decide whether AC22's check names it.
+  An e2e test cannot stand in for it, because how many devices overflow the menu depends on
+  how many a browser invents: the e2e test "audio menu stays inside a short window" asserts
+  only what holds at any device count.
+
+### 2026-09-10 — upstream PRs for the base of this branch
+- The repo agent contract and the FEATURES_SPEC process go to `main` on their own: #4256
+  (`fkwp/agents-md`) and #4255 (`fkwp/features-spec-process`). `fkwp/feature/audio_quick_menu`
+  carries both as if merged; rebasing it onto `main` after they land drops the duplicates.
+
+### 2026-09-10 — finding: chevron menus leave the root in the component build
+- Compound's `Menu` portals to `document.body`, and the component build rewrites every
+  selector to match only `[data-element-call-root]` or its descendants. A menu opened there
+  matches none of its own styles: no background, no border, no padding, and the audio menu's
+  height bound is inert, so nothing holds a long device list inside the window. Measured in
+  the component harness, which applies the same scoping the library build ships.
+- Not introduced by this feature. The camera chevron menu, untouched here, is equally
+  unstyled in that build, and no component test covers a menu, which is why it went unseen.
+- Out of scope for this spec: the fix is to give the portal the root element as its
+  container, which Compound does not expose today. Raised separately. The audio menu behaves
+  as specified standalone and as a widget, which is where its acceptance criteria are checked.
+
+### 2026-09-11 — review finding: a missing microphone read as a silent one (#4254)
+- The product spec's edge case for no microphone mapped to no FR and so to no acceptance
+  criterion, and the menu drew a level indicator at rest, which is what a working but
+  silent microphone draws. The owner chose a hint in the indicator's place, as FR-018
+  requires for a denied permission, over omitting the microphone group entirely. The level
+  state now tells a microphone that is absent from one that is silent.
+- Added as AC28 and the product spec's edge case reworded to match, both with the owner's
+  authorisation, since acceptance criteria and the product spec are human-owned.
+
+### 2026-09-11 — finding: `:focus-visible` cannot express D13 (#4254)
+- The menu moves focus onto whichever item the pointer is over, so the browser decides the
+  modality for a focus it did not see the user cause. Chromium calls every focus after any
+  key press keyboard-driven, so one Escape left the border following the mouse for the rest
+  of the session; Firefox never calls a programmatic focus keyboard-driven, so the border
+  never appeared there at all. Neither matches D13.
+- The menu now tracks which way each item was reached — a key press on the trigger or on an
+  item, against pointer movement over one — and the border follows that. Verified in both
+  browsers: the border appears only after a key press and leaves again on the next pointer
+  move. AC24's manual check could now name a unit test; owner's call.
+
+### 2026-09-11 — acceptance checks that could not fail (#4254)
+- Raised in review: AC22's check ran in jsdom, which lays nothing out, so it passed whatever
+  the layout did — the defect it exists for went unseen until a screenshot. Its check now
+  names the `CallFooter` "With Many Devices" story, which measures the geometry in a browser
+  with the device count fixed. The unit test and the short-window e2e stay as they are; the
+  criterion names the one that would fail.
+- AC24 was a manual check, and the border it describes turned out to be wrong in both
+  browsers for different reasons. Its check now names an e2e test that reads the painted
+  outline as the pointer and the keyboard take turns.
+- The same audit found AC15: its check asserted the attribute the stylesheet keys off, not
+  the greying, so losing the CSS rule would not have failed it. Re-anchored to the meter's
+  own story, which reads the applied opacity.
+- Every edit to `## Acceptance criteria` was made with the owner's authorisation. The
+  remaining manual checks are AC6, which needs Safari, and AC21, which needs a screen
+  reader.
+
+### 2026-09-11 — e2e tests must not assume how many devices a browser reports
+- Twice now a new e2e test has failed in CI for the same reason: how many devices a browser
+  invents differs between them and from a developer machine. Chromium reports several
+  microphones and outputs; Firefox in CI reports one microphone and no outputs, so the menu
+  holds a single selectable row. A test that hovered the second row timed out there.
+- Tests in `playwright/audio-menu.spec.ts` now assert only what holds at any device count.
+  Where a fixed device list is what makes the check meaningful, it belongs in a story.
+
+## PRs
+
+- #4254 — draft, one commit per slice — AC1–AC27 (AC6, AC21, AC24 manual by the reviewer;
+  AC26, AC27 on Chromium only)

FEATURES_SPEC/2026-09_Audio_Quick_Menu.notes.md

@@ -0,0 +1,75 @@
+# Audio quick menu — exploration notes
+
+Not load-bearing. Nothing here constrains the implementation; constraints live in the
+feature spec.
+
+## Findings from the spike
+
+- **The shared slider names itself after its tooltip.** `Slider` wraps its thumb in a
+  compound `Tooltip`, which sets `aria-labelledby` on the thumb and so overrides the
+  `label` prop's `aria-label`. A screen reader announced the volume control as "50%".
+  Worked around at the call site by putting the control's name into the tooltip text.
+  The same defect exists in Settings → Audio today and would be better fixed in
+  `Slider` itself.
+- **Arrow keys inside the menu.** The radix menu treats arrow keys as navigation
+  between items, so a slider placed inside it never receives them. The slider row stops
+  propagation for arrow/Home/End. Without this the slider is mouse-only, which would
+  have failed AC20 silently.
+- **jsdom gaps.** The radix slider needs `ResizeObserver` and the meter needs
+  `AudioContext`; neither exists in jsdom, so both are stubbed per test file rather
+  than globally.
+- **Snapshot churn.** `LobbyView` and `InCallView` snapshots changed because the mic
+  button is now wrapped in the chevron container in cases that previously rendered a
+  bare button. Reviewed before updating; the change is the intended one.
+
+## Findings from design review
+
+- **An invented design token fails silently.** The meter's bars were written with
+  `--cpd-radius-pill-effective`; the token is `--cpd-radius-pill-effect`. An unknown
+  custom property makes the whole `border-radius` declaration invalid, so the bars
+  rendered square with no error anywhere. Worth grepping for the token name before
+  using one.
+- **A sticky child paints over the menu's border.** `FloatingMenu` draws its border as
+  an `outline` inset by one border width rather than as a real border. A
+  `position: sticky` child is positioned, so it paints above that outline and its
+  opaque background covered the border at the left and right edges. Fixed with a
+  matching inline margin on the sticky row.
+- **The bar geometry has two coupled knobs.** The bars share the row, so their width
+  is whatever the gaps leave over: raising the gap thins them and raising the count
+  thins them too. Moving both at once cancels out, which cost two review rounds.
+  Across the inset row (~248px at the menu's 340px maximum):
+
+  | bars | gap | bar width | bar:gap |
+  | ---- | --- | --------- | ------- |
+  | 20   | 8px | 4.8px     | 0.60    |
+  | 18   | 8px | 6.2px     | 0.78    |
+  | 17   | 8px | 7.1px     | 0.88    |
+  | 16   | 8px | 8.0px     | 1.00    |
+
+  The design sits near 0.8, hence 18 bars at an 8px gap.
+
+- **The bars line up with the label column, not the menu edge.** A menu item keeps a
+  `4x` margin after its label plus a `2x` column reserved for the chevron, on top of
+  the menu's own `4x` padding, so the meter's inline-end inset is `2 * 4x + 2x`.
+
+## Still open with design
+
+- The mockup marks the active device with a radio circle; the menu marks it with a
+  device icon and a checkmark, which is the existing pattern shared with the camera
+  chevron. Changing it would either change the camera menu too or make the two
+  inconsistent. Left as-is pending design sign-off.
+
+## Not done
+
+- Storybook interaction tests were not run; that project drives a real browser.
+  `AudioLevelMeter.stories.tsx` covers the five meter states for visual review.
+- Sticky positioning, the focus border and the bar geometry are all unverified by
+  tests: jsdom has no layout. The tests assert the DOM structure that makes them
+  possible, and the rest was checked by eye in a browser.
+- No measurement of what the meter's second capture costs while a call is running.
+  This is the main thing left before sign-off, and it is the decision most likely to
+  be revisited: if the cost is material, D1 gets narrower.
+- `oxfmt` covers markdown, and `AGENTS.md`, `_TEMPLATE.product.md` and the product
+  spec do not match its style, so `pnpm format:check` fails on them. Left alone: the
+  product spec is not editable after `draft` and the other two are process documents.
+  Either format them in a separate commit or exclude the folder from `oxfmt`.

FEATURES_SPEC/2026-09_Audio_Quick_Menu.product.md

@@ -0,0 +1,100 @@
+# Feature Specification: Audio quick menu
+
+**Feature Branch**: `[not yet created]`
+**Created**: 2026-09-09
+**Feature Spec**: `2026-09_Audio_Quick_Menu.md`  <!-- status lives in the feature spec's frontmatter, not here -->
+**Owner**: fkwp
+**Source**: this file
+**Input**: User description: "The chevron next to the mic button only offers microphone selection ('Mic Source'). Extend it into a combined audio quick-menu that also lets the user pick the speaker/output. Microphone check: the live, input-level meter that visibly reacts to the user's voice — so they immediately see the mic is active. For now this is web/desktop only (mobile is another story). Stretch: validate if it's possible to also place the sound effects volume in that new chevron menu."
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Choose where the call is heard, without leaving the call (Priority: P1)
+
+A participant realises the call is coming out of the laptop speakers instead of their headset. They open the chevron next to the microphone button, see a speaker section alongside the microphone section, pick their headset, and hear the difference immediately — the call view never goes away and the menu stays open so they can confirm the choice.
+
+**Why this priority**: This is the change that removes a full detour through the settings dialog during a live call, and it is the reason the menu is being reshaped at all. It is valuable on its own, with no dependency on the level meter or the volume slider.
+
+**Independent Test**: With two or more audio outputs attached, join a call, open the microphone chevron, and switch output. Audio follows the choice, and the same choice is visible in settings.
+
+**Acceptance Scenarios**:
+
+1. **Given** a participant in a call with two or more audio outputs available, **When** they open the microphone chevron, **Then** the menu shows a microphone section and a speaker section under one "Audio controls" heading, each marking the active device.
+2. **Given** the menu is open, **When** the participant selects a different speaker, **Then** call audio moves to that device, the row is marked active, and the menu stays open.
+3. **Given** the participant switched output from the menu, **When** they open settings, **Then** settings shows the same output as the active one.
+4. **Given** a browser that does not permit choosing an audio output, or a machine with exactly one output, **When** the participant opens the menu, **Then** the speaker section still shows which output is in use, presented as information rather than a choice.
+
+---
+
+### User Story 2 - Confirm the microphone is picking me up (Priority: P2)
+
+Before speaking — or after being told "we can't hear you" — a participant opens the same menu and speaks. A level indicator next to the microphone section moves with their voice, so they can tell within a second whether the selected microphone is live, and can try another one in the same menu if it is not.
+
+**Why this priority**: It answers the single most common audio complaint, but the menu is useful without it, and it carries the largest open design and privacy questions.
+
+**Independent Test**: Open the menu, speak, and watch the indicator move; select a different microphone in the same menu and confirm the indicator follows it.
+
+**Acceptance Scenarios**:
+
+1. **Given** the menu is open and the participant is unmuted, **When** they speak, **Then** the indicator visibly rises and falls with their voice.
+2. **Given** the menu is open and the participant is muted, **When** they speak, **Then** the indicator still rises and falls, so they can verify the microphone before unmuting.
+3. **Given** the indicator is live, **When** the participant closes the menu, **Then** the indicator stops capturing from the microphone.
+4. **Given** the menu is open, **When** the participant selects a different microphone, **Then** the indicator follows the newly selected microphone and the menu stays open.
+5. **Given** the selected microphone produces no signal, **When** the participant speaks, **Then** the indicator rests in an idle state rather than showing an error.
+
+---
+
+### User Story 3 - Adjust sound-effect volume without leaving the call (Priority: P3)
+
+Join and leave chimes and reaction sounds are too loud during a call. The participant opens the audio menu and moves a sound-effects slider until the next chime sits where they want it.
+
+**Why this priority**: A convenience placement of an existing setting. It is the smallest slice, it can be dropped without touching the other two, and the value it adds is discoverability rather than new capability.
+
+**Independent Test**: Move the slider in the menu, trigger a sound effect, and confirm both the audible change and that settings shows the new value.
+
+**Acceptance Scenarios**:
+
+1. **Given** the menu is open, **When** the participant moves the sound-effects slider, **Then** the next sound effect plays at the new level.
+2. **Given** the participant changed the level in the menu, **When** they open settings, **Then** the settings slider shows the same level, and changing it there is reflected back in the menu.
+
+---
+
+### Edge Cases
+
+- The menu is opened while muted: the operating system's "microphone in use" indicator turns on even though the participant is muted. No disclosure in the menu is required — that indicator is expected to behave the same whether the participant is muted or not, and mute state and microphone sampling are independent of one another.
+- The active microphone or speaker is unplugged while the menu is open — the menu must settle on a device that exists rather than showing a stale selection.
+- No microphone is present at all: the menu says so where the level indicator would be. An indicator at rest is what a working but silent microphone shows, so the two must not look alike.
+- Microphone permission has not been granted yet — most likely when the menu is opened in the lobby before joining.
+- Another application or browser tab holds the microphone exclusively, so the level indicator receives no signal even though the device is fine. Rare on current operating systems, which share the microphone between applications; where it does happen, the indicator shows a greyed-out state.
+- Sound-effects volume is set to zero: effects are silent but the rest of the call audio is unaffected.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The audio quick menu MUST be opened from the chevron next to the microphone button and MUST present its controls under a single "Audio controls" heading.
+- **FR-002**: The menu MUST list the available microphones, mark the active one, and switch input immediately on selection while staying open.
+- **FR-003**: The menu MUST list the available audio outputs, mark the active one, and switch output immediately on selection while staying open.
+- **FR-004**: The microphone, speaker and sound-effects controls MUST be visually separated from one another within the menu.
+- **FR-005**: When the audio output cannot be changed — the browser does not permit choosing an output, or only one output exists — the menu MUST still show the active output as a non-selectable row.
+- **FR-006**: The output selected in the menu and the output selected in settings MUST be one and the same selection; a change in either MUST be reflected in the other.
+- **FR-007**: The menu MUST show a live indicator of the sound level at the selected microphone.
+- **FR-008**: The indicator MUST respond while the microphone is muted as well as while it is unmuted.
+- **FR-009**: The indicator MUST become live when the menu opens and MUST stop capturing from the microphone when the menu closes.
+- **FR-010**: Selecting a different microphone MUST re-point the indicator at that microphone without closing the menu.
+- **FR-011**: When the selected microphone produces no signal, the indicator MUST show an idle state rather than an error.
+- **FR-012**: Users MUST be able to change the sound-effects volume from the menu, taking effect from the next sound effect onward.
+- **FR-013**: Sound-effects volume MUST remain adjustable in settings, and both controls MUST read and write the same stored value.
+- **FR-014**: The menu MUST be available before joining and during a call on web and desktop, and before joining on every platform — the pre-join chevron already exists everywhere and MUST show the full menu.
+- **FR-015**: During a call on mobile, the microphone chevron MUST behave as it does today; the menu is not introduced there.
+- **FR-016**: Every control in the menu MUST be reachable and operable by keyboard alone.
+- **FR-017**: The level indicator MUST be focusable, and while it holds focus it MUST announce its current state to a screen reader.
+- **FR-018**: When microphone permission has been denied, the menu MUST show a hint saying so, in place of a silent idle indicator.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: Changing the audio output never requires opening a dialog that covers the call: the other participants remain visible from the moment the participant reaches for the control until the new output is in use.
+- **SC-002**: With the menu open, speech produces visible movement in the level indicator while the person is still speaking. No millisecond target: perceived latency is explicitly not critical for this indicator.
+- **SC-003**: Every control in the menu, including the sound-effects slider, is reachable and operable with the keyboard alone, verified on the supported desktop browsers.

FEATURES_SPEC/AGENTS.md

@@ -0,0 +1,415 @@
+# FEATURE_SPEC — Agent Instructions
+
+This folder holds **feature specs distilled from experiments**. A spec is the durable
+artifact of an exploration; the exploration branch is not. Each spec must contain
+enough information for an agent to produce mergeable PRs against a *current* `main`
+without access to the original branch.
+
+## What this folder is not
+
+- Not a design-doc archive. Specs that are not intended to be implemented do not
+  belong here.
+- Not a place for narrative. Prose that does not constrain the implementation or its
+  verification should be cut.
+- Not a substitute for the PR description. The spec explains *why* and *what must be
+  true*; the PR explains *this diff*.
+
+## File naming
+
+`YYYY-MM_Snake_Case_Title.md` — e.g. `2026-09_Raise_Hand_Improvements.md`
+
+The filename is immutable once committed. Renames break links from PRs, issues and
+the drift log. If scope changes fundamentally, write a new spec and set
+`supersedes:` / `superseded_by:`.
+
+A sidecar `YYYY-MM_Snake_Case_Title.product.md` holds the product spec — user stories,
+functional requirements, success criteria. Copy `_TEMPLATE.product.md`. Product owns
+it; see "Brainstorming: the product spec".
+
+An optional sidecar `YYYY-MM_Snake_Case_Title.notes.md` holds lessons learned,
+narrative, dead-end logs and anything else that is worth keeping but does not
+constrain the implementation. Rules:
+
+- The sidecar is **never load-bearing**. Agents do not read it to derive
+  implementation, and nothing in it may contradict or extend the spec. If a note
+  constrains the work, it belongs in `## Decisions`, `## Rejected alternatives` or
+  `## Measurements` instead.
+- Agents may append to it (an observation from a drift check, a wrong turn during
+  implementation) and must never rewrite or delete existing content.
+- An agent that is `blocked` may read the sidecar to draft an open question, but
+  quotes what it found rather than acting on it.
+- No sidecar is required. An empty one is worse than none.
+
+## Style: facts only
+
+Applies to the spec file only. The product spec is prose by design and the notes
+sidecar is unconstrained. The spec is re-read on every regeneration, where prose costs context
+and dilutes the contract, so:
+
+- Bullets, not paragraphs. Declarative present tense. No motivation, no background,
+  no summary of what the code currently does beyond locating the change.
+- Name things instead of describing them — a path, a symbol, an event type, a command,
+  an event id. A reference is shorter and more precise than a sentence about it. Which
+  kind of reference is allowed depends on the section; see "Reference durability".
+- One line per decision plus at most one sentence of rationale. If the rationale needs
+  more, the extra goes in the sidecar.
+- No judgement adjectives (clean, elegant, proper, obviously) and no hedging (should
+  probably, might be nice). Either it is a constraint or it is not in the spec.
+- `## Problem` is at most five bullets.
+- Target under 200 lines for the whole spec; over 300 lines, split the feature or move
+  material to the sidecar.
+
+The test for any line: does it constrain the implementation, constrain its
+verification, or record a measured fact? If not, delete it or move it to the sidecar.
+
+## Reference durability
+
+The spec must stay implementable against a `main` nobody has seen yet, so which
+references are allowed depends on how fast they rot. Most to least durable:
+
+1. Protocol identifiers — `m.reaction`, `m.call.member`, `m.relates_to`, a reaction
+   key. MSC-bound; effectively permanent.
+2. Observable behaviour. Permanent.
+3. Concept names — membership, participation, session.
+4. Test names. Survive file moves and renames, because the test moves with the code.
+5. Exported symbols. Survive refactors sometimes.
+6. File paths. Rot fast.
+7. Line numbers. Never.
+
+Per section:
+
+- `## Problem`, `## Measurements`, `## Slicing plan`, `## Drift log` — any reference,
+  paths and internal symbols included. These describe the codebase **as of `base`**. A
+  reference going stale here is a finding for the drift check, not a defect, and
+  removing the concrete references would leave the drift check with nothing to verify.
+- `## Decisions`, `## Acceptance criteria` — levels 1 to 4 only. No file paths, no
+  internal symbols. This is the part that has to hold against a future `main`.
+- An acceptance criterion that is not user-observable is tagged `[internal]` and
+  anchored by **its test name**, not by the symbol under test. The test name moves with
+  a refactor; the symbol does not.
+
+`[internal]` ACs are legitimate and expected: an invariant that no current consumer can
+observe is exactly what protects the consumer that does not exist yet. Tagging them
+keeps visible which ACs defend a product requirement and which defend a code
+invariant.
+
+## Required frontmatter
+
+```yaml
+---
+status: draft            # see state machine below
+blocked_from: null       # state to return to when leaving `blocked`
+title: Raise hand improvements
+owner: <human handle>    # a human, always
+signoff:                 # join condition for leaving exploration.signoff
+  eng: pending
+  design: pending
+  product: pending
+experiment_ref: <branch name or commit sha of the spike, if any>
+base: <sha of main the spec was validated against>
+repos: [matrix-js-sdk, element-call]    # in dependency order
+specs: [MSC4143]         # protocol documents touched, if any
+supersedes: []
+superseded_by: null
+---
+```
+
+`base` is mandatory and is what makes drift detectable. `owner` is a human even when
+every section was drafted by an agent.
+
+## Brainstorming: the product spec
+
+The usual entry point is a human handing an agent a one-line feature idea. The output
+of that session is `<stem>.product.md`, not code and not a feature spec. Copy
+`_TEMPLATE.product.md` and fill it.
+
+Ownership: an agent may create and fill this file during `brainstorm`. From `draft`
+onwards **product owns it and agents do not edit it** — not to fix wording, not to
+resolve a marker, not to reconcile it with the code. Agents raise mismatches in the
+feature spec's `## Open questions`.
+
+If product's source of truth lives outside the repo (a tracker, a design doc), put its
+URL in the header `**Source**:` line and keep the requirement text and ids in the repo
+anyway. The ids are what the feature spec references; a link alone cannot be traced.
+
+Agent behaviour during the session:
+
+- **Ask, do not assume.** An unanswered question is recorded as
+  `[NEEDS CLARIFICATION: <the question>]`, inline where the answer would go. Filling a
+  gap with a plausible guess is the main failure mode of this state — the marker is a
+  deliverable, not a defect.
+- Ask in one round of at most five questions, ordered by how much the answer changes
+  the shape of the feature. Do not interview.
+- **No implementation in the product spec.** No file paths, symbols, libraries, event
+  types, API shapes or framework names. If a requirement cannot be stated without them,
+  it is not a product requirement.
+- Every user story must be independently deployable and demonstrable on its own. A
+  story that only makes sense once another story ships is not a story; merge it.
+- More than four priority levels means more than one feature. Split before `draft`.
+- Never invent an SC number. Ask for the target, or mark it
+  `[NEEDS CLARIFICATION]`.
+
+For protocol and infrastructure work, success criteria may be expressed as observable
+client behaviour or a wire-level invariant ("a client joining mid-session converges
+within one sync"), but still never as a code path or an internal API.
+
+`FR-###` and `SC-###` ids are immutable once assigned. Product may revise the document
+at any time, including after `in_production`, but a changed requirement gets a **new
+id** and the old one is marked superseded — never edited in place. Renumbering silently
+breaks every AC that references it, and there is no way to detect that afterwards.
+
+A new or changed FR after `implement` does not amend the current spec's scope. It is
+either a new feature spec or the next iteration; the mapping table simply shows an
+unmapped FR, which is the intended signal.
+
+## Traceability
+
+The product spec states intent; the feature spec states what must be true and how it is
+checked. They are kept in sync by ids, not by duplication.
+
+- Every `FR-###` maps to at least one acceptance criterion. Tag the AC with its
+  origin: `AC2 [FR-003] — <observable behaviour>`.
+- Every `SC-###` maps to an entry in `## Measurements` with a method. An SC with no
+  measurement blocks `exploration.signoff`.
+- Every user story maps to at least one slice. **Slice order follows story priority**
+  (P1 first) unless a technical dependency overrides it, and the override is recorded
+  in the slicing plan with its reason.
+- An AC with no `FR` origin is allowed and expected — implementation-level invariants
+  have no counterpart in the product spec. The converse is not: an unmapped FR is an
+  incomplete spec.
+- Agents do not resolve a mismatch between the two. The product spec wins on intent,
+  the feature spec wins on verification; a genuine contradiction is `blocked`.
+
+## Status state machine
+
+Transitions are explicit; an agent may perform only the ones marked (agent).
+
+```
+brainstorm ─► draft ─► exploration ─► implement ─► qa ─► in_production
+                           │              │        │
+                           └──────────────┴────────┴──► blocked ──► (blocked_from)
+                                                           │
+                                                           └──► abandoned
+```
+
+Exploration has sub-states, written dotted in `status`:
+
+```
+exploration.scoping ─► exploration.iterating ─► exploration.signoff
+        ▲                       │                      │
+        └───────────────────────┴──────────────────────┘
+```
+
+- `brainstorm` → `draft`: human. Requires `<stem>.product.md` to exist with at least one
+  P1 story carrying acceptance scenarios, every FR and SC id assigned, and every
+  remaining `[NEEDS CLARIFICATION]` copied into the feature spec's `## Open questions`.
+- `draft` → `exploration.scoping`: human. Requires `## Problem` and `## Out of scope`.
+  Scoping before the branch exists is what keeps exploration from becoming the
+  long-lived branch this folder replaces.
+- `exploration.scoping` → `.iterating`: human. `experiment_ref` must name the branch.
+- `.iterating` → `.signoff`: human. Requires `## Decisions`, `## Acceptance criteria`,
+  `## Rejected alternatives` and `## Measurements` to be complete, no
+  `[NEEDS CLARIFICATION]` left in the product spec, and full traceability (below).
+- `.signoff` → `implement`: **only when all three sign-offs in `signoff:` are `ok`.**
+  This is a join, not a sequence — a single reviewer cannot advance it. On entering
+  `implement`, the exploration branch stops being a base: it is reference material,
+  and implementation branches off current `main` (see "Turning a spec into PRs").
+- `.signoff` → `.iterating`: human, on any sign-off returning changes. Reset the
+  rejecting role to `pending`; leave the others as they are.
+- `implement` → `qa`: (agent) when every acceptance criterion is covered, as recorded
+  in `## PRs`, and the feature flag is enabled in the QA environment.
+- `qa` → `in_production`: human. The flag is on by default in production.
+- `qa` → `implement`: (agent) when a QA finding needs code. See "QA feedback".
+- any active state → `blocked`: (agent) when drift or an unresolved question prevents
+  progress. Requires a drift-log entry and `blocked_from: <state>`. Do not guess and
+  continue. Leaving `blocked` returns to `blocked_from`, never to a fixed state.
+- any state → `abandoned`: human only.
+
+`in_production` is terminal. A production regression does not reopen the spec: it
+either is an ordinary bug fix with no spec, or it is a new spec. The acceptance
+criteria remain as the regression contract (see "QA feedback").
+
+## QA feedback
+
+The point of the `qa` state is not to record that testing happened. It is to make the
+spec a better regeneration source than it was before implementation. So:
+
+- Every reproduced QA finding becomes **either** a new acceptance criterion **or** a
+  new entry in `## Rejected alternatives`. Never a prose note, never only a bug
+  tracker link.
+- (agent) may **append** ACs during `qa`, with provenance:
+  `AC7 [qa: <issue ref>] — <observable behaviour>` plus its check. Appending is
+  allowed; rewriting or reordering existing ACs is not.
+- A finding that invalidates a decision does not become an AC. It sets `blocked` — a
+  decision is human-owned in every state.
+- A finding that is out of scope goes to `## Out of scope` with its issue ref, so the
+  next regeneration does not treat it as a gap.
+
+This also applies after `in_production`: a production bug that reveals a missing AC is
+appended with `[prod: <ref>]` provenance without any state change.
+
+## Required sections
+
+Order matters — agents read top-down and the first three sections are the contract.
+
+1. **`## Problem`** — up to five bullets. What breaks today, for whom, observably,
+   with the file or symbol where it breaks.
+2. **`## Decisions`** — the choices the exploration settled, each with a one-line
+   rationale. **Human-owned. An agent must never add, remove or reword a decision.**
+   If a decision is missing, set `blocked` and ask.
+3. **`## Acceptance criteria`** — the load-bearing section. Each item must be
+   mechanically checkable and name its check:
+   - `AC1 [FR-002] — <observable behaviour>` / `check: yarn vitest run src/reactions/ReactionsReader.test.tsx -t "backfill"`
+   - `AC2 [FR-002] — <observable behaviour>` / `check: manual, <exact steps>`
+   - `AC3 [internal] — <invariant>` / `check: yarn vitest run <file> -t "<test name>"`
+   An acceptance criterion without a check is a wish; reject the spec (`blocked`).
+4. **`## Rejected alternatives`** — what the experiment tried and why it failed,
+   including measurements. This exists so regeneration does not re-walk dead ends. If
+   this section is empty for a spec with an `experiment_ref`, the spec is incomplete.
+5. **`## Measurements`** — numbers from the experiment with the method used to obtain
+   them (command, hardware, load profile). Numbers without a method are not usable as
+   regression baselines and must be marked `unverified`. A baseline states its direction: a
+   count that unrelated work grows — tests passing, test files — is a floor (`≥ n`); a
+   cost — latency, CPU, bundle size — is a ceiling (`≤ n`). An exact count is stale as
+   soon as `main` moves and is not a drift finding.
+6. **`## Out of scope`** — explicit non-goals, so agents stop expanding the diff.
+7. **`## Slicing plan`** — ordered, independently mergeable PRs (see below).
+8. **`## Drift log`** — append-only, agent-written.
+9. **`## PRs`** — append-only list of `#<n> — <state> — <ACs covered>`.
+
+Optional: `## Open questions` (blocks `exploration.signoff`), `## Migration / compat` (mandatory
+whenever wire format, event schema, or a published API changes).
+
+## Turning a spec into PRs
+
+Run these steps in order. Do not skip step 2.
+
+1. **Fetch and pin.** `git fetch origin` and record `origin/main`'s sha as `head`.
+   Never start from the exploration branch, and never rebase it — the branch is
+   reference material, not a base.
+2. **Drift check** against `base..head`:
+   - Do all files, symbols and modules named in the spec still exist?
+   - Have the invariants in `## Decisions` been contradicted by changes in main?
+   - Do the commands in `## Acceptance criteria` still run?
+   Write the result as a drift-log entry. On a contradicted decision: set `blocked`,
+   do not implement.
+3. **Re-derive the slicing plan** if drift changed it. Each slice must:
+   - build and pass CI on its own,
+   - be reviewable in one sitting (target < 400 changed lines, hard stop at 800 —
+     split further rather than exceeding it),
+   - map to at least one acceptance criterion, and
+   - land behind a flag or be inert if it is not the last slice of a user-visible
+     change.
+4. **Implement one slice at a time**, branch `spec/<spec-slug>/<n>-<short>` off the
+   pinned `head`. Tests for the slice's ACs go in the same PR as the code. A PR merges
+   only when every check of every AC it lists passes on that PR: automated checks in
+   CI, manual checks performed by a human reviewer with the result recorded in the PR
+   description. An AC is *covered* once such a PR has merged.
+5. **Open the PR** linking the spec path and listing the ACs it covers. Update
+   `## PRs` and `status`.
+6. **Do not touch merged or reviewed slices.** See the regeneration rule.
+
+## The regeneration rule
+
+Regeneration from spec is only allowed **before a human has reviewed the PR**.
+
+Once review has started, the PR is a shared artifact: rebase, fix forward, push
+incremental commits. Regenerating discards the reviewer's context and silently
+invalidates their approvals. If regeneration is unavoidable after review, close the
+old PR with an explanation and open a new one — never force-push a fresh generation
+over a reviewed branch.
+
+## Cross-repo and protocol work
+
+When `repos` has more than one entry, PRs are opened in `repos` order and each PR
+body states which upstream PR it depends on. Merging out of order is a spec
+violation, not an optimisation.
+
+When `specs` is non-empty:
+- the implementation PR references the section of the MSC it implements,
+- unmerged MSCs require the implementation to be feature-flagged and documented as
+  unstable (unstable prefixes, not stable identifiers), and
+- any deviation from the MSC text is recorded in `## Drift log`, not silently
+  resolved in favour of the code.
+
+## Drift-log format
+
+Append-only, newest last:
+
+```
+### 2026-09-14 — drift check (base 4f2a1c9 → head 9b17e02)
+- `ReactionsReader.getLastReactionEvent` now takes a `CallMembership` instead of an
+  event id → AC2 and AC3 check commands still valid, slice 3 needs rework
+- BLOCKING: decision D2 assumes a membership event change may keep a hand raised; main
+  now clears all reaction relations on membership replacement. Needs owner decision.
+```
+
+Drift entries are never rewritten or deleted, including entries that were later
+resolved. The log is the record of why the implementation diverged from the
+exploration.
+
+## Hard rules
+
+- Never fill a `[NEEDS CLARIFICATION]` marker with a guess, in any state.
+- Never put file paths, symbols or library names in the product spec.
+- Never reference a file path or an internal symbol in `## Decisions` or
+  `## Acceptance criteria`. Behaviour, protocol identifiers, concepts and test names
+  only.
+- Never edit `<stem>.product.md` after `draft`, and never renumber an FR or SC id.
+- Never add a line that does not constrain the implementation, constrain its
+  verification, or record a measured fact. It goes in the sidecar or nowhere.
+- Never modify `## Decisions`, `## Problem`, or `## Acceptance criteria`. These are
+  the human contract. Propose changes in `## Open questions` and set `blocked`.
+- Never invent measurements or acceptance checks. Absent is better than plausible.
+- Never widen scope past `## Out of scope`, even when the fix looks trivial.
+- Never open a PR while `status` is `draft`, any `exploration.*`, or `blocked`.
+- Never delete a spec file. Terminal states are `in_production` or `abandoned`.
+- If the spec and current `main` disagree about how the system works, **main wins as
+  description, the spec wins as intent** — record the difference and stop.
+
+## Spec template
+
+```markdown
+---
+status: draft
+blocked_from: null
+title:
+owner:
+signoff:
+  eng: pending
+  design: pending
+  product: pending
+experiment_ref:
+base:
+repos: []
+specs: []
+supersedes: []
+superseded_by: null
+---
+
+## Problem
+
+## Decisions
+- D1 — <decision> — <why>
+
+## Acceptance criteria
+- AC1 [FR-###] — <observable behaviour>
+  - check: <command or exact manual steps>
+- AC2 [internal] — <invariant>
+  - check: <command, anchored by test name>
+
+## Rejected alternatives
+- <approach> — <why it failed> — <evidence>
+
+## Measurements
+- <metric>: <value> (method: <command / setup>)
+
+## Out of scope
+
+## Slicing plan
+1. <slice> — covers AC1 — depends on: none
+
+## Drift log
+
+## PRs
+```

FEATURES_SPEC/_TEMPLATE.product.md

@@ -0,0 +1,117 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`
+**Created**: [DATE]
+**Feature Spec**: `[YYYY-MM_Title.md]`  <!-- status lives in the feature spec's frontmatter, not here -->
+**Owner**: [product handle]
+**Source**: [URL of the tracker/doc this mirrors, or "this file"]
+**Input**: User description: "$ARGUMENTS"
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+*Example of marking unclear requirements:*
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Key Entities *(include if feature involves data)*
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]

README.md

@@ -36,8 +36,9 @@ You can find the latest development version continuously deployed to
 ✅ **Decentralized & Federated** – No central authority; works across Matrix
 homeservers.  
 ✅ **End-to-End Encrypted** – Secure and private calls.  
-✅ **Standalone & Widget Mode** – Use as an independent app or embed in Matrix
-clients.  
+✅ **Standalone, Widget & Component Mode** – Use as an independent app, embed
+in Matrix clients as a widget, or (experimentally) mount it as a React component
+inside your own application.  
 ✅ **WebRTC-based** – No additional software required.  
 ✅ **Scalable with LiveKit** – Supports large meetings via SFU
 ([MSC4195: MatrixRTC using LiveKit backend](https://github.com/hughns/matrix-spec-proposals/blob/hughns/matrixrtc-livekit/proposals/4195-matrixrtc-livekit.md)).  
@@ -90,7 +91,9 @@ and voice calls within Matrix rooms.
 
 Element Call offers two packaging options: one for standalone or widget
 deployment, and another for seamless widget-based integration into messenger
-apps. Below is an overview of each option.
+apps. A third, experimental option builds it as a React component library for
+applications that want to render a call inside their own page rather than in an
+iframe. Below is an overview of each option.
 
 **Full Package** – Supports both **Standalone** and **Widget** mode. It is
 hosted as a static web page and can be accessed via a URL when used as a widget.
@@ -107,6 +110,11 @@ recommended method for embedding Element Call.
   <img src="./docs/embedded_package.drawio.png" alt="Element Call Embedded Package">
 </p>
 
+**Component Package (experimental)** – A library build of Element Call as a
+React component, consumed as a dependency by a host application that already
+has a Matrix client. See
+[Element Call as a component](#element-call-as-a-component-experimental) below.
+
 For more details on the packages, see the
 [Embedded vs. Standalone Guide](./docs/embedded_standalone.md).
 
@@ -213,6 +221,94 @@ See also:
 
 - [Developing with linked packages](./docs/linking.md)
 
+#### Element Call as a component (experimental)
+
+Element Call can also be embedded directly into another React application
+rather than being loaded in an iframe as a widget. `pnpm build:component`
+builds it as a library into `component/dist` (the bundle, its stylesheet and
+type declarations), and
+
+```sh
+pnpm dev:component
+```
+
+serves a harness on port 3001 that stands in for such an application: it signs
+in twice against the development backend and shows two calls side by side, in
+resizable boxes, with page furniture of its own around them. Use it to see how
+Element Call behaves when it does not own the page — the size it is given,
+whether it stays inside its container, and what it says to its host, which is
+logged along the bottom. The harness is served with the same development
+certificate as the app, so unless the development CA is trusted, the browser
+needs a certificate exception for `https://localhost:3001` as well (see the
+note under [Backend](#backend)). It reads the same `public/config.json` as
+`pnpm dev` if one exists, and runs with Element Call's defaults otherwise.
+
+The call lays itself out for the size of the element it is mounted in, not the
+window: a host that shrinks the container to a corner of its page gets the
+picture-in-picture layout, just as a host that shrank the whole iframe used to.
+The breakpoints in the stylesheets the component uses are
+`@container element-call` queries against its root element for the same reason;
+for the standalone app the root is the page, so they mean what the media queries
+they replaced did. (The standalone-only views, such as the home and login pages,
+still use plain media queries, since the component never shows them.)
+
+The component's stylesheet is confined to the element it is mounted in: the
+build rewrites every selector so that it matches only Element Call's root or
+what is inside it, with `html`, `body` and `:root` standing for that root (see
+`component/build/scopeStylesToRoot.ts`). A host's own page keeps its styles,
+and Element Call brings its own fonts and design tokens along.
+
+The component speaks every language the app does. English is bundled in; the
+other locales are split into chunks the host's bundler loads the first time
+they are needed. It starts in the browser's language, and follows the host's
+own language setting through the `language` prop (`supportedLanguages` lists
+the tags it accepts, and anything else falls back to its base language or to
+English). The `theme` prop works the same way and takes the same values as the
+widget's `theme` URL parameter: `light`, `dark`, `light-high-contrast` or
+`dark-high-contrast`. Both can change while a call is running without
+disturbing it.
+
+A host must call and await `initializeElementCall(config)` once before
+rendering the component: it loads the `Intl` polyfills, applies the
+deployment-wide `config.json`-style configuration and sets up translations.
+The component itself takes the host's `client` and the `roomId` to call in, an
+`intent` saying what the user asked for (which decides whether to show the
+lobby, ring, and so on), an optional `config` overriding what the intent
+implies, and an optional `hostBridge` through which Element Call tells the host
+that the user has joined or hung up, that it wants to stay on screen, and so
+on. The host makes its own requests (`join`, `hangUp`, `setDeviceMute`) through
+the handle exposed on `ref`. The full API is documented in the type declarations
+(`component/index.tsx` and `component/host.ts`).
+
+A few things differ from the widget on purpose: the component draws a solid
+background rather than a gradient unless told otherwise, never offers to edit
+the user's profile (the account is the host's), scopes its keyboard shortcuts to
+its own root element so that several instances can share a page, and only shows
+its own post-call and error screens when the host has not supplied a `close()`
+callback; with one, it asks the host to unmount it instead. The
+[global JS controls](./docs/controls.md) on `window` are unchanged and remain
+page-wide, so with several instances on one page they apply to all of them.
+
+The package is not published yet. A host installs it as a git dependency on the
+`component` directory of this repository,
+
+```json
+"@element-hq/element-call-component": "github:element-hq/element-call#main&path:/component"
+```
+
+whose `prepare` script runs the build on install. That build needs pnpm (via
+Corepack) on the host's machine, runs a full `pnpm install` of this repository
+and is memory-hungry, since it inherits the `--max-old-space-size` setting of
+the app build; the host's pnpm also has to allow it to run at all
+(`allowBuilds` in its `pnpm-workspace.yaml`). Note that `component/` is a pnpm
+project of its own for this reason, so pnpm commands run from inside that
+directory target it rather than the repository; run them from the repository
+root. The host imports the component from
+`@element-hq/element-call-component` and the stylesheet from
+`@element-hq/element-call-component/style.css`, and has to provide `react`,
+`react-dom`, `matrix-js-sdk` and `livekit-client` itself, since the bundle leaves
+them external.
+
 ### Backend
 
 A docker compose file `docker-compose-dev.yml` is provided to start the
@@ -274,7 +370,10 @@ running Playwright by following
 
 However the Playwright tests are run, an element-call instance must be running
 on https://localhost:3000 (this is configured in `playwright.config.ts`) - this
-is what will be tested.
+is what will be tested. The tests under `playwright/component` instead drive
+the component harness (`pnpm dev:component`) on https://localhost:3001, which
+Playwright starts as a second web server; it is always a Vite dev server, even
+when the app itself is served from Docker with `USE_DOCKER`.
 
 The local backend environment should be running for the test to work:
 `pnpm backend`
@@ -373,7 +472,7 @@ We do this so that we can reuse the labels between repositories.
 
 ## 📝 Copyright & License
 
-Copyright 2021-2025 New Vector Ltd
+Copyright 2021-2026 New Vector Ltd
 
 This software is dual-licensed by New Vector Ltd (Element). It can be used
 either:

component/ElementCall.module.css

@@ -0,0 +1,43 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+/* The container a host mounts us into. It fills whatever space the host gives
+it, and nothing we draw may leave it.
+
+That takes two separate things, which are easy to mistake for one. `isolation`
+gives us a stacking context, so nothing inside can be layered above the host's
+own interface. Containment makes us the containing block for `position: fixed`
+descendants, and clips what we paint to our own box: without it, the modal
+scrim and dialog — which are positioned `fixed` and centred, since in the app
+they are meant to cover the page — resolve against the viewport and appear in
+the middle of the host's window rather than in the middle of the call.
+
+The clipping cuts both ways: a menu near the edge of a small container is
+trimmed rather than overflowing into the host. That is the trade being a
+component rather than a page makes. */
+.root {
+  display: flex;
+  flex-direction: column;
+  inline-size: 100%;
+  block-size: 100%;
+  isolation: isolate;
+  contain: layout paint;
+  position: relative;
+  background-color: var(--cpd-color-bg-canvas-default);
+  color: var(--cpd-color-text-primary);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-tap-highlight-color: transparent;
+}
+
+/* Compound's overlay container, which holds tooltips and popovers, has to fill
+the container for the elements inside it to be positioned against it. The
+standalone page does the same for the container under `#root`. */
+.root > [data-overlay-container] {
+  position: relative;
+  block-size: 100%;
+}

component/build/scopeStylesToRoot.test.ts

@@ -0,0 +1,112 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { describe, expect, it } from "vitest";
+import postcss from "postcss";
+
+import { ROOT_SELECTOR, scopeStylesToRoot } from "./scopeStylesToRoot";
+
+const inRoot = `:where(${ROOT_SELECTOR}, ${ROOT_SELECTOR} *)`;
+const isRoot = `:where(${ROOT_SELECTOR})`;
+
+async function scope(css: string, file = "base.css"): Promise<string> {
+  const result = await postcss([scopeStylesToRoot()]).process(css, {
+    from: file,
+  });
+  return result.css;
+}
+
+describe("scopeStylesToRoot", () => {
+  it("makes the root stand in for the document", async () => {
+    expect(await scope("html { line-height: 1.15 }")).toBe(
+      `${isRoot} { line-height: 1.15 }`,
+    );
+    expect(await scope("body { margin: 0 }")).toBe(`${isRoot} { margin: 0 }`);
+    expect(await scope(":root { --a: 1 }")).toBe(`${isRoot} { --a: 1 }`);
+    expect(await scope("body.no-scroll-body { position: fixed }")).toBe(
+      `${isRoot}.no-scroll-body { position: fixed }`,
+    );
+    expect(await scope("body .x { color: red }")).toBe(
+      `${isRoot} .x { color: red }`,
+    );
+  });
+
+  it("collapses selectors that all became the root", async () => {
+    expect(await scope("html, body, input { font: inherit }")).toBe(
+      `${isRoot},input${inRoot} { font: inherit }`,
+    );
+  });
+
+  it("confines everything else to the root and what is inside it", async () => {
+    expect(await scope("h1 { margin: 0 }")).toBe(`h1${inRoot} { margin: 0 }`);
+    expect(await scope(".cpd-theme-dark { --a: 1 }")).toBe(
+      `.cpd-theme-dark${inRoot} { --a: 1 }`,
+    );
+    expect(await scope("* { box-sizing: border-box }")).toBe(
+      `*${inRoot} { box-sizing: border-box }`,
+    );
+    expect(await scope(".a > .b + .c { color: red }")).toBe(
+      `.a>.b+.c${inRoot} { color: red }`,
+    );
+  });
+
+  it("keeps pseudo-elements last", async () => {
+    expect(await scope("button::-moz-focus-inner { border: 0 }")).toBe(
+      `button${inRoot}::-moz-focus-inner { border: 0 }`,
+    );
+    expect(await scope(".a .b:hover::after { content: '' }")).toBe(
+      `.a .b:hover${inRoot}::after { content: '' }`,
+    );
+    expect(await scope("p:first-letter { color: red }")).toBe(
+      `p${inRoot}:first-letter { color: red }`,
+    );
+  });
+
+  it("leaves alone what already names the root", async () => {
+    const css = `${ROOT_SELECTOR}[data-platform="ios"] { --a: 1 }`;
+    expect(await scope(css)).toBe(css);
+  });
+
+  it("reaches into layers and media queries", async () => {
+    expect(
+      await scope(
+        "@layer normalize { h1 { margin: 0 } } @media (min-width: 1px) { p { margin: 0 } }",
+      ),
+    ).toBe(
+      `@layer normalize { h1${inRoot} { margin: 0 } } @media (min-width: 1px) { p${inRoot} { margin: 0 } }`,
+    );
+  });
+
+  it("does not touch keyframes or nested rules", async () => {
+    expect(
+      await scope("@keyframes spin { from { opacity: 0 } to { opacity: 1 } }"),
+    ).toBe("@keyframes spin { from { opacity: 0 } to { opacity: 1 } }");
+    expect(
+      await scope(
+        ".a { color: red; &:hover { color: blue } .b { color: green } }",
+      ),
+    ).toBe(
+      `.a${inRoot} { color: red; &:hover { color: blue } .b { color: green } }`,
+    );
+  });
+
+  it("only touches the bare selectors of a CSS module", async () => {
+    const file = "Settings.module.css";
+    expect(await scope("pre { font-size: 1px }", file)).toBe(
+      `pre${inRoot} { font-size: 1px }`,
+    );
+    expect(await scope(".modal pre { font-size: 1px }", file)).toBe(
+      `.modal pre${inRoot} { font-size: 1px }`,
+    );
+    expect(await scope(".box_abc12 { border: 0 }", file)).toBe(
+      ".box_abc12 { border: 0 }",
+    );
+    expect(await scope(".a .b_abc12:hover { border: 0 }", file)).toBe(
+      ".a .b_abc12:hover { border: 0 }",
+    );
+  });
+});

component/build/scopeStylesToRoot.ts

@@ -0,0 +1,161 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import {
+  type AtRule,
+  type Container,
+  type Document,
+  type Plugin,
+  type Rule,
+} from "postcss";
+import selectorParser, {
+  type Node,
+  type Pseudo,
+  type Selector,
+} from "postcss-selector-parser";
+
+/**
+ * How the stylesheets find Element Call's root element. The attribute is put
+ * there by `useTheme`, on the container the host gives the component.
+ */
+export const ROOT_SELECTOR = "[data-element-call-root]";
+
+// Both are `:where()`, which has no specificity of its own, so the rules keep
+// exactly the weight they had before being scoped and nothing in Element Call's
+// cascade changes — only where it applies.
+//
+// The root, or anything inside it. Appended to the element a rule is about,
+// rather than prepended to the whole selector, so that a rule about the root
+// itself (its theme class, say) still matches.
+const IN_ROOT = `:where(${ROOT_SELECTOR}, ${ROOT_SELECTOR} *)`;
+// The root itself, standing in for the document.
+const IS_ROOT = `:where(${ROOT_SELECTOR})`;
+
+/**
+ * Confines a stylesheet to Element Call's root element, for the build of
+ * Element Call as a component.
+ *
+ * As a page of its own, Element Call can style the document: normalize.css and
+ * Compound speak of `html`, `body` and bare elements, and the design tokens are
+ * declared on `:root`. As a component, all of that would land on the host's
+ * document too. This rewrites every selector so that it matches only the root
+ * or its descendants:
+ *
+ * - `html`, `body` and `:root` become the root element, which is what stands in
+ *   for the document inside a host.
+ * - Everything else keeps its selector and gains `:where([data-element-call-root],
+ *   [data-element-call-root] *)` on the element it styles.
+ * - Selectors that already name the root are left alone, as are keyframe
+ *   selectors and rules nested inside another rule, which are relative to it.
+ *
+ * CSS modules are scoped by their class names already, so only their selectors
+ * that would match by element alone — `pre` rather than `.pre` — are touched.
+ *
+ * The root's fonts and design tokens are still inherited by everything inside
+ * it, the way they were from `body` and `:root`, and `@font-face` declarations
+ * stay global, which they are by nature.
+ */
+export function scopeStylesToRoot(): Plugin {
+  return {
+    postcssPlugin: "element-call-scope-styles-to-root",
+    Once(root) {
+      const isModule =
+        root.source?.input.file?.endsWith(".module.css") ?? false;
+      root.walkRules((rule) => {
+        if (isRelative(rule)) return;
+        rule.selector = (isModule ? scopeBare : scopeAll).processSync(
+          rule.selector,
+          { lossless: false },
+        );
+      });
+    },
+  };
+}
+
+/** Whether a rule's selectors are relative to something other than the document. */
+function isRelative(rule: Rule): boolean {
+  let parent: Container | Document | undefined = rule.parent;
+  while (parent !== undefined) {
+    if (parent.type === "rule") return true;
+    if (parent.type === "atrule") {
+      const { name } = parent as AtRule;
+      if (name.endsWith("keyframes") || name === "page") return true;
+    }
+    parent = parent.parent;
+  }
+  return false;
+}
+
+const processor = (isModule: boolean): ReturnType<typeof selectorParser> =>
+  selectorParser((selectors) => {
+    selectors.each((selector) => {
+      scopeSelector(selector, isModule);
+    });
+    // Mapping `html, body` onto the root leaves the same selector twice
+    const seen = new Set<string>();
+    selectors.each((selector) => {
+      const text = String(selector).trim();
+      if (seen.has(text)) selector.remove();
+      else seen.add(text);
+    });
+  });
+
+// Everything, for stylesheets that speak of the document; only what a class
+// does not already confine, for CSS modules
+const scopeAll = processor(false);
+const scopeBare = processor(true);
+
+function scopeSelector(selector: Selector, isModule: boolean): void {
+  if (String(selector).includes(ROOT_SELECTOR)) return;
+
+  const compounds = splitCompounds(selector);
+  if (compounds.length === 0) return;
+
+  // Something said of the document is said of the root instead
+  const document = compounds[0].find(isDocumentSelector);
+  if (document !== undefined) {
+    document.replaceWith(pseudo(IS_ROOT));
+    return;
+  }
+
+  const subject = compounds.at(-1)!;
+  if (isModule && subject.some((node) => node.type === "class")) return;
+
+  // Pseudo-elements have to come last in a compound selector
+  const pseudoElement = subject.find(isPseudoElement);
+  if (pseudoElement === undefined) selector.append(pseudo(IN_ROOT));
+  else selector.insertBefore(pseudoElement, pseudo(IN_ROOT));
+}
+
+/** The compound selectors making up a complex selector, in order. */
+function splitCompounds(selector: Selector): Node[][] {
+  const compounds: Node[][] = [[]];
+  for (const node of selector.nodes) {
+    if (node.type === "combinator") compounds.push([]);
+    else if (node.type !== "comment") compounds.at(-1)!.push(node);
+  }
+  return compounds.filter((compound) => compound.length > 0);
+}
+
+function isDocumentSelector(node: Node): boolean {
+  return (
+    (node.type === "tag" && (node.value === "html" || node.value === "body")) ||
+    (node.type === "pseudo" && node.value === ":root")
+  );
+}
+
+function isPseudoElement(node: Node): node is Pseudo {
+  if (node.type !== "pseudo") return false;
+  return (
+    node.value.startsWith("::") ||
+    [":before", ":after", ":first-line", ":first-letter"].includes(node.value)
+  );
+}
+
+function pseudo(text: string): Pseudo {
+  return selectorParser().astSync(text).nodes[0].nodes[0].clone() as Pseudo;
+}

component/dev/DevHostBridge.ts

@@ -0,0 +1,46 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { type ElementCallHostBridge } from "../index";
+
+/**
+ * A host bridge that reports everything it is told, so that the harness can
+ * watch what Element Call says to its host. (What the host says to Element
+ * Call goes through the component's handle, and is logged by the pane.)
+ */
+export function createDevHostBridge(
+  log: (message: string) => void,
+  /** What the host does when Element Call asks to be closed. */
+  onClose: () => void,
+): ElementCallHostBridge {
+  /**
+   * Records something Element Call told the host. Nothing is sent anywhere, so
+   * this is only asynchronous because a real host's answer would have to be.
+   */
+  const told = async (message: string): Promise<void> => {
+    log(`→ ${message}`);
+    await Promise.resolve();
+  };
+
+  return {
+    setAlwaysOnScreen: async (alwaysOnScreen): Promise<void> =>
+      await told(`setAlwaysOnScreen(${alwaysOnScreen})`),
+    contentLoaded: async (): Promise<void> => await told("contentLoaded"),
+    notifyJoined: async (): Promise<void> => await told("notifyJoined"),
+    notifyHungUp: async (): Promise<void> => await told("notifyHungUp"),
+    notifyDeviceMute: async (state): Promise<void> =>
+      await told(
+        `notifyDeviceMute(audio: ${state.audio_enabled}, video: ${state.video_enabled})`,
+      ),
+    // Present because this host really can dismiss Element Call, which is what
+    // makes it offer a close affordance at all
+    close: async (): Promise<void> => {
+      await told("close");
+      onClose();
+    },
+  };
+}

component/dev/Harness.module.css

@@ -0,0 +1,140 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+.credentials {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  max-inline-size: 420px;
+  margin: 48px auto;
+  padding: 24px;
+  background-color: #ffffff;
+  border: 1px solid #d4d4d8;
+  border-radius: 8px;
+}
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.error {
+  color: #b91c1c;
+}
+
+.harness {
+  display: grid;
+  grid-template-rows: auto 1fr auto;
+  block-size: 100%;
+}
+
+.header,
+.paneBar {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 8px 12px;
+  border-block-end: 1px solid #d4d4d8;
+  background-color: #ffffff;
+}
+
+.header h1 {
+  font-size: 16px;
+  margin: 0;
+}
+
+.middle {
+  display: flex;
+  min-block-size: 0;
+}
+
+.sidebar {
+  flex: 0 0 220px;
+  padding: 12px;
+  border-inline-end: 1px solid #d4d4d8;
+  background-color: #ffffff;
+  overflow-y: auto;
+}
+
+.panes {
+  display: flex;
+  flex-wrap: wrap;
+  /* So that a pane is the size it was dragged to, rather than being stretched
+  to fill the row */
+  align-items: flex-start;
+  align-content: flex-start;
+  gap: 16px;
+  padding: 16px;
+  flex: 1;
+  min-inline-size: 0;
+  overflow: auto;
+}
+
+.pane {
+  display: flex;
+  flex-direction: column;
+  border: 1px solid #d4d4d8;
+  border-radius: 8px;
+  overflow: hidden;
+  background-color: #ffffff;
+}
+
+.paneBar {
+  flex-wrap: wrap;
+  gap: 6px;
+  border-block-end: none;
+}
+
+/* The space the host gives Element Call. Resizable so that the sizes it has to
+cope with can be found by dragging rather than by rebuilding, and `overflow:
+hidden` both to enable the resize handle and to show up anything inside Element
+Call that does not fit the box it was given. */
+.paneCall {
+  inline-size: 560px;
+  block-size: 420px;
+  min-inline-size: 180px;
+  min-block-size: 180px;
+  resize: both;
+  overflow: hidden;
+}
+
+.log {
+  max-block-size: 180px;
+  overflow-y: auto;
+  padding: 8px 12px;
+  border-block-start: 1px solid #d4d4d8;
+  background-color: #ffffff;
+  font-size: 12px;
+}
+
+.log h2 {
+  font-size: 13px;
+  margin: 0 0 4px;
+}
+
+.log ol {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* A host overlay, which Element Call must not be able to draw over */
+.dialogScrim {
+  position: fixed;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  background-color: rgb(0 0 0 / 50%);
+  z-index: 10;
+}
+
+.dialog {
+  padding: 24px;
+  border-radius: 8px;
+  background-color: #ffffff;
+}

component/dev/Harness.tsx

@@ -0,0 +1,380 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import {
+  type FC,
+  type FormEvent,
+  type ReactNode,
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { type MatrixClient } from "matrix-js-sdk";
+import { logger } from "matrix-js-sdk/lib/logger";
+
+import {
+  ElementCall,
+  type ElementCallHandle,
+  supportedLanguages,
+} from "../index";
+import { createDevHostBridge } from "./DevHostBridge";
+import { createSession, joinRoom } from "./session";
+import styles from "./Harness.module.css";
+
+interface Credentials {
+  homeserver: string;
+  username: string;
+  password: string;
+  room: string;
+}
+
+const CREDENTIALS_KEY = "element-call-component-harness";
+
+const DEFAULT_CREDENTIALS: Credentials = {
+  homeserver: "https://synapse.m.localhost",
+  username: "",
+  password: "",
+  room: "",
+};
+
+/**
+ * The credentials to start with: the last ones used, so that a reload does not
+ * mean typing them again, overridden by anything in the query string.
+ *
+ * A host reading its own URL is entirely proper — it was Element Call doing so
+ * that was the mistake. It lets the end-to-end tests, or a shared link, say
+ * which account and room to use.
+ */
+function loadCredentials(): Credentials {
+  let stored: Partial<Credentials> = {};
+  try {
+    const json = localStorage.getItem(CREDENTIALS_KEY);
+    if (json !== null) stored = JSON.parse(json) as Credentials;
+  } catch (e) {
+    logger.warn("Could not read the stored harness credentials", e);
+  }
+
+  const query = new URLSearchParams(location.search);
+  const fromUrl = Object.fromEntries(
+    (["homeserver", "username", "password", "room"] as const)
+      .map((name) => [name, query.get(name)])
+      .filter(([, value]) => value !== null),
+  ) as Partial<Credentials>;
+
+  return { ...DEFAULT_CREDENTIALS, ...stored, ...fromUrl };
+}
+
+interface Session {
+  label: string;
+  client: MatrixClient;
+}
+
+type State =
+  | { phase: "credentials" }
+  | { phase: "starting"; progress: string }
+  | { phase: "started"; roomId: string; sessions: Session[] }
+  | { phase: "failed"; error: string };
+
+interface LogEntry {
+  pane: string;
+  message: string;
+  at: string;
+}
+
+/**
+ * One Element Call component, with the controls a host would have over it: the
+ * requests it can make of Element Call, and the ability to take it off screen
+ * altogether.
+ */
+const Pane: FC<{
+  session: Session;
+  roomId: string;
+  theme: string | undefined;
+  language: string | undefined;
+  log: (pane: string, message: string) => void;
+}> = ({ session, roomId, theme, language, log }): ReactNode => {
+  const [mounted, setMounted] = useState(true);
+
+  const bridge = useMemo(
+    () =>
+      createDevHostBridge(
+        (message) => log(session.label, message),
+        () => setMounted(false),
+      ),
+    [log, session.label],
+  );
+
+  // What the host asks of Element Call goes through the component's handle.
+  // Worth saying out loud when a request is refused — asking to hang up when
+  // there is no call, say — since that is the sort of thing the harness is for.
+  const handle = useRef<ElementCallHandle>(null);
+  const ask = (
+    name: string,
+    make: (handle: ElementCallHandle) => Promise<unknown>,
+  ): void => {
+    if (handle.current === null) {
+      log(session.label, `← ${name}: not mounted`);
+      return;
+    }
+    log(session.label, `← ${name}`);
+    make(handle.current).then(
+      (reply) =>
+        log(
+          session.label,
+          `→ ${name} acknowledged${reply === undefined ? "" : `: ${JSON.stringify(reply)}`}`,
+        ),
+      (e: unknown) => log(session.label, `→ ${name} refused: ${e}`),
+    );
+  };
+
+  return (
+    <section className={styles.pane} data-testid="call-pane">
+      <div className={styles.paneBar}>
+        <strong>{session.label}</strong>
+        <code>{session.client.getDeviceId()}</code>
+        <button onClick={(): void => setMounted((m) => !m)}>
+          {mounted ? "Unmount" : "Mount"}
+        </button>
+        <button
+          onClick={(): void =>
+            ask(
+              "setDeviceMute(audio: false)",
+              async (h) => await h.setDeviceMute({ audio_enabled: false }),
+            )
+          }
+        >
+          Mute
+        </button>
+        <button
+          onClick={(): void => ask("hangUp", async (h) => await h.hangUp())}
+        >
+          Hang up
+        </button>
+      </div>
+      {/* Resizable, because how Element Call copes with the size it is given is
+      one of the things we cannot find out from the standalone app */}
+      <div className={styles.paneCall} data-testid="call-container">
+        {mounted && (
+          <ElementCall
+            ref={handle}
+            client={session.client}
+            roomId={roomId}
+            hostBridge={bridge}
+            theme={theme}
+            language={language}
+          />
+        )}
+      </div>
+    </section>
+  );
+};
+
+/** Host furniture, to make it visible if Element Call styles anything but itself. */
+const HostChrome: FC = (): ReactNode => (
+  <nav className={styles.sidebar}>
+    <h2>Host chrome</h2>
+    <p>
+      This column belongs to the host. If Element Call&apos;s stylesheet reaches
+      outside its own container, it shows up here.
+    </p>
+    <hr />
+    <ul>
+      <li>Some room</li>
+      <li>Another room</li>
+    </ul>
+    <button>A host button</button>
+  </nav>
+);
+
+/**
+ * A dialog of the host's own, over the top of the calls. Element Call as a
+ * component has to sit underneath this — being unable to is one of the reasons
+ * for a component rather than an iframe.
+ */
+const HostDialog: FC<{ onClose: () => void }> = ({ onClose }): ReactNode => (
+  <div className={styles.dialogScrim}>
+    <div className={styles.dialog}>
+      <h2>A dialog belonging to the host</h2>
+      <p>This should cover the calls completely.</p>
+      <button onClick={onClose}>Close</button>
+    </div>
+  </div>
+);
+
+/**
+ * Stands in for a host application using the Element Call component: it owns the Matrix
+ * clients, the page and the space each call is given, and reaches Element Call
+ * only through the component's public interface.
+ *
+ * Two calls at once, from two devices of the same account, so that a real call
+ * happens between them and anything Element Call keeps once per process rather
+ * than once per call shows itself.
+ */
+export const Harness: FC = (): ReactNode => {
+  const [credentials, setCredentials] = useState(loadCredentials);
+  const [state, setState] = useState<State>({ phase: "credentials" });
+  const [entries, setEntries] = useState<LogEntry[]>([]);
+  const [dialogOpen, setDialogOpen] = useState(false);
+  // The host's language setting, which Element Call follows. Undefined means
+  // the host has none and Element Call uses the browser's.
+  const [language, setLanguage] = useState<string | undefined>(undefined);
+  const [theme, setTheme] = useState<string | undefined>(undefined);
+
+  const log = useCallback((pane: string, message: string): void => {
+    setEntries((entries) =>
+      [
+        ...entries,
+        { pane, message, at: new Date().toLocaleTimeString() },
+      ].slice(-100),
+    );
+  }, []);
+
+  const start = useCallback(
+    (event: FormEvent): void => {
+      event.preventDefault();
+      localStorage.setItem(CREDENTIALS_KEY, JSON.stringify(credentials));
+      const { homeserver, username, password, room } = credentials;
+
+      const progress = (message: string): void =>
+        setState({ phase: "starting", progress: message });
+      progress("Starting");
+
+      void (async (): Promise<void> => {
+        try {
+          // One at a time: two logins at once from the same account is the
+          // shape of request homeservers rate limit
+          const sessions: Session[] = [];
+          for (const label of ["Call A", "Call B"])
+            sessions.push({
+              label,
+              client: await createSession(
+                homeserver,
+                username,
+                password,
+                (message) => progress(`${label}: ${message}`),
+              ),
+            });
+
+          progress("Joining the room");
+          let roomId = room;
+          for (const { client } of sessions)
+            roomId = await joinRoom(client, roomId);
+
+          setState({ phase: "started", roomId, sessions });
+        } catch (e) {
+          logger.error("The harness could not start", e);
+          setState({ phase: "failed", error: `${e}` });
+        }
+      })();
+    },
+    [credentials],
+  );
+
+  const field = (
+    name: keyof Credentials,
+    label: string,
+    type = "text",
+  ): ReactNode => (
+    <label className={styles.field}>
+      {label}
+      <input
+        type={type}
+        value={credentials[name]}
+        onChange={(e): void =>
+          setCredentials((c) => ({ ...c, [name]: e.target.value }))
+        }
+      />
+    </label>
+  );
+
+  if (state.phase !== "started")
+    return (
+      <form className={styles.credentials} onSubmit={start}>
+        <h1>Element Call component harness</h1>
+        <p>
+          Signs in twice and shows the Element Call component twice, in a page
+          that is not Element Call&apos;s own.
+        </p>
+        {field("homeserver", "Homeserver")}
+        {field("username", "Username")}
+        {field("password", "Password", "password")}
+        {field("room", "Room ID or alias")}
+        <button type="submit" disabled={state.phase === "starting"}>
+          Start
+        </button>
+        {state.phase === "starting" && <p>{state.progress}</p>}
+        {state.phase === "failed" && (
+          <p className={styles.error}>{state.error}</p>
+        )}
+      </form>
+    );
+
+  return (
+    <div className={styles.harness}>
+      <header className={styles.header}>
+        <h1>Element Call component harness</h1>
+        <code>{state.roomId}</code>
+        <button onClick={(): void => setDialogOpen(true)}>
+          Open a host dialog
+        </button>
+        <label>
+          Theme{" "}
+          <select
+            value={theme ?? ""}
+            onChange={(e): void => setTheme(e.target.value || undefined)}
+          >
+            <option value="">Element Call&apos;s choice</option>
+            <option value="light">light</option>
+            <option value="dark">dark</option>
+          </select>
+        </label>
+        <label>
+          Language{" "}
+          <select
+            value={language ?? ""}
+            onChange={(e): void => setLanguage(e.target.value || undefined)}
+          >
+            <option value="">Browser default</option>
+            {supportedLanguages.map((tag) => (
+              <option key={tag} value={tag}>
+                {tag}
+              </option>
+            ))}
+          </select>
+        </label>
+      </header>
+      <div className={styles.middle}>
+        <HostChrome />
+        <main className={styles.panes}>
+          {state.sessions.map((session) => (
+            <Pane
+              key={session.label}
+              session={session}
+              roomId={state.roomId}
+              theme={theme}
+              language={language}
+              log={log}
+            />
+          ))}
+        </main>
+      </div>
+      <section className={styles.log} data-testid="bridge-log">
+        <h2>Host bridge</h2>
+        <ol>
+          {entries.map((entry, i) => (
+            <li key={i}>
+              <code>{entry.at}</code> <strong>{entry.pane}</strong>{" "}
+              {entry.message}
+            </li>
+          ))}
+        </ol>
+      </section>
+      {dialogOpen && <HostDialog onClose={(): void => setDialogOpen(false)} />}
+    </div>
+  );
+};

component/dev/host.css

@@ -0,0 +1,23 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+/* The host page's own styles. Deliberately plain, and deliberately not using
+Element Call's design tokens: the harness should look like it does because of
+this file, not because Element Call styled it. */
+
+html,
+body,
+#root {
+  height: 100%;
+}
+
+body {
+  margin: 0;
+  font-family: system-ui, sans-serif;
+  background-color: #f4f4f5;
+  color: #18181b;
+}

component/dev/index.html

@@ -0,0 +1,21 @@
+<!doctype html>
+<!--
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+-->
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Element Call component harness</title>
+  </head>
+  <body>
+    <!-- Deliberately plain: this page stands in for a host application, so
+    anything it looks like must have come from the host's own styles or from
+    Element Call reaching outside its container. -->
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

component/dev/main.tsx

@@ -0,0 +1,42 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { logger } from "matrix-js-sdk/lib/logger";
+
+import { type ConfigOptions, initializeElementCall } from "../index";
+import { Harness } from "./Harness";
+// After Element Call's, so that the host has the last word on its own page
+import "./host.css";
+
+/**
+ * The development app's own `config.json`, so that the harness runs Element
+ * Call the way `pnpm dev` does. It is not in the repository — developers copy
+ * it from `config/config.devenv.json` — so its absence is expected rather than
+ * an error.
+ */
+async function loadConfig(): Promise<ConfigOptions> {
+  try {
+    const response = await fetch("/config.json");
+    if (response.ok) return (await response.json()) as ConfigOptions;
+    logger.warn(
+      `No config.json (${response.status}); running with Element Call's defaults`,
+    );
+  } catch (e) {
+    logger.warn("Could not read config.json", e);
+  }
+  return {};
+}
+
+await initializeElementCall(await loadConfig());
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <Harness />
+  </StrictMode>,
+);

component/dev/session.ts

@@ -0,0 +1,79 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import {
+  ClientEvent,
+  createClient,
+  type MatrixClient,
+  MemoryStore,
+  SyncState,
+} from "matrix-js-sdk";
+
+/**
+ * Logs in and brings up a client the way a host application would, so that the
+ * component is handed a real one rather than something Element Call built for
+ * itself.
+ *
+ * Everything is kept in memory and a fresh login happens on every reload. That
+ * costs a device on the development homeserver each time, which is harmless,
+ * and buys the harness two clients that cannot tread on each other's storage.
+ * Persisting the login to make reloads quicker would mean persisting the
+ * crypto store too: reusing a device ID with a fresh crypto store generates new
+ * device keys, and uploading them conflicts with the ones the server already
+ * holds.
+ */
+export async function createSession(
+  homeserver: string,
+  username: string,
+  password: string,
+  onProgress: (message: string) => void,
+): Promise<MatrixClient> {
+  onProgress("Logging in");
+  const login = await createClient({ baseUrl: homeserver }).login(
+    "m.login.password",
+    { identifier: { type: "m.id.user", user: username }, password },
+  );
+
+  const client = createClient({
+    baseUrl: homeserver,
+    accessToken: login.access_token,
+    userId: login.user_id,
+    deviceId: login.device_id,
+    store: new MemoryStore(),
+    useAuthorizationHeader: true,
+    fallbackICEServerAllowed: true,
+  });
+
+  onProgress(`Setting up crypto for ${login.device_id}`);
+  await client.initRustCrypto({ useIndexedDB: false });
+
+  onProgress(`Syncing ${login.device_id}`);
+  await client.startClient();
+  await new Promise<void>((resolve) => {
+    const onSync = (state: SyncState): void => {
+      if (state !== SyncState.Prepared && state !== SyncState.Syncing) return;
+      client.off(ClientEvent.Sync, onSync);
+      resolve();
+    };
+    client.on(ClientEvent.Sync, onSync);
+  });
+
+  return client;
+}
+
+/**
+ * The room to call in, joining it if this session is not in it yet — a host
+ * hands Element Call a room it already knows about, so the harness has to get
+ * itself into that position first.
+ */
+export async function joinRoom(
+  client: MatrixClient,
+  roomIdOrAlias: string,
+): Promise<string> {
+  const room = await client.joinRoom(roomIdOrAlias);
+  return room.roomId;
+}

component/host.test.ts

@@ -0,0 +1,161 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { renderHook } from "@testing-library/react";
+import { createRef } from "react";
+import { describe, expect, test, vi } from "vitest";
+
+import {
+  type ElementCallHandle,
+  type ElementCallHostBridge,
+  useComponentHostBridge,
+} from "./host";
+
+describe("useComponentHostBridge", () => {
+  test("keeps one identity while the host supplies new objects", () => {
+    const { result, rerender } = renderHook(
+      ({ supplied }: { supplied: ElementCallHostBridge }) =>
+        useComponentHostBridge(supplied, undefined, undefined),
+      { initialProps: { supplied: {} } },
+    );
+    const first = result.current;
+    rerender({ supplied: { notifyJoined: async () => {} } });
+    expect(result.current).toBe(first);
+  });
+
+  test("forwards to whatever the host most recently supplied", async () => {
+    const before = vi.fn().mockResolvedValue(undefined);
+    const after = vi.fn().mockResolvedValue(undefined);
+    const { result, rerender } = renderHook(
+      ({ supplied }: { supplied: ElementCallHostBridge }) =>
+        useComponentHostBridge(supplied, undefined, undefined),
+      { initialProps: { supplied: { notifyJoined: before } } },
+    );
+    rerender({ supplied: { notifyJoined: after } });
+
+    await result.current.notifyJoined();
+    expect(before).not.toHaveBeenCalled();
+    expect(after).toHaveBeenCalledOnce();
+  });
+
+  test("is quiet about what the host did not implement", async () => {
+    const { result } = renderHook(() =>
+      useComponentHostBridge(undefined, undefined, undefined),
+    );
+    await expect(result.current.contentLoaded()).resolves.toBeUndefined();
+    await expect(
+      result.current.notifyDeviceMute({
+        audio_enabled: true,
+        video_enabled: false,
+      }),
+    ).resolves.toBeUndefined();
+    expect(result.current.supportsReactions).toBe(true);
+    // Starting the user unmuted unasked is something a host has to opt into
+    expect(result.current.allowJoinUnmutedViaIntent).toBe(false);
+  });
+
+  test("lets the host allow joining unmuted on the intent", () => {
+    const { result, rerender } = renderHook(
+      ({ supplied }: { supplied: ElementCallHostBridge }) =>
+        useComponentHostBridge(supplied, undefined, undefined),
+      { initialProps: { supplied: {} } },
+    );
+    expect(result.current.allowJoinUnmutedViaIntent).toBe(false);
+
+    // Read through to whatever the host most recently said
+    rerender({ supplied: { allowJoinUnmutedViaIntent: true } });
+    expect(result.current.allowJoinUnmutedViaIntent).toBe(true);
+  });
+
+  test("only has a close when the host has one, since that is a signal", () => {
+    const { result, rerender } = renderHook(
+      ({ supplied }: { supplied: ElementCallHostBridge }) =>
+        useComponentHostBridge(supplied, undefined, undefined),
+      { initialProps: { supplied: {} } },
+    );
+    expect(result.current.close).toBeUndefined();
+
+    const close = vi.fn().mockResolvedValue(undefined);
+    rerender({ supplied: { close } });
+    expect(result.current.close).toBeDefined();
+  });
+
+  test("never offers profile changes, since the account is the host's", () => {
+    const { result } = renderHook(() =>
+      useComponentHostBridge(undefined, undefined, undefined),
+    );
+    expect(result.current.supportsProfileChanges).toBe(false);
+  });
+
+  describe("the handle", () => {
+    test("delivers a request to what is listening and resolves on its reply", async () => {
+      const ref = createRef<ElementCallHandle>();
+      const { result } = renderHook(() =>
+        useComponentHostBridge(undefined, ref, undefined),
+      );
+
+      const received = vi.fn();
+      result.current.deviceMute$.subscribe(({ data, reply }) => {
+        received(data);
+        reply({ audio_enabled: data.audio_enabled!, video_enabled: true });
+      });
+
+      await expect(
+        ref.current!.setDeviceMute({ audio_enabled: false }),
+      ).resolves.toEqual({ audio_enabled: false, video_enabled: true });
+      expect(received).toHaveBeenCalledWith({ audio_enabled: false });
+    });
+
+    test("refuses a request nothing in Element Call is listening for", async () => {
+      const ref = createRef<ElementCallHandle>();
+      renderHook(() => useComponentHostBridge(undefined, ref, undefined));
+
+      await expect(ref.current!.hangUp()).rejects.toThrow(
+        "Nothing in Element Call can hang up right now",
+      );
+    });
+  });
+
+  describe("the theme", () => {
+    test("reaches a subscriber that arrives after it was set", () => {
+      const { result } = renderHook(() =>
+        useComponentHostBridge(undefined, undefined, "light"),
+      );
+      const names: (string | undefined)[] = [];
+      result.current.themeChange$.subscribe(({ data }) =>
+        names.push(data.name),
+      );
+      expect(names).toEqual(["light"]);
+    });
+
+    test("follows the prop", () => {
+      const { result, rerender } = renderHook(
+        ({ theme }: { theme: string | undefined }) =>
+          useComponentHostBridge(undefined, undefined, theme),
+        { initialProps: { theme: "light" } },
+      );
+      const names: (string | undefined)[] = [];
+      result.current.themeChange$.subscribe(({ data }) =>
+        names.push(data.name),
+      );
+
+      rerender({ theme: "dark" });
+      expect(names).toEqual(["light", "dark"]);
+    });
+
+    test("says nothing when the host leaves the theme to Element Call", () => {
+      const { result } = renderHook(() =>
+        useComponentHostBridge(undefined, undefined, undefined),
+      );
+      const names: (string | undefined)[] = [];
+      result.current.themeChange$.subscribe(({ data }) =>
+        names.push(data.name),
+      );
+      expect(names).toEqual([]);
+    });
+  });
+});

component/host.ts

@@ -0,0 +1,201 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+/**
+ * How a host application and the Element Call component talk to each other.
+ *
+ * Inside Element Call the host is a {@link HostBridge}, which carries the
+ * host's requests as rxjs observables because that is what the widget API and
+ * the view models work in. A host should not have to know about rxjs, or agree
+ * with us on a version of it, so a component host sees neither: it implements
+ * plain async callbacks for what Element Call tells it, and makes its own
+ * requests through an imperative handle on the component, the way it would
+ * call `play()` on a video element. This module adapts the one to the other.
+ */
+
+import { type Ref, useEffect, useImperativeHandle } from "react";
+import { ReplaySubject, Subject } from "rxjs";
+
+import {
+  type DeviceMuteRequest,
+  type DeviceMuteState,
+  type HostBridge,
+  type HostRequest,
+} from "../src/HostBridge";
+import { type JoinCallData } from "../src/widget";
+import { useInitial } from "../src/useInitial";
+import { useLatest } from "../src/useLatest";
+
+/**
+ * What Element Call tells the application hosting it as a component.
+ * Everything is optional: a host implements what it wants to hear about.
+ *
+ * Compared by nothing — Element Call always calls whichever one it was most
+ * recently given, so this may be written inline.
+ */
+export interface ElementCallHostBridge {
+  /**
+   * Asks the host to keep Element Call on screen (or stop doing so), so that a
+   * call in progress is not torn down when the user navigates elsewhere.
+   */
+  setAlwaysOnScreen?(alwaysOnScreen: boolean): Promise<void>;
+  /** Tells the host that Element Call has finished loading. */
+  contentLoaded?(): Promise<void>;
+  /** Tells the host that the user has joined the call. */
+  notifyJoined?(): Promise<void>;
+  /** Tells the host that the user has hung up. */
+  notifyHungUp?(): Promise<void>;
+  /** Tells the host the user's current audio and video mute state. */
+  notifyDeviceMute?(state: DeviceMuteState): Promise<void>;
+  /**
+   * Asks the host to close Element Call: to unmount the component. Its
+   * presence is what makes Element Call offer a close button on its error
+   * screens, and leave the host to decide what is shown once a call has ended.
+   * Without it, Element Call shows its own post-call screen, if it has one for
+   * the situation, or nothing.
+   */
+  close?(): Promise<void>;
+  /**
+   * Whether Element Call may send and receive reactions in this room.
+   * Defaults to true.
+   */
+  readonly supportsReactions?: boolean;
+  /**
+   * Whether the user may start unmuted when the intent skips the lobby, so
+   * that they never see their devices before joining. Defaults to false: the
+   * user starts muted and unmutes themselves. A host that chose the intent on
+   * the user's behalf, and is sure they expect to be heard and seen at once,
+   * says so here — as a Matrix client hosting Element Call as a widget does.
+   */
+  readonly allowJoinUnmutedViaIntent?: boolean;
+}
+
+/**
+ * What a host can ask of a mounted Element Call, reached through the
+ * component's `ref`. Each request resolves once Element Call has acted on it,
+ * and rejects if nothing in Element Call is in a position to act: hanging up
+ * when there is no call, say.
+ */
+export interface ElementCallHandle {
+  /**
+   * Joins the call, when Element Call was configured to `preload` and is
+   * waiting to be told to. Says which devices to join with.
+   */
+  join(devices: JoinCallData): Promise<void>;
+  /** Leaves the call. */
+  hangUp(): Promise<void>;
+  /**
+   * Changes the mute state, for whichever of audio and video is given, and
+   * reports the state that results.
+   */
+  setDeviceMute(request: DeviceMuteRequest): Promise<DeviceMuteState>;
+}
+
+/** Hands a request to Element Call and waits for it to be acknowledged. */
+async function request<Data, Reply>(
+  listeners: Subject<HostRequest<Data, Reply>>,
+  what: string,
+  data: Data,
+): Promise<Reply> {
+  if (!listeners.observed)
+    throw new Error(`Nothing in Element Call can ${what} right now`);
+  return await new Promise((resolve) =>
+    listeners.next({ data, reply: resolve }),
+  );
+}
+
+/**
+ * The {@link HostBridge} the rest of Element Call sees, built from what a
+ * component host supplies and wired to the handle it is given.
+ *
+ * The bridge is created once and never changes identity — everything that
+ * depends on it would otherwise restart when the host re-rendered with a new
+ * object — and forwards each call to whatever the host most recently passed.
+ */
+export function useComponentHostBridge(
+  supplied: ElementCallHostBridge | undefined,
+  ref: Ref<ElementCallHandle> | undefined,
+  /** The theme the host wants, or undefined to leave it to Element Call. */
+  theme: string | undefined,
+): HostBridge {
+  const latest = useLatest(supplied ?? {});
+
+  const requests = useInitial(() => ({
+    // The theme is state, not an event: a `theme` prop rather than a request
+    // on the handle. It travels this channel because that is how the rest of
+    // Element Call hears about a host's theme, and replays so that whatever
+    // subscribes after the host has set it — everything, on first render —
+    // still hears the current one.
+    themeChange$: new ReplaySubject<HostRequest<{ name?: string }>>(1),
+    join$: new Subject<HostRequest<JoinCallData>>(),
+    hangUp$: new Subject<HostRequest<Record<string, never>>>(),
+    deviceMute$: new Subject<HostRequest<DeviceMuteRequest, DeviceMuteState>>(),
+  }));
+
+  useEffect(() => {
+    if (theme !== undefined)
+      requests.themeChange$.next({ data: { name: theme }, reply: () => {} });
+  }, [requests, theme]);
+
+  const bridge = useInitial((): HostBridge => ({
+    setAlwaysOnScreen: async (alwaysOnScreen) => {
+      await latest.current.setAlwaysOnScreen?.(alwaysOnScreen);
+    },
+    contentLoaded: async () => {
+      await latest.current.contentLoaded?.();
+    },
+    notifyJoined: async () => {
+      await latest.current.notifyJoined?.();
+    },
+    notifyHungUp: async () => {
+      await latest.current.notifyHungUp?.();
+    },
+    notifyDeviceMute: async (state) => {
+      await latest.current.notifyDeviceMute?.(state);
+    },
+    // Whether these exist is itself information, so they are read through
+    // rather than wrapped unconditionally
+    get close() {
+      const close = latest.current.close;
+      return close === undefined
+        ? undefined
+        : async (): Promise<void> => await close();
+    },
+    // Not offered to a component host: the client it hands over holds the
+    // credentials to fetch media itself. A widget's client does not, which
+    // is what the internal bridge's `downloadMedia` is for.
+    get supportsReactions(): boolean {
+      return latest.current.supportsReactions ?? true;
+    },
+    get allowJoinUnmutedViaIntent(): boolean {
+      return latest.current.allowJoinUnmutedViaIntent ?? false;
+    },
+    // Whatever the host says or does not say, the account is its own: it
+    // signed the user in and handed us the client. So Element Call never
+    // offers to edit the profile from inside a component.
+    supportsProfileChanges: false,
+    ...requests,
+  }));
+
+  useImperativeHandle(
+    ref,
+    (): ElementCallHandle => ({
+      join: async (devices) =>
+        await request(requests.join$, "join a call", devices),
+      hangUp: async () => await request(requests.hangUp$, "hang up", {}),
+      setDeviceMute: async (muteRequest) =>
+        await request(
+          requests.deviceMute$,
+          "change the mute state",
+          muteRequest,
+        ),
+    }),
+    [requests],
+  );
+
+  return bridge;
+}

component/index.tsx

@@ -0,0 +1,358 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+/**
+ * EXPERIMENTAL
+ *
+ * Element Call as a React component, for an application that wants to show a
+ * call inside itself rather than in an iframe.
+ *
+ * The host supplies the client and says which room to call in; Element Call
+ * supplies the call. Everything it would otherwise take from the page it is on
+ * — the URL, the document body, a Matrix session of its own — comes from the
+ * host instead, or is confined to the container it is mounted in.
+ */
+
+// The design tokens, fonts and element defaults every Element Call stylesheet
+// builds on. Written for a page, they speak of `html`, `body` and bare
+// elements; the component build confines them, and every other stylesheet in
+// this bundle, to the root element below (see build/scopeStylesToRoot.ts), so
+// that the host's document is left as it was.
+//
+// Where these land relative to the component stylesheets is the bundler's
+// choice — the standalone app puts them first, this build puts them in the
+// middle — so nothing in base.css may depend on winning or losing against a
+// component's own rules at equal specificity. It currently does not: what it
+// declares unlayered is custom properties on Element Call's root, which
+// components inherit rather than compete with, and everything from Compound
+// sits in a `@layer`, which loses to unlayered rules either way.
+import "../src/base.css";
+
+import {
+  type FC,
+  type JSX,
+  type ReactNode,
+  type Ref,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { type MatrixClient } from "matrix-js-sdk";
+import { logger } from "matrix-js-sdk/lib/logger";
+import { I18nextProvider } from "react-i18next";
+import { TooltipProvider } from "@vector-im/compound-web";
+import { ErrorBoundary } from "@sentry/react";
+import { shouldPolyfill as shouldPolyfillSegmenter } from "@formatjs/intl-segmenter/should-polyfill";
+import { shouldPolyfill as shouldPolyfillDurationFormat } from "@formatjs/intl-durationformat/should-polyfill.js";
+
+import LanguageDetector from "i18next-browser-languagedetector";
+
+import EN from "../locales/en/app.json";
+import { CallView } from "../src/room/CallView";
+import { ErrorPage } from "../src/FullScreenView";
+import { ClientProvider } from "../src/ClientContext";
+import { HostBridgeProvider } from "../src/HostBridge";
+import { RootElementProvider, useRootElement } from "../src/RootElementContext";
+import {
+  configurationForIntent,
+  componentProperties,
+  type UrlConfiguration,
+  type UrlParams,
+  UrlParamsProvider,
+  type UrlProperties,
+  UserIntent,
+  useUrlParams,
+} from "../src/UrlParams";
+import { MediaDevicesContext } from "../src/MediaDevicesContext";
+import { MediaDevices } from "../src/state/MediaDevices";
+import { ObservableScope } from "../src/state/ObservableScope";
+import { ProcessorProvider } from "../src/livekit/TrackProcessorContext";
+import { Config } from "../src/config/Config";
+import { type ConfigOptions } from "../src/config/ConfigOptions";
+import { i18n } from "../src/utils/i18n";
+import { useTheme } from "../src/useTheme";
+import { useStableValue } from "../src/useStableValue";
+import styles from "./ElementCall.module.css";
+import {
+  type ElementCallHandle,
+  type ElementCallHostBridge,
+  useComponentHostBridge,
+} from "./host";
+import { supportedLanguages, translationsBackend } from "./localization";
+
+// The languages Element Call can be shown in
+export { supportedLanguages } from "./localization";
+
+// How the host and Element Call talk to each other, and what they say
+export { type ElementCallHandle, type ElementCallHostBridge } from "./host";
+export {
+  type DeviceMuteRequest,
+  type DeviceMuteState,
+} from "../src/HostBridge";
+export { type JoinCallData } from "../src/widget";
+// The deployment-wide configuration, as distinct from ElementCallConfiguration
+// above, which is per call
+export { type ConfigOptions } from "../src/config/ConfigOptions";
+// The values that appear in ElementCallConfiguration and in the intent
+export {
+  BackgroundStyle,
+  HeaderStyle,
+  UserIntent,
+  type UrlConfiguration,
+} from "../src/UrlParams";
+
+/**
+ * How Element Call should behave. Everything is optional; anything left out
+ * takes the default that {@link ElementCallProps.intent} implies.
+ *
+ * This is the behaviour a widget can be configured with through its URL, plus
+ * the one fact about the call a host has a say in here, the background. The
+ * rest of what a widget's URL carries — who the user is, how to reach the
+ * homeserver, where to report analytics, the shared secret of a room that is
+ * encrypted with one — a component host supplies by other routes, or not at
+ * all; and what can change while the call is running, the theme and the
+ * language, is a prop of its own.
+ */
+export type ElementCallConfiguration = Partial<UrlConfiguration> &
+  Partial<Pick<UrlProperties, "background">>;
+
+export interface ElementCallProps {
+  /**
+   * The client to place the call with. Element Call does not authenticate
+   * anyone or manage a session of its own; this one is the host's.
+   */
+  client: MatrixClient;
+  /** The room to call in. The host's client must already know about it. */
+  roomId: string;
+  /**
+   * What the user asked for — whether they started the call or joined one that
+   * was already running, and whether it is a call in a group or a DM. Element
+   * Call decides what each of those means: whether to show the lobby first,
+   * whether to ring, and so on.
+   *
+   * Defaults to joining an existing group call, which is the most conservative
+   * reading, but a host that knows which button the user pressed should say so.
+   */
+  intent?: UserIntent;
+  /**
+   * How Element Call should behave, overriding whatever {@link intent} implies.
+   * A host that finds itself setting a lot of these probably wants a different
+   * intent instead.
+   *
+   * Compared by value, so it is fine to write this inline; only a change to
+   * what it says restarts anything.
+   */
+  config?: ElementCallConfiguration;
+  /**
+   * What Element Call tells the host while the call is running: that the user
+   * has joined or hung up, that it would like to be kept on screen, and so on.
+   * Without one, Element Call assumes nobody is listening.
+   */
+  hostBridge?: ElementCallHostBridge;
+  /**
+   * What the host tells Element Call: to hang up, to mute, to join. Available
+   * once the component has rendered.
+   */
+  ref?: Ref<ElementCallHandle>;
+  /**
+   * The theme to show Element Call in, `light` or `dark`. Left out, Element
+   * Call picks. Changes take effect at once, and cost nothing else.
+   */
+  theme?: string;
+  /**
+   * The language to show Element Call in, as a BCP 47 tag: one of
+   * {@link supportedLanguages}, or something that falls back to one (`de-AT`
+   * to `de`). Left out, the browser's language is used.
+   *
+   * Translations are one thing shared by every Element Call on the page, so
+   * the most recently set language wins for all of them.
+   */
+  language?: string;
+}
+
+/**
+ * Prepares the things Element Call needs before it can be shown: translations,
+ * `Intl` polyfills for older browsers, and its configuration.
+ *
+ * Await this once, before rendering {@link ElementCall}.
+ */
+export async function initializeElementCall(
+  config: ConfigOptions = {},
+): Promise<void> {
+  const polyfills: Promise<unknown>[] = [];
+  if (shouldPolyfillSegmenter())
+    polyfills.push(import("@formatjs/intl-segmenter/polyfill-force"));
+  if (shouldPolyfillDurationFormat())
+    polyfills.push(import("@formatjs/intl-durationformat/polyfill-force.js"));
+  await Promise.all(polyfills);
+
+  Config.initWith(config);
+  await i18n
+    .use(translationsBackend)
+    .use(new LanguageDetector())
+    .init({
+      fallbackLng: "en",
+      defaultNS: "app",
+      keySeparator: ".",
+      nsSeparator: false,
+      pluralSeparator: "_",
+      contextSeparator: "|",
+      supportedLngs: [...supportedLanguages],
+      interpolation: { escapeValue: false },
+      // English is bundled in, so the fallback never has to be loaded; every
+      // other language arrives from the backend when first asked for.
+      partialBundledLanguages: true,
+      resources: { en: { app: EN } },
+      detection: {
+        // The browser's language, until the host says otherwise through the
+        // `language` prop. Nothing is remembered: the choice is the host's.
+        order: ["navigator"],
+        caches: [],
+      },
+    });
+}
+
+/** Applies the theme and background to the container, before it is painted. */
+const Decoration: FC<{ children: JSX.Element }> = ({ children }) => {
+  useTheme();
+  const { background } = useUrlParams();
+  const rootElement = useRootElement();
+  useLayoutEffect(() => {
+    rootElement.setAttribute("data-background", background);
+  }, [rootElement, background]);
+  return children;
+};
+
+export const ElementCall: FC<ElementCallProps> = ({
+  client,
+  roomId,
+  intent = UserIntent.JoinExistingCall,
+  config,
+  hostBridge: suppliedHostBridge,
+  ref,
+  theme,
+  language,
+}): ReactNode => {
+  const hostBridge = useComponentHostBridge(suppliedHostBridge, ref, theme);
+
+  useEffect(() => {
+    if (language !== undefined)
+      i18n
+        .changeLanguage(language)
+        .catch((e) => logger.error(`Could not switch to ${language}`, e));
+  }, [language]);
+
+  // The container is what Element Call decorates and portals into, so nothing
+  // inside can render until we have it.
+  const [container, setContainer] = useState<HTMLDivElement | null>(null);
+
+  // Element Call has no URL of its own to read any of this from, and the
+  // host's URL is not Element Call's business, so the defaults come from the
+  // intent with the host's wishes over the top.
+  //
+  // Everything downstream — the mute state, the call view model and with it
+  // the media connection — is keyed on the identity of this object, so it has
+  // to be stable for as long as its contents are. A host writing `config`
+  // inline would otherwise tear the call down on every render.
+  const stableConfig = useStableValue(config);
+  const params = useMemo(
+    (): UrlParams => ({
+      ...componentProperties,
+      roomId,
+      ...configurationForIntent(intent),
+      ...stableConfig,
+    }),
+    [roomId, intent, stableConfig],
+  );
+
+  // Created in an effect so that the scope it lives in ends when the component
+  // is unmounted (or these options change), rather than keeping its device
+  // observers running for the rest of the page's life. Null until then, which
+  // is one render.
+  const { controlledAudioDevices, callIntent } = params;
+  const [mediaDevices, setMediaDevices] = useState<MediaDevices | null>(null);
+  useEffect(() => {
+    const scope = new ObservableScope();
+    setMediaDevices(
+      new MediaDevices(scope, { controlledAudioDevices, callIntent }),
+    );
+    return (): void => {
+      setMediaDevices(null);
+      scope.end();
+    };
+  }, [controlledAudioDevices, callIntent]);
+
+  const room = client.getRoom(roomId);
+  const rtcSession = useMemo(
+    () => (room === null ? null : client.matrixRTC.getRoomSession(room)),
+    [client, room],
+  );
+
+  if (rtcSession === null)
+    logger.error(
+      `Element Call was asked to call in ${roomId}, which its host's client does not know about`,
+    );
+
+  // Everything the call needs is in hand once these exist, and the first
+  // render with them is where the call itself appears: the moment the host
+  // is told that Element Call has loaded, as the widget tells its client once
+  // its own initialisation is over. Once per mount, however often the pieces
+  // are later swapped out.
+  const ready =
+    container !== null && rtcSession !== null && mediaDevices !== null;
+  const announcedLoaded = useRef(false);
+  useEffect(() => {
+    if (!ready || announcedLoaded.current) return;
+    announcedLoaded.current = true;
+    hostBridge
+      .contentLoaded()
+      .catch((e) => logger.error("Could not tell the host we had loaded", e));
+  }, [ready, hostBridge]);
+
+  return (
+    <I18nextProvider i18n={i18n}>
+      <HostBridgeProvider value={hostBridge}>
+        <UrlParamsProvider value={params}>
+          <div ref={setContainer} className={styles.root}>
+            {ready && (
+              <RootElementProvider value={container}>
+                {/* Whatever goes wrong in here is shown in here. Left to
+                  propagate, an error would unmount the host's own tree. */}
+                <ErrorBoundary
+                  fallback={(error) => <ErrorPage error={error} />}
+                  // A broken call should not hold the host on screen
+                  onError={() => void hostBridge.setAlwaysOnScreen(false)}
+                >
+                  <Decoration>
+                    <TooltipProvider>
+                      <ClientProvider client={client}>
+                        <MediaDevicesContext value={mediaDevices}>
+                          <ProcessorProvider>
+                            <CallView
+                              client={client}
+                              rtcSession={rtcSession}
+                              isPasswordlessUser={false}
+                              confineToRoom={params.confineToRoom}
+                              preload={params.preload}
+                              skipLobby={params.skipLobby}
+                            />
+                          </ProcessorProvider>
+                        </MediaDevicesContext>
+                      </ClientProvider>
+                    </TooltipProvider>
+                  </Decoration>
+                </ErrorBoundary>
+              </RootElementProvider>
+            )}
+          </div>
+        </UrlParamsProvider>
+      </HostBridgeProvider>
+    </I18nextProvider>
+  );
+};

component/localization.test.ts

@@ -0,0 +1,46 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { describe, expect, test } from "vitest";
+
+import { supportedLanguages, translationsBackend } from "./localization";
+
+const read = async (
+  language: string,
+  namespace = "app",
+): Promise<Record<string, unknown>> =>
+  await new Promise((resolve, reject) =>
+    translationsBackend.read(language, namespace, (error, data) => {
+      if (error) reject(error);
+      else resolve(data as Record<string, unknown>);
+    }),
+  );
+
+describe("component translations", () => {
+  test("offer every language in locales/, tagged as its directory is", () => {
+    expect(supportedLanguages).toContain("en");
+    expect(supportedLanguages).toContain("de");
+    expect(supportedLanguages).toContain("zh-Hans");
+    expect(new Set(supportedLanguages).size).toBe(supportedLanguages.length);
+  });
+
+  test("load a language's translations on demand", async () => {
+    const de = await read("de");
+    expect(de).toHaveProperty("action");
+    expect(de).not.toEqual(await read("en"));
+  });
+
+  test("refuse a language there are no translations for", async () => {
+    await expect(read("xx")).rejects.toThrow("No app translations for xx");
+  });
+
+  test("refuse a namespace there are no translations for", async () => {
+    await expect(read("en", "other")).rejects.toThrow(
+      "No other translations for en",
+    );
+  });
+});

component/localization.ts

@@ -0,0 +1,55 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+/**
+ * Translations for Element Call as a component.
+ *
+ * The standalone app fetches its locale files at runtime from URLs its own
+ * build emits, which a host serving the library from somewhere else could not
+ * resolve. The component instead has the bundler split every locale into a
+ * chunk of its own, loaded the first time its language is asked for; English,
+ * the fallback, is bundled in so that the first paint never waits for it.
+ */
+
+import { type BackendModule, type ResourceKey } from "i18next";
+
+import { languageOfLocalePath } from "../src/utils/i18n";
+
+/** Every locale, as a lazily imported module. */
+const translations = import.meta.glob<{ default: ResourceKey }>(
+  "../locales/*/app.json",
+);
+
+/**
+ * The languages Element Call can be shown in, as BCP 47 tags — `en`, `de`,
+ * `zh-Hans` and so on. A language that is not one of these falls back to its
+ * base language where there is one (`de-AT` to `de`), and to English otherwise.
+ */
+export const supportedLanguages: readonly string[] = [
+  ...new Set(Object.keys(translations).map(languageOfLocalePath)),
+];
+
+/** Loads translations on demand. */
+export const translationsBackend: BackendModule = {
+  type: "backend",
+  init(): void {},
+  read(language: string, namespace: string, callback): void {
+    const load = translations[`../locales/${language}/${namespace}.json`];
+    if (load === undefined) {
+      callback(new Error(`No ${namespace} translations for ${language}`), null);
+      return;
+    }
+    load().then(
+      (module) => callback(null, module.default),
+      (error: unknown) =>
+        callback(
+          error instanceof Error ? error : new Error(String(error)),
+          null,
+        ),
+    );
+  },
+};

component/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@element-hq/element-call-component",
+  "version": "0.0.0",
+  "description": "Element Call as a React component. Consumed straight from the repository as a git dependency (github:element-hq/element-call#<ref>&path:/component): the host's package manager runs `prepare`, which builds `dist/`.",
+  "license": "SEE LICENSE IN ../README.md",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/element-hq/element-call",
+    "directory": "component"
+  },
+  "type": "module",
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/element-call.js",
+  "module": "./dist/element-call.js",
+  "types": "./dist/types/component/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/component/index.d.ts",
+      "default": "./dist/element-call.js"
+    },
+    "./style.css": "./dist/element-call.css"
+  },
+  "sideEffects": [
+    "*.css"
+  ],
+  "scripts": {
+    "prepare": "cd .. && pnpm install --frozen-lockfile && pnpm build:component"
+  },
+  "peerDependencies": {
+    "livekit-client": "^2.18.1",
+    "matrix-js-sdk": "*",
+    "react": "^19",
+    "react-dom": "^19"
+  }
+}

component/pnpm-lock.yaml

@@ -0,0 +1,9 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: false
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .: {}

component/pnpm-workspace.yaml

@@ -0,0 +1,14 @@
+# Makes `component/` a pnpm project of its own rather than a directory inside
+# the repository's workspace. That matters when a host installs the component
+# straight from this repository (`github:element-hq/element-call#…&path:/component`):
+# pnpm prepares such a dependency by running `pnpm install` in this directory,
+# and only a project root gets its `prepare` script (see package.json) run, which
+# is what builds `dist/`. Inside the repository's own workspace the install
+# would silently target the repository instead and build nothing.
+#
+# Consequence for development: pnpm commands run from within this directory see
+# this project, not the repository; run them from the repository root.
+
+# Nothing to install here: the peers in package.json are the host's, and the
+# build runs against the repository's own node_modules (see `prepare`).
+autoInstallPeers: false

component/tsconfig.build.json

@@ -0,0 +1,20 @@
+{
+  // Declaration output for the component package (`pnpm build:component:types`).
+  // The root tsconfig only type-checks; this one emits `.d.ts` files, and nothing
+  // else, for everything the component's entry point reaches. The layout under
+  // `dist/types` mirrors the repository (`component/index.d.ts`, `src/…`), which
+  // is what `package.json` points its `types` at.
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "emitDeclarationOnly": true,
+    "declaration": true,
+    "declarationMap": false,
+    "rootDir": "..",
+    "outDir": "./dist/types"
+  },
+  // The entry point, plus the ambient declarations (CSS modules, `?react` SVGs,
+  // `import.meta.env`, …) that the sources it reaches rely on.
+  "include": ["./index.tsx", "../src/@types/*.d.ts"],
+  "exclude": []
+}

config/config.devenv.json

@@ -9,8 +9,6 @@
   "matrix_rtc_session": {
     "wait_for_key_rotation_ms": 3000,
     "membership_event_expiry_ms": 180000000,
-    "delayed_leave_event_delay_ms": 18000,
-    "delayed_leave_event_restart_ms": 4000,
     "network_error_retry_ms": 100
   }
 }

config/config.sample.json

@@ -13,8 +13,6 @@
   "matrix_rtc_session": {
     "wait_for_key_rotation_ms": 3000,
     "membership_event_expiry_ms": 180000000,
-    "delayed_leave_event_delay_ms": 18000,
-    "delayed_leave_event_restart_ms": 4000,
     "network_error_retry_ms": 100
   }
 }

config/config_netlify_preview.json

@@ -9,8 +9,6 @@
   "matrix_rtc_session": {
     "wait_for_key_rotation_ms": 3000,
     "membership_event_expiry_ms": 180000000,
-    "delayed_leave_event_delay_ms": 18000,
-    "delayed_leave_event_restart_ms": 4000,
     "network_error_retry_ms": 100
   },
   "posthog": {

config/config_netlify_preview_sdk.json

@@ -9,8 +9,6 @@
   "matrix_rtc_session": {
     "wait_for_key_rotation_ms": 3000,
     "membership_event_expiry_ms": 180000000,
-    "delayed_leave_event_delay_ms": 18000,
-    "delayed_leave_event_restart_ms": 4000,
     "network_error_retry_ms": 100
   }
 }

docs/README.md

@@ -3,8 +3,18 @@
 This folder contains documentation for setup, usage, and development of Element Call.
 
 - [Embedded vs standalone mode](./embedded_standalone.md)
+- [Element Call as a React component (experimental)](../README.md#element-call-as-a-component-experimental)
 - [Url format and parameters](./url_params.md)
 - [Global JS controls](./controls.md)
 - [MatrixRTC modes](./matrix_rtc_modes.md)
 - [Self-Hosting](./self_hosting.md)
 - [Developing with linked packages](./linking.md)
+
+### Writing code for Element Call (agent-readable conventions)
+
+Entry point: [AGENTS.md](../AGENTS.md).
+
+- [Agent workflow](./agents/workflow.md)
+- [Architecture](./agents/architecture.md)
+- [Code style](./agents/code-style.md)
+- [Testing](./agents/testing.md)

docs/agents/architecture.md

@@ -0,0 +1,79 @@
+# Architecture
+
+## Logic lives in view models; components render
+
+- Call logic lives in `src/state/`. A component that derives call state is
+  misplaced logic.
+- Composing behaviors: a factory taking `(scope, ...deps$)`, returning named
+  behaviors plus callbacks. Copy `src/state/LayoutSwitchViewModel.ts`. Prefer this
+  for anything new.
+- Owning a resource: a class taking the scope in its constructor — `MediaDevices`,
+  `MuteStates`, `TileStore`, `Publisher`, `Connection`. Both styles are current;
+  don't convert one to the other in passing.
+- `foo$` is an observable. `Behavior<T>`, an observable with a current value, is
+  the default for anything a view reads.
+
+## The view model / view contract
+
+- Components take `vm: ViewModel<Snapshot>` and read state through `useBehavior`.
+  See `CallFooter`, `InCallView`, `LobbyView`, `SettingsModal`.
+- A snapshot is `Actions & State`; every field becomes a `foo$` behavior, and none
+  is optional.
+- An unavailable action is `undefined`, not a separate `canDoThing` flag — the
+  presence of the callback drives the rendering.
+- Subscribe in an effect only to drive a side effect off an event stream, as
+  `ReactionAudioRenderer` does; never to read state a behavior already holds.
+
+## Scopes own lifetimes
+
+- `ObservableScope` bounds every subscription a view model creates.
+- Reference only the scope defined in the same function; one captured from an
+  enclosing scope outlives its owner, and `no-observablescope-leak` rejects it.
+
+## Nothing reads the page
+
+Element Call can be mounted several times inside a host's React tree, so it owns
+neither window, URL, document nor router. Each seam defaults to the old standalone
+and widget behaviour.
+
+| Never                                         | Use                                                           |
+| --------------------------------------------- | ------------------------------------------------------------- |
+| the `widget` global                           | `useHostBridge()` — `src/HostBridge.ts`                       |
+| `getUrlParams()`, `window.location`           | `useUrlParams()`                                              |
+| `useNavigate("/")`, `<Link to="/">`           | `useLeaveToHome()`, `LeaveToHomeLink`                         |
+| `document.body`                               | `useRootElement()`                                            |
+| `window.innerWidth/Height`, `useMediaQuery`   | `useRootSizeMatches()` in views, `windowSize$` in view models |
+| global `i18next`                              | the instance in `src/utils/i18n.ts`                           |
+| config or analytics reading their environment | `Config.initWith()`, `PosthogAnalytics.configure()`           |
+
+- View models take values as options, never `getUrlParams()`
+  (`callViewModelOptionsFromParams`, `CallViewModelOptions.hostBridge`).
+- The host bridge is the only channel to the host: `createWidgetHostBridge(widget)`,
+  `nullHostBridge` standalone, `useComponentHostBridge`. State a capability
+  (`supportsReactions`, `supportsProfileChanges`); never infer it from being a
+  widget.
+- Shortcuts and portals attach to the root element, so two instances don't fight.
+- Known debt, not precedent: `Grid` measures `window.innerHeight`; `ErrorView`'s
+  reload and `getAbsoluteRoomUrl` use `window.location`; recaptcha appends to
+  `document.body` on the standalone login path.
+
+## Context differences are options, not checks
+
+- Named options with per-intent defaults (`configurationForIntent`), never a
+  runtime check for who is hosting.
+- `controlledAudioDevices`, not the platform, is what makes `MediaDevices` pick
+  `AndroidControlledAudioOutput` / `IOSControlledAudioOutput` over the web
+  `AudioOutput`. Intent presets set it on non-desktop; standalone leaves it off.
+- URL params are a published contract: change one, update `docs/url_params.md`.
+
+## Build targets
+
+Code that builds in only one is a bug.
+
+- `build:full` — standalone app, also widget mode.
+- `build:embedded` — `@element-hq/element-call-embedded`.
+- `build:sdk` — SDK library, entry `sdk/main.ts`.
+- `build:component` — `@element-hq/element-call-component`, sources in `component/`
+  (its own pnpm project; run pnpm from the repo root). Host API is in the README;
+  `pnpm lint:externals` rejects an import of a `react` / `react-dom` /
+  `matrix-js-sdk` / `livekit-client` subpath the externals list omits.

docs/agents/code-style.md

@@ -0,0 +1,74 @@
+# Code style
+
+_Clean Code_ (Robert C. Martin): small functions, intention-revealing names, low
+noise.
+
+## Reuse before you build
+
+Look before you write, in this order:
+
+1. **Compound Web** — `@vector-im/compound-web` for buttons, tooltips, alerts,
+   dialogs, menus, form controls, avatars; icons in
+   `@vector-im/compound-design-tokens/assets/web/icons`.
+2. **This repo** — `src/button/`, `src/components/`, `src/input/`, `src/form/`,
+   `src/tabs/`, and `Modal`, `Avatar`, `Toast`, `Slider`, `ErrorView`,
+   `FullScreenView` at the root of `src/`.
+3. **The nearest existing feature** — grep for the same shape first. A hook is
+   often what you want to extract, not a component.
+
+If nothing fits, name the new shared component in the PR body and say what you
+rejected and why — never add one silently. Extend or parameterise before forking,
+and extract shared logic into a hook both callers use before copying it; if you
+copy, the PR says so.
+
+## Ordering
+
+- **Newspaper order.** Headline first, detail down. A file opens with what it
+  exists to provide.
+- **Stepdown rule.** Caller above callee. A helper used by one function sits
+  beneath it, which needs a `function` declaration, not a `const` arrow. Existing
+  arrow components above their callers are not a pattern to extend — nor to churn.
+- **Suites.** Test cases first, helpers below. Older suites invert this; follow the
+  rule in new ones, don't reorder old ones.
+- **Names.** What a thing means, not what it is made of: `naturalLayout$`, not
+  `computedLayout$`. Comments explain why, never what.
+
+## TypeScript, React and RxJS idiom win on a clash
+
+- Hooks stay unconditional at the top of a component.
+- `useCallback` / `useMemo` dependency arrays sometimes force inlining.
+- An RxJS pipeline stays one expression. Name the behavior, not each operator.
+- A long factory is fine when it reads as a list of named behaviors.
+  `CallViewModel.ts` is long because the domain is.
+- Marble test tables are dense on purpose.
+
+## Enforced by lint
+
+- Copyright header on every file: `Copyright <current year> Element Creations Ltd.`
+  plus the AGPL / commercial SPDX line.
+- `logger` from `matrix-js-sdk/lib/logger`, never `console`, and no top-level
+  `logger.getChild()`. The `console` ban is only enforced under `src/*/**`.
+- No floating or misused promises; async functions typed `Promise<T>`.
+- Inline type imports (`import { type Foo }`), so matrix-js-sdk stays lazily
+  loadable.
+- Deep-import `matrix-js-sdk/lib/<module>` as the codebase does. Banned is the bare
+  `matrix-js-sdk/lib`, `lib/index` and anything under `src/`.
+
+## CSS
+
+- Compound components and `--cpd-*` tokens in CSS modules. A hardcoded colour or px
+  spacing is a design question, not a licence to inline a hex.
+- Size against the root, not the window: `@container element-call (…)` and
+  `cqw` / `cqh`, never `@media (width)` or `vw` / `vh`. Media queries stay correct
+  only in standalone-only views — home, login.
+- Style `[data-element-call-root]`, never `body` or `:root`; the component build
+  makes those stand for the root (`component/build/scopeStylesToRoot.ts`).
+
+## Strings and a11y
+
+- Strings through `t()`: add the key, run `pnpm i18n`, fill `locales/en/app.json`.
+  Other locales come from Localazy; never hand-edit them.
+- `t` from `useTranslation()`, or `src/utils/i18n.ts` outside React. Never the
+  `i18next` global — several instances share a page.
+- Accessible names on controls, `aria-pressed` on toggles, keyboard reachability.
+  `jsx-a11y` rules are errors; `vitest-axe` is available.

docs/agents/testing.md

@@ -0,0 +1,51 @@
+# Testing
+
+Three layers; a user-facing feature needs all three. Unit proves the logic,
+Storybook proves the rendering, e2e proves the feature. Codecov gates 80% on the
+lines a PR touches.
+
+## Unit
+
+- View model tests use `withTestScheduler` + `testScope()` from `src/utils/test.ts`
+  and read as ASCII timelines. Copy `LayoutSwitchViewModel.test.ts`.
+- Component tests use Testing Library, queried by role and accessible name.
+- Reuse the factories in `src/utils/test.ts` — `mockRemoteParticipant`,
+  `mockMatrixRoom`, `mockLivekitRoom`, `MockRTCSession`. Hand-rolled mocks drift.
+- Snapshots live in `__snapshots__/`; update with `pnpm test <Name> -u`.
+- `component/**/*.test.ts` runs in the same jsdom project as `src`.
+
+## Storybook
+
+A deliverable, not documentation: `pnpm test:storybook` runs every story as a real
+browser test in the same CI job as the unit suite. **A UI change without a story is
+incomplete.** Only three stories exist so far, so copy `CallFooter.stories.tsx`.
+
+- Drive the component from a snapshot via `useStaticViewModel`, never internals.
+- One named story per state that matters — loading, error, empty, denied, mobile.
+- Assert in a `play` function with `userEvent` / `expect` from `storybook/test`.
+- Mobile is `globals: { viewport: { value: "mobile2" } }`, not a second component.
+- Expose interesting props through `argTypes`.
+
+`.storybook/preview.tsx` supplies `TooltipProvider`, `src/index.css` and English
+translations. The browser is Playwright's, so a fresh clone needs
+`pnpm playwright install` once.
+
+## End-to-end
+
+- `playwright/*.spec.ts` — standalone, on Chromium and Firefox.
+- `playwright/widget/` — widget mode, where cross-context bugs surface.
+- `playwright/component/` — the component in a host page, via the harness on port
+  3001 that Playwright starts as a second web server. Catches container-relative
+  layout, styles escaping the root, two instances on a page, host-bridge reports.
+- `playwright/mobile/` — Pixel 7, `mobile` project only.
+
+Test what a user observes: the peer sees the change, it survives a reconnect, it is
+right after a reload. Reuse `playwright/spa-helpers.ts`,
+`playwright/widget/test-helpers.ts`, `playwright/fixtures/`.
+
+```sh
+pnpm test                   # unit + storybook
+pnpm backend                # Synapse + LiveKit, required for e2e
+pnpm test:playwright        # or :open
+pnpm dev:component          # component harness, port 3001
+```

docs/agents/workflow.md

@@ -0,0 +1,48 @@
+# Agent workflow
+
+## Scratch files live in `agent-workspace/`
+
+Git-ignored. One kebab-case subfolder per task, matching the branch topic:
+`agent-workspace/<slug>/`.
+
+| File                        | Purpose                                                                          |
+| --------------------------- | -------------------------------------------------------------------------------- |
+| `plan.md`                   | The concrete approach — files, symbols, edit order — once direction is confirmed |
+| `commit-msg.txt`            | `git commit -F agent-workspace/<slug>/commit-msg.txt`                            |
+| `pr-body.md`                | `gh pr create --body-file agent-workspace/<slug>/pr-body.md`                     |
+| `implementation-summary.md` | What was built, decisions, trade-offs                                            |
+| `NN-prompt.md`              | Raw prompt text, numbered, when worth keeping                                    |
+
+- Nothing here is durable. The folder is ignored, so anything worth keeping is
+  promoted into the PR body, a doc, or a feature spec before the task ends.
+- Never write scratch files to the repo root. Stray `load_test_summary.md` and
+  `config.json_` files are what this folder prevents.
+- Start `pr-body.md` from `.github/PULL_REQUEST_TEMPLATE.md` and fill every
+  section.
+- Commit subjects are plain imperative English. No conventional-commits prefixes.
+- A `plan.md` and a feature spec sit at different altitudes; neither replaces the
+  other. A spec in `FEATURES_SPEC/` is durable and deliberately abstract —
+  behaviour, decisions, acceptance criteria — so the feature can be rebuilt against
+  a `main` nobody has seen yet. A plan is one slice of it landing on today's
+  `main`: the paths, symbols and edit order the spec's decisions and criteria must
+  not name. `FEATURES_SPEC/AGENTS.md` wins wherever the two genuinely overlap.
+
+## Hand off before the quality pass
+
+- Implement the change, run the narrowest check that rules out an obviously broken
+  handoff, then stop and ask whether the direction is right.
+- Full `pnpm lint`, the whole suite, coverage and benchmarks come after the
+  direction is confirmed.
+- Wider refactors, extra tests and documentation polish are follow-up work, not
+  part of the first handoff.
+- If a check is needed before feedback, keep it to the touched code and say why.
+
+## Commit and PR readiness
+
+- Commit once the user confirms direction, or asks for one. Not before.
+- Before committing, every gate in [AGENTS.md](../../AGENTS.md#gates) is green and
+  the change is covered at the layers [testing.md](./testing.md) asks for. Read the
+  diff against [code-style.md](./code-style.md).
+- Re-run the whole checklist after any fix. Commit only on green.
+- Once a human has started reviewing, fix forward — never force-push a
+  regeneration over a review in progress.

docs/embedded_standalone.md

@@ -3,6 +3,9 @@
 Element Call is available as two different packages: Full Package and Embedded Package.
 
 The Full Package is designed for standalone use, while the Embedded Package is designed for widget mode only.
+There is also an experimental third option, a build of Element Call as a React component for applications
+that want to render a call inside their own page rather than in an iframe; see
+[Element Call as a component](../README.md#element-call-as-a-component-experimental) in the README.
 
 The table below provides a comparison of the two packages:
 

knip.ts

@@ -9,7 +9,13 @@ import { type KnipConfig } from "knip";
 
 export default {
   vite: {
-    config: ["vite.config.ts", "vite-embedded.config.ts", "vite-sdk.config.ts"],
+    config: [
+      "vite.config.ts",
+      "vite-embedded.config.ts",
+      "vite-sdk.config.ts",
+      "vite-component.config.ts",
+      "vite-component-dev.config.ts",
+    ],
   },
   entry: ["src/main.tsx", "eslint/index.js", "i18next.config.ts"],
   ignoreBinaries: [

locales/en/app.json

@@ -23,6 +23,15 @@
     "upload_file": "Upload file"
   },
   "analytics_notice": "By participating in this beta, you consent to the collection of anonymous data, which we use to improve the product. You can find more information about which data we track in our <2>Privacy Policy</2> and our <6>Cookie Policy</6>.",
+  "audio_menu": {
+    "mic_absent": "No microphone found",
+    "mic_level_active": "Picking up sound",
+    "mic_level_label": "Microphone level",
+    "mic_level_silent": "No sound detected",
+    "mic_permission_denied": "Microphone access is blocked. Allow it in your browser settings.",
+    "mic_unavailable": "Microphone unavailable",
+    "title": "Audio controls"
+  },
   "call_ended_view": {
     "create_account_button": "Create account",
     "create_account_prompt": "<0>Why not finish by setting up a password to keep your account?</0><1>You'll be able to keep your name and set an avatar for use on future calls</1>",
@@ -218,6 +227,7 @@
       "change_device_button": "Change audio device",
       "default": "Default",
       "default_named": "Default <2>({{name}})</2>",
+      "default_named_plain": "Default ({{name}})",
       "handset": "Handset",
       "loudspeaker": "Loudspeaker",
       "microphone": "Microphone",

package.json

@@ -6,6 +6,7 @@
     "dev": "pnpm dev:full",
     "dev:full": "vite",
     "dev:embedded": "vite --config vite-embedded.config.js",
+    "dev:component": "vite --config vite-component-dev.config.ts",
     "build": "pnpm build:full",
     "build:full": "NODE_OPTIONS=--max-old-space-size=16384 vite build",
     "build:full:production": "pnpm build:full",
@@ -16,13 +17,19 @@
     "build:sdk:development": "pnpm build:sdk --mode development",
     "build:sdk": "pnpm build:full --config vite-sdk.config.js",
     "build:sdk:production": "pnpm build:sdk",
+    "build:component": "pnpm build:component:js && pnpm build:component:types",
+    "build:component:js": "pnpm build:full --config vite-component.config.js",
+    "build:component:types": "tsc -p component/tsconfig.build.json",
+    "build:component:production": "pnpm build:component",
+    "build:component:development": "pnpm build:component:js --mode development && pnpm build:component:types",
     "serve": "vite preview",
     "format": "oxfmt",
     "format:check": "oxfmt --check; rc=$?; [[ $rc -ne 0 ]] && printf '\\033[46;30m INFO \\033[0m To fix, run: pnpm format\\n' >&2; exit $rc",
-    "lint": "pnpm lint:types && pnpm lint:oxlint && pnpm lint:knip",
-    "lint:oxlint": "oxlint src playwright",
-    "lint:oxlint-fix": "oxlint --fix src playwright",
+    "lint": "pnpm lint:types && pnpm lint:oxlint && pnpm lint:knip && pnpm lint:externals",
+    "lint:oxlint": "oxlint src component playwright",
+    "lint:oxlint-fix": "oxlint --fix src component playwright",
     "lint:knip": "knip",
+    "lint:externals": "node scripts/check-component-externals.mjs",
     "lint:types": "tsc",
     "i18n": "npx i18next-cli extract",
     "i18n:check": "npx i18next-cli extract --ci",
@@ -81,7 +88,7 @@
     "@vitejs/plugin-react": "^6.0.2",
     "@vitest/browser-playwright": "^4.1.5",
     "@vitest/coverage-v8": "^4.0.18",
-    "@vitest/ui": "4.1.10",
+    "@vitest/ui": "4.1.11",
     "babel-plugin-react-compiler": "^1.0.0",
     "classnames": "^2.3.1",
     "copy-to-clipboard": "^3.3.3",
@@ -101,12 +108,13 @@
     "node-stdlib-browser": "^1.3.1",
     "normalize.css": "^8.0.1",
     "observable-hooks": "^4.2.3",
-    "oxfmt": "^0.61.0",
+    "oxfmt": "^0.66.0",
     "oxlint": "^1.70.0",
     "oxlint-tsgolint": "^0.25.0",
     "pako": "^2.0.4",
     "postcss": "^8.4.41",
     "postcss-preset-env": "^10.0.0",
+    "postcss-selector-parser": "^7.1.1",
     "posthog-js": "1.408.2",
     "qrcode": "^1.5.4",
     "react": "19",

playwright.config.ts

@@ -11,6 +11,8 @@ import { join } from "path";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { COMPONENT_HARNESS_URL } from "./playwright/component/harness.ts";
+
 const baseURL = process.env.USE_DOCKER
   ? "http://localhost:8080"
   : "https://localhost:3000";
@@ -84,6 +86,11 @@ export default defineConfig({
             // enumerateDevices work on CI runners without real hardware.
             "media.navigator.streams.fake": true,
             "media.navigator.permission.disabled": true,
+            // Vite serves HTTPS over HTTP/2, and Firefox intermittently stalls
+            // on Node's HTTP/2 server with a page that never finishes loading
+            // (one run in five or so, locally). Every server in the suite
+            // still speaks HTTP/1.1, so nothing is lost by insisting on it.
+            "network.http.http2.enabled": false,
           },
         },
       },
@@ -115,14 +122,29 @@ export default defineConfig({
   ],
 
   /* Run your local dev server before starting the tests */
-  webServer: {
-    command: "./scripts/playwright-webserver-command.sh",
-    url: baseURL,
-    reuseExistingServer: !process.env.CI,
-    ignoreHTTPSErrors: true,
-    gracefulShutdown: {
-      signal: "SIGTERM",
-      timeout: 500,
+  webServer: [
+    {
+      command: "./scripts/playwright-webserver-command.sh",
+      url: baseURL,
+      reuseExistingServer: !process.env.CI,
+      ignoreHTTPSErrors: true,
+      gracefulShutdown: {
+        signal: "SIGTERM",
+        timeout: 500,
+      },
     },
-  },
+    {
+      // The harness that embeds Element Call as a component. Always a Vite dev
+      // server, whether or not the app itself is being served from Docker,
+      // since there is nothing to build: it is a development page only.
+      command: "pnpm dev:component",
+      url: COMPONENT_HARNESS_URL,
+      reuseExistingServer: !process.env.CI,
+      ignoreHTTPSErrors: true,
+      gracefulShutdown: {
+        signal: "SIGTERM",
+        timeout: 500,
+      },
+    },
+  ],
 });

playwright/audio-menu.spec.ts

@@ -0,0 +1,223 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { expect, type Locator, test } from "@playwright/test";
+
+import { SpaHelpers } from "./spa-helpers";
+
+test("audio menu leaves participants visible while switching output", async ({
+  browser,
+  browserName,
+}) => {
+  test.skip(
+    browserName === "firefox",
+    "Firefox's fake media stream enumerates no audio outputs, so there is nothing to switch.",
+  );
+
+  // Reduced motion disables the animations that make these tests flaky.
+  const creatorContext = await browser.newContext({ reducedMotion: "reduce" });
+  const page = await creatorContext.newPage();
+  await page.goto("/");
+  await SpaHelpers.createCall(page, "Inviter", "Audio menu", true);
+  const inviteLink = await SpaHelpers.getCallInviteLink(page);
+
+  const guestContext = await browser.newContext({ reducedMotion: "reduce" });
+  const guestPage = await guestContext.newPage();
+  await SpaHelpers.joinCallFromInviteLink(guestPage, inviteLink, "Guest");
+
+  await SpaHelpers.expectVideoTilesCount(page, 2);
+
+  // The chevron beside the microphone button opens the audio menu in place.
+  await page.getByRole("button", { name: "Microphone" }).click();
+  const menu = page.getByRole("menu");
+  await expect(
+    menu.getByRole("heading", { name: "Audio controls" }),
+  ).toBeVisible();
+
+  // Pick another output where the browser offers one; where it does not, the
+  // speaker group still names the output in use.
+  const outputs = menu
+    .getByTestId("audio_menu_scroll")
+    .locator('> [role="menuitemradio"]');
+  const count = await outputs.count();
+  if (count > 1) {
+    // Pinned by position: a locator on "the unchecked row" would re-resolve to
+    // the previously active row once the click has moved the check mark.
+    const other = outputs.nth(await firstUncheckedIndex(outputs, count));
+    await other.click();
+    await expect(other).toHaveAttribute("aria-checked", "true");
+    await expect(menu).toBeVisible();
+  } else {
+    await expect(menu.getByTestId("speaker_readonly")).toBeVisible();
+  }
+
+  // Nothing covered the call: the other participant is still on screen with
+  // the menu open, and after it closes.
+  await SpaHelpers.expectVideoTilesCount(page, 2);
+  await page.keyboard.press("Escape");
+  await expect(menu).not.toBeVisible();
+  await SpaHelpers.expectVideoTilesCount(page, 2);
+});
+
+test("level indicator moves with microphone input", async ({
+  browser,
+  browserName,
+}) => {
+  test.skip(
+    browserName === "firefox",
+    "Firefox has no audio backend on the CI runner, so the level stays at zero there. It passes against Firefox elsewhere, including CI's own Docker image over plain HTTP.",
+  );
+  const context = await browser.newContext({ reducedMotion: "reduce" });
+  const page = await context.newPage();
+  await page.goto("/");
+  await SpaHelpers.createCall(page, "Speaker", "Level meter", true);
+  await expect(page.getByTestId("videoTile")).toHaveCount(1);
+
+  await page.getByRole("button", { name: "Microphone" }).click();
+  const meter = page.getByRole("menu").getByRole("meter");
+  await expect(meter).toBeVisible();
+
+  // The browser's fake microphone plays a tone, so the meter has to leave its
+  // resting level while the menu is open.
+  await expect
+    .poll(async () => Number(await meter.getAttribute("aria-valuenow")), {
+      timeout: 15_000,
+    })
+    .toBeGreaterThan(0);
+});
+
+test("audio menu is keyboard operable in a real browser", async ({
+  browser,
+  browserName,
+}) => {
+  test.skip(
+    browserName === "firefox",
+    'Firefox headless drives page.keyboard.press("Tab") unreliably, as reconnect.spec.ts records.',
+  );
+  const context = await browser.newContext({ reducedMotion: "reduce" });
+  const page = await context.newPage();
+  await page.goto("/");
+  await SpaHelpers.createCall(page, "Keys", "Keyboard menu", true);
+  await expect(page.getByTestId("videoTile")).toHaveCount(1);
+
+  // Open from the chevron; the first device row takes focus.
+  await page.getByRole("button", { name: "Microphone" }).focus();
+  await page.keyboard.press("Enter");
+  const menu = page.getByRole("menu");
+  await expect(menu).toBeVisible();
+  const rows = menu.getByRole("menuitemradio");
+  await expect(rows.first()).toBeFocused();
+
+  // Arrow keys walk the device rows, where the browser lists more than one.
+  if ((await rows.count()) > 1) {
+    await page.keyboard.press("ArrowDown");
+    await expect(rows.nth(1)).toBeFocused();
+  }
+
+  // Tab reaches the meter and then the slider; arrows adjust the slider and
+  // leave the menu open.
+  await page.keyboard.press("Tab");
+  await expect(menu.getByRole("meter")).toBeFocused();
+  await page.keyboard.press("Tab");
+  const slider = menu.getByRole("slider");
+  await expect(slider).toBeFocused();
+  const before = Number(await slider.getAttribute("aria-valuenow"));
+  await page.keyboard.press("ArrowRight");
+  await expect
+    .poll(async () => Number(await slider.getAttribute("aria-valuenow")))
+    .toBeGreaterThan(before);
+  await expect(menu).toBeVisible();
+
+  // Shift+Tab goes back; Escape closes.
+  await page.keyboard.press("Shift+Tab");
+  await expect(menu.getByRole("meter")).toBeFocused();
+  await page.keyboard.press("Escape");
+  await expect(menu).not.toBeVisible();
+});
+
+test("audio menu stays inside a short window", async ({ browser }) => {
+  const context = await browser.newContext({
+    reducedMotion: "reduce",
+    viewport: { width: 1280, height: 560 },
+  });
+  const page = await context.newPage();
+  await page.goto("/");
+  await SpaHelpers.createCall(page, "Devices", "Long lists", true);
+  await page.getByTestId("videoTile").first().waitFor();
+
+  await page.getByRole("button", { name: "Microphone" }).focus();
+  await page.keyboard.press("Enter");
+  const menu = page.getByRole("menu");
+  await expect(menu).toBeVisible();
+
+  // However many devices the browser reports, the menu fits the window and
+  // the heading and the slider are on screen with it. How many devices that
+  // is differs between browsers, so the case where the lists actually
+  // overflow is covered by the CallFooter "With Many Devices" story, which
+  // fixes the device count.
+  await expect(menu).toBeInViewport({ ratio: 1 });
+  await expect(
+    menu.getByRole("heading", { name: "Audio controls" }),
+  ).toBeInViewport({ ratio: 1 });
+  await expect(menu.getByRole("slider")).toBeInViewport({ ratio: 1 });
+
+  // The menu itself never becomes the scroller: that would carry the heading
+  // out of view, which is what the scroll area exists to prevent.
+  await expect
+    .poll(async () => menu.evaluate((el) => el.scrollHeight <= el.clientHeight))
+    .toBe(true);
+});
+
+test("the focus border follows the keyboard and not the pointer", async ({
+  browser,
+}) => {
+  const context = await browser.newContext({ reducedMotion: "reduce" });
+  const page = await context.newPage();
+  await page.goto("/");
+  await SpaHelpers.createCall(page, "Focus", "Focus border", true);
+  await page.getByTestId("videoTile").first().waitFor();
+
+  await page.getByRole("button", { name: "Microphone" }).click();
+  const menu = page.getByRole("menu");
+  await expect(menu).toBeVisible();
+
+  // However many devices this browser reports, there is at least one row.
+  const row = menu.getByRole("menuitemradio").first();
+  const box = await row.boundingBox();
+  if (box === null) throw new Error("Expected the row to be laid out");
+  const centre = { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+  const borderOfFocused = async (): Promise<string> =>
+    page.evaluate(() => {
+      const el = document.activeElement;
+      return el === null ? "none" : getComputedStyle(el).outlineStyle;
+    });
+
+  // Reached with the pointer: the hover background carries it, no border.
+  await page.mouse.move(centre.x, centre.y);
+  await expect.poll(borderOfFocused).toBe("none");
+
+  // Reached with the keyboard: a border marks where the keyboard is. The menu
+  // moves focus to whatever the pointer is over, so the browser cannot tell
+  // these two apart on its own.
+  await page.keyboard.press("ArrowDown");
+  await expect.poll(borderOfFocused).toBe("solid");
+
+  // And gone again on the next movement of the pointer. A point the pointer
+  // is not already at, so that the move is one.
+  await page.mouse.move(centre.x + 4, centre.y + 2);
+  await expect.poll(borderOfFocused).toBe("none");
+});
+
+async function firstUncheckedIndex(
+  rows: Locator,
+  count: number,
+): Promise<number> {
+  for (let i = 0; i < count; i++) {
+    if ((await rows.nth(i).getAttribute("aria-checked")) === "false") return i;
+  }
+  throw new Error("every output row is marked active");
+}

playwright/component/component-call.spec.ts

@@ -0,0 +1,285 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { expect, type Locator, type Page, test } from "@playwright/test";
+
+import {
+  createUserAndRoom,
+  expectWithin,
+  resizeContainer,
+  startHarness,
+} from "./harness.ts";
+import { SpaHelpers } from "../spa-helpers.ts";
+
+/**
+ * Element Call embedded as a React component, driven through the development
+ * harness in `component/dev`.
+ *
+ * What these cover that the widget tests cannot is everything that follows from
+ * sharing a page with a host: whether Element Call stays inside the space it
+ * was given, and whether two of it can exist at once. As a widget, the iframe
+ * guaranteed both.
+ */
+
+// Each test signs in twice, sets up crypto twice and syncs twice before
+// anything is on screen, and then waits for media to connect; the waits below
+// are sized for that, so the tests have to be too
+test.describe.configure({ timeout: 180_000 });
+
+/** The settings button, whichever of the two the footer is currently showing. */
+function settingsButton(pane: Locator): Locator {
+  return pane
+    .getByTestId("settings-bottom-left")
+    .or(pane.getByTestId("settings-bottom-center"))
+    .filter({ visible: true })
+    .first();
+}
+
+test("holds a call between two components on one page", async ({ page }) => {
+  const { username, roomId } = await createUserAndRoom("twocomponents");
+  const panes = await startHarness(page, username, roomId);
+
+  // Each component shows a lobby of its own, and neither has joined anything
+  // just by being rendered
+  for (const index of [0, 1])
+    await expect(panes.nth(index).getByTestId("lobby_joinCall")).toBeVisible({
+      timeout: 60_000,
+    });
+
+  for (const index of [0, 1])
+    await panes.nth(index).getByTestId("lobby_joinCall").click();
+
+  // Two devices of one account, so each component should see itself and the
+  // other. This is the part that proves two Element Calls in one page are two
+  // calls, and not one shared thing wearing two hats.
+  for (const index of [0, 1])
+    await expect(panes.nth(index).getByTestId("videoTile")).toHaveCount(2, {
+      timeout: 60_000,
+    });
+});
+
+test("keeps its modals inside the container it was given", async ({ page }) => {
+  const { username, roomId } = await createUserAndRoom("containment");
+  const panes = await startHarness(page, username, roomId);
+  const pane = panes.first();
+  const container = pane.getByTestId("call-container");
+
+  // In the flat container the harness gives it by default, Element Call hides
+  // its controls a few seconds after the call starts, as it would in a flat
+  // window. A full-size container keeps them on screen to be clicked.
+  await resizeContainer(container, { width: 900, height: 640 });
+  await pane.getByTestId("lobby_joinCall").click({ timeout: 60_000 });
+  await expect(pane.getByTestId("footer-container")).toBeVisible({
+    timeout: 60_000,
+  });
+
+  // Both of these are positioned `fixed`, and were centred on the window
+  // rather than the container until it was made a containing block. The
+  // settings dialog spilled over the host's interface; the reaction picker sat
+  // at 82vh, which put it below the container entirely and so out of sight.
+  await settingsButton(pane).click();
+  await expectWithin(pane.getByRole("dialog"), container);
+  await pane.getByTestId("modal_close").click();
+
+  await pane.getByRole("button", { name: "Reactions" }).click();
+  await expectWithin(
+    pane.getByRole("dialog", { name: "Pick reaction" }),
+    container,
+  );
+});
+
+test("keeps the call inside the container, wherever the host put it", async ({
+  page,
+}) => {
+  const { username, roomId } = await createUserAndRoom("tileswithin");
+  const panes = await startHarness(page, username, roomId);
+  const pane = panes.first();
+  const container = pane.getByTestId("call-container");
+
+  // Large enough for the layout switch to be offered
+  await resizeContainer(container, { width: 900, height: 640 });
+  await pane.getByTestId("lobby_joinCall").click({ timeout: 60_000 });
+  await expect(pane.getByTestId("footer-container")).toBeVisible({
+    timeout: 60_000,
+  });
+
+  // The spotlight layout draws its tile in the fixed grid, which is positioned
+  // against Element Call's root rather than laid out in flow. The harness puts
+  // the container below a header of its own, so a grid offset measured from
+  // the top of the page instead of from the root would land the tile on top of
+  // the footer and out of the bottom of the container.
+  await pane.getByRole("radio", { name: "Spotlight" }).check();
+  const tile = pane.getByTestId("videoTile").first();
+  await expect(tile).toBeVisible({ timeout: 60_000 });
+  await expectWithin(tile, container);
+});
+
+test("leaves the host's own page unstyled", async ({ page }) => {
+  const { username, roomId } = await createUserAndRoom("hoststyles");
+  const panes = await startHarness(page, username, roomId);
+  await expect(panes.first().getByTestId("lobby_joinCall")).toBeVisible({
+    timeout: 60_000,
+  });
+
+  // Element Call's stylesheet is written for a page of its own: normalize.css
+  // gives `html` a line height, Compound gives `body` its font and feature
+  // settings, and the design tokens live on `:root`. None of that may reach the
+  // host's document — the harness sets none of these itself, so anything other
+  // than the browser's defaults here came from us.
+  const host = await page.evaluate(() => {
+    const html = getComputedStyle(document.documentElement);
+    const body = getComputedStyle(document.body);
+    return {
+      lineHeight: html.lineHeight,
+      fontFeatureSettings: body.fontFeatureSettings,
+      token: html.getPropertyValue("--cpd-color-text-primary"),
+    };
+  });
+  expect(host).toEqual({
+    lineHeight: "normal",
+    fontFeatureSettings: "normal",
+    token: "",
+  });
+
+  // While inside the container, the same rules do apply
+  const root = panes.first().locator("[data-element-call-root]");
+  await expect(root).toHaveCSS("font-feature-settings", /"kern"/);
+});
+
+test("tells its host what it is doing", async ({ page }) => {
+  const { username, roomId } = await createUserAndRoom("hostbridge");
+  const panes = await startHarness(page, username, roomId);
+  const pane = panes.first();
+  const log = page.getByTestId("bridge-log");
+
+  // Every component reports to its host through the bridge, whether that host
+  // is a widget container or an application embedding it directly
+  await expect(log).toContainText("contentLoaded", { timeout: 60_000 });
+
+  await pane.getByTestId("lobby_joinCall").click({ timeout: 60_000 });
+  await expect(log).toContainText("notifyJoined", { timeout: 60_000 });
+  await expect(log).toContainText("setAlwaysOnScreen(true)", {
+    timeout: 60_000,
+  });
+
+  // And takes instructions back: the host asking for a mute should come back
+  // as the component reporting the new state
+  await pane.getByRole("button", { name: "Mute" }).click();
+  await expect(log).toContainText("notifyDeviceMute(audio: false", {
+    timeout: 30_000,
+  });
+});
+
+test("lays itself out for the space it is given, not the page", async ({
+  page,
+}) => {
+  const { username, roomId } = await createUserAndRoom("containersize");
+  const panes = await startHarness(page, username, roomId);
+  const pane = panes.first();
+  const container = pane.getByTestId("call-container");
+  const call = pane.locator("[data-layout]");
+
+  await pane.getByTestId("lobby_joinCall").click({ timeout: 60_000 });
+  await expect(call).toBeVisible({ timeout: 60_000 });
+  await expect(call).not.toHaveAttribute("data-layout", "pip");
+
+  // As a widget, Element Call's container and its window were one and the same:
+  // a host wanting a picture-in-picture made the iframe small, and Element Call
+  // saw the window shrink. A component gets no such signal from the window,
+  // which stays as large as it ever was; only the container changes.
+  await resizeContainer(container, { width: 300, height: 300 });
+  await expect(call).toHaveAttribute("data-layout", "pip");
+
+  await resizeContainer(container, { width: 900, height: 700 });
+  await expect(call).not.toHaveAttribute("data-layout", "pip");
+});
+
+/**
+ * The shape of a call at whatever size it has been given: the layout it chose,
+ * how much of the height the tile and the footer take, and which controls the
+ * footer shows. Two calls with the same shape look the same, participants aside.
+ */
+async function callShape(scope: Page | Locator): Promise<{
+  layout: string | null;
+  tileHeight: number;
+  footerHeight: number;
+  buttons: (string | null)[];
+}> {
+  const call = scope.locator("[data-layout]");
+  const footer = scope.getByTestId("footer-container");
+  await expect(footer).toBeVisible();
+  // The tile arrives with the media connection, which can take a while
+  const tile = scope.getByTestId("videoTile").first();
+  await expect(tile).toBeVisible({ timeout: 60_000 });
+  const tileBox = (await tile.boundingBox())!;
+  const footerBox = (await footer.boundingBox())!;
+  // Buttons and switches alike: the mute controls are switches
+  const buttons = await footer
+    .locator("button")
+    .filter({ visible: true })
+    .evaluateAll((elements) =>
+      elements.map((element) => element.getAttribute("aria-label")),
+    );
+  return {
+    layout: await call.getAttribute("data-layout"),
+    tileHeight: Math.round(tileBox.height),
+    footerHeight: Math.round(footerBox.height),
+    buttons,
+  };
+}
+
+test("looks the same in a small container as in a small window", async ({
+  page,
+  browser,
+}) => {
+  // Two calls to set up, one of them through the harness's two logins
+  test.setTimeout(300_000);
+  const size = { width: 300, height: 300 };
+
+  // The reference is Element Call owning a window of that size, which is what
+  // a mobile app's webview or a browser's picture-in-picture gives it, and
+  // what its small-window styling was written for.
+  // No permissions to grant: each browser is launched with fake media that is
+  // handed out without asking (see playwright.config.ts), and Firefox rejects
+  // a request for `camera` or `microphone` outright
+  const referenceContext = await browser.newContext({
+    viewport: size,
+    ignoreHTTPSErrors: true,
+  });
+  const referencePage = await referenceContext.newPage();
+  await referencePage.goto("/");
+  await SpaHelpers.createCall(referencePage, "Reference", "smallwindow", true);
+  const reference = await callShape(referencePage);
+  await referencePage.screenshot({
+    path: test.info().outputPath("small-window.png"),
+  });
+
+  // The component gets a container of that size, in a window that is far larger
+  const { username, roomId } = await createUserAndRoom("smallcontainer");
+  const panes = await startHarness(page, username, roomId);
+  const pane = panes.first();
+  const container = pane.getByTestId("call-container");
+  await resizeContainer(container, size);
+  await pane.getByTestId("lobby_joinCall").click({ timeout: 60_000 });
+  await expect(pane.locator("[data-layout]")).toBeVisible({ timeout: 60_000 });
+  const component = await callShape(pane);
+  await container.screenshot({
+    path: test.info().outputPath("small-container.png"),
+  });
+  await referenceContext.close();
+
+  // The breakpoints in Element Call's stylesheets are container queries, so a
+  // small container gets the compact footer a small window does, rather than
+  // the full-width one the window's own size would call for
+  expect(component).toEqual(reference);
+  // And that footer is the compact one: a single row of controls, not the
+  // full-height bar with its logo and layout switch that a large window gets
+  expect(component.footerHeight).toBeLessThan(size.height / 3);
+  expect(component.tileHeight + component.footerHeight).toBeLessThanOrEqual(
+    size.height,
+  );
+});

playwright/component/harness.ts

@@ -0,0 +1,126 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { expect, type Locator, type Page } from "@playwright/test";
+
+import { SynapseAdmin } from "../utils/synapse-admin.ts";
+
+/**
+ * Where the component harness is served — `component/dev`, which embeds Element
+ * Call the way a host application would. Not the `baseURL` the rest of the
+ * suite uses: these tests drive a page that contains Element Call rather than
+ * Element Call itself.
+ */
+export const COMPONENT_HARNESS_URL = "https://localhost:3001";
+
+const HOMESERVER_URL = "https://synapse.m.localhost";
+const PASSWORD = "foobarbaz1!";
+
+/**
+ * Registers a user through the Synapse admin API and creates a room for it to
+ * call in, without touching a browser. The harness signs into this account
+ * twice, giving two devices in one page and so a real call between the two
+ * components.
+ */
+export async function createUserAndRoom(
+  name: string,
+): Promise<{ username: string; roomId: string }> {
+  const username = `${name}_${Date.now()}`;
+  const { access_token: accessToken } = await SynapseAdmin.forHomeserver(
+    HOMESERVER_URL,
+  ).registerUser(username, PASSWORD, name);
+
+  const response = await fetch(
+    `${HOMESERVER_URL}/_matrix/client/v3/createRoom`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ name: `${name}'s call`, preset: "private_chat" }),
+    },
+  );
+  if (!response.ok)
+    throw new Error(
+      `Could not create a room: ${response.status} ${await response.text()}`,
+    );
+  const { room_id: roomId } = (await response.json()) as { room_id: string };
+
+  return { username, roomId };
+}
+
+/**
+ * Opens the harness signed in as the given user, and waits for both embedded
+ * calls to appear.
+ *
+ * @returns The two containers the host gave Element Call, in order.
+ */
+export async function startHarness(
+  page: Page,
+  username: string,
+  roomId: string,
+): Promise<Locator> {
+  const query = new URLSearchParams({
+    homeserver: HOMESERVER_URL,
+    username,
+    password: PASSWORD,
+    room: roomId,
+  });
+  await page.goto(`${COMPONENT_HARNESS_URL}/?${query.toString()}`);
+  await page.getByRole("button", { name: "Start" }).click();
+
+  const panes = page.getByTestId("call-pane");
+  // Two logins, two crypto setups and two initial syncs happen first
+  await expect(panes).toHaveCount(2, { timeout: 120_000 });
+  return panes;
+}
+
+/**
+ * Asserts that one element is drawn entirely inside another.
+ *
+ * This is the check that being a component rather than an iframe costs us: an
+ * iframe could not paint outside itself whatever its stylesheets said, whereas
+ * a component shares the page and has to be made to stay put.
+ */
+export async function expectWithin(
+  inner: Locator,
+  outer: Locator,
+): Promise<void> {
+  await expect(inner).toBeVisible();
+  const innerBox = await inner.boundingBox();
+  const outerBox = await outer.boundingBox();
+  if (innerBox === null || outerBox === null)
+    throw new Error("Expected both elements to be laid out");
+
+  // A pixel of slack, for subpixel layout
+  const slack = 1;
+  expect(innerBox.x).toBeGreaterThanOrEqual(outerBox.x - slack);
+  expect(innerBox.y).toBeGreaterThanOrEqual(outerBox.y - slack);
+  expect(innerBox.x + innerBox.width).toBeLessThanOrEqual(
+    outerBox.x + outerBox.width + slack,
+  );
+  expect(innerBox.y + innerBox.height).toBeLessThanOrEqual(
+    outerBox.y + outerBox.height + slack,
+  );
+}
+
+/**
+ * Gives one of the harness's containers a new size. Element Call lays itself
+ * out for the size of its container, so this is how a test puts it into a
+ * particular mode: a flat or narrow one, a picture-in-picture, or a full-size
+ * window, without the window itself changing at all.
+ */
+export async function resizeContainer(
+  container: Locator,
+  size: { width: number; height: number },
+): Promise<void> {
+  await container.evaluate((element, { width, height }) => {
+    element.style.width = `${width}px`;
+    element.style.height = `${height}px`;
+  }, size);
+}

playwright/mobile/audio-menu-mobile.spec.ts

@@ -0,0 +1,35 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { expect, test } from "@playwright/test";
+
+test("no audio menu during a call on mobile", async ({ page }) => {
+  await page.goto("/");
+  await page.getByTestId("home_callName").fill("Audio menu");
+  await page.getByTestId("home_displayName").fill("Mobile");
+  await page.getByTestId("home_go").click();
+  await expect(page.getByTestId("lobby_joinCall")).toBeVisible();
+
+  // Before joining, the microphone chevron exists and opens the full menu.
+  const chevron = page.getByRole("button", { name: "Microphone" });
+  await expect(chevron).toBeVisible();
+  await chevron.click();
+  // On mobile the menu is a drawer named after its title rather than headed
+  // by it.
+  const menu = page.getByRole("menu", { name: "Audio controls" });
+  await expect(menu).toBeVisible();
+  await expect(menu.getByRole("meter")).toBeVisible();
+  await expect(menu.getByRole("slider")).toBeVisible();
+  await page.keyboard.press("Escape");
+  await expect(menu).not.toBeVisible();
+
+  // During the call, the microphone button stands alone: no chevron, no menu.
+  await page.getByTestId("lobby_joinCall").click();
+  await expect(page.getByTestId("incall_mute")).toBeVisible();
+  await expect(page.getByTestId("incall_leave")).toBeVisible();
+  await expect(chevron).toHaveCount(0);
+});

pnpm-workspace.yaml

@@ -1,3 +1,7 @@
+supportedArchitectures:
+  os: [current, linux]
+  cpu: [current, arm64]
+  libc: [current, glibc]
 minimumReleaseAgeExclude:
   - "@vector-im/compound-design-tokens"
   - "@vector-im/compound-web"

scripts/check-component-externals.mjs

@@ -0,0 +1,140 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+/**
+ * Checks that the component build leaves the packages a host must supply to
+ * the host.
+ *
+ * A host application already has React, the Matrix SDK and LiveKit, and a
+ * second copy of any of them is worse than dead weight: React would hold two
+ * sets of hooks, and the Matrix client would run two sync loops. So the
+ * component build lists them as external — but that list has to name every
+ * subpath, since the bundler silently ignores the pattern and callback forms
+ * of the option, and an import it does not cover is bundled with no warning at
+ * all. That is the failure this guards against.
+ *
+ * It reads the list from the build config itself, so there is one copy of it,
+ * and compares it against every import of those packages in the source.
+ *
+ * The comparison is deliberately over-approximate: it looks at all of `src`
+ * rather than only the modules the component actually pulls in, so it will
+ * sometimes ask for a subpath that only the standalone app imports. Listing
+ * one the component never imports costs nothing — the bundler ignores it —
+ * whereas missing one costs a duplicate package.
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadConfigFromFile } from "vite";
+
+const CONFIG = "vite-component.config.ts";
+const SOURCES = ["src", "component"];
+
+/** The packages whose duplication would break a host, rather than merely enlarge it. */
+const MUST_BE_EXTERNAL = [
+  "react",
+  "react-dom",
+  "matrix-js-sdk",
+  "livekit-client",
+];
+
+const isTestFile = (name) =>
+  name.includes(".test.") || name.includes(".stories.");
+
+/** Every source file under the given directories, recursively. */
+async function* sourceFiles(dir) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) yield* sourceFiles(path);
+    else if (/\.(ts|tsx)$/.test(entry.name) && !isTestFile(entry.name))
+      yield path;
+  }
+}
+
+/**
+ * The module specifiers a source file imports. Covers `from "…"` (which is
+ * both static imports and re-exports), bare `import "…"` for side effects, and
+ * dynamic `import("…")`.
+ */
+function imports(source) {
+  const specifiers = [];
+  for (const pattern of [
+    /\bfrom\s*["']([^"']+)["']/g,
+    /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g,
+    /^\s*import\s+["']([^"']+)["']/gm,
+  ])
+    for (const [, specifier] of source.matchAll(pattern))
+      specifiers.push(specifier);
+  return specifiers;
+}
+
+/**
+ * Whether a specifier is an import of one of the packages we care about.
+ *
+ * Imports carrying a resource query — `?worker`, `?inline` and friends — are
+ * not, whatever package they name. Those ask the bundler for a script to run
+ * in a context of its own, which has to be self-contained and shares no state
+ * with the host's copy of anything. Worker sub-builds do not inherit this
+ * option anyway.
+ */
+const mustBeExternal = (specifier) =>
+  !specifier.includes("?") &&
+  MUST_BE_EXTERNAL.some(
+    (pkg) => specifier === pkg || specifier.startsWith(`${pkg}/`),
+  );
+
+const loaded = await loadConfigFromFile(
+  { command: "build", mode: "production" },
+  CONFIG,
+);
+if (loaded === null) {
+  console.error(`Could not load ${CONFIG}`);
+  process.exit(1);
+}
+const declared = new Set(loaded.config.build?.rollupOptions?.external ?? []);
+if (declared.size === 0) {
+  console.error(
+    `${CONFIG} declares nothing external. Either the option moved, or the ` +
+      `list is empty; either way this check is not looking at what it thinks.`,
+  );
+  process.exit(1);
+}
+
+// Where each missing specifier is imported, so the message can point at it
+const missing = new Map();
+const seen = new Set();
+for (const dir of SOURCES)
+  for await (const file of sourceFiles(dir)) {
+    const source = await readFile(file, "utf8");
+    for (const specifier of imports(source)) {
+      if (!mustBeExternal(specifier)) continue;
+      seen.add(specifier);
+      if (declared.has(specifier)) continue;
+      const files = missing.get(specifier) ?? [];
+      files.push(file);
+      missing.set(specifier, files);
+    }
+  }
+
+if (missing.size > 0) {
+  console.error(
+    `${CONFIG} does not declare these imports external, so the component ` +
+      `build would bundle its own copy of them:\n`,
+  );
+  for (const [specifier, files] of [...missing].sort())
+    console.error(`  ${specifier}\n    imported by ${files.join(", ")}`);
+  console.error(`\nAdd each one to the \`external\` list in ${CONFIG}.`);
+  process.exit(1);
+}
+
+// Deliberately no complaint about declarations nothing imports. Some of them
+// cannot be seen from the source at all — `react/jsx-runtime` is injected by
+// the JSX transform — and an extra declaration is inert, so there is nothing
+// to warn about.
+console.log(
+  `${declared.size} external declarations cover all ${seen.size} imports of ${MUST_BE_EXTERNAL.join(", ")}.`,
+);

sdk/main.ts

@@ -46,7 +46,10 @@ import {
 // Can this be done in the tsconfig.json
 import { type TextStreamInfo } from "../node_modules/livekit-client/dist/src/room/types";
 import { type Behavior, constant } from "../src/state/Behavior";
-import { createCallViewModel$ } from "../src/state/CallViewModel/CallViewModel";
+import {
+  callViewModelOptionsFromParams,
+  createCallViewModel$,
+} from "../src/state/CallViewModel/CallViewModel";
 import { ObservableScope } from "../src/state/ObservableScope";
 import { getUrlParams } from "../src/UrlParams";
 import { MuteStates } from "../src/state/MuteStates";
@@ -54,12 +57,10 @@ import { MediaDevices } from "../src/state/MediaDevices";
 import { E2eeType } from "../src/e2ee/e2eeType";
 import { currentAndPrev, TEXT_LK_TOPIC, tryMakeSticky } from "./helper";
 import { logger as rootLogger } from "matrix-js-sdk/lib/logger";
-import {
-  ElementWidgetActions,
-  widget as _widget,
-  initializeWidget,
-} from "../src/widget";
+import { initializeWidget } from "../src/widget";
 import { type Connection } from "../src/state/CallViewModel/remoteMembers/Connection";
+import { createWidgetHostBridge } from "../src/HostBridge";
+import { observeElementSize$ } from "../src/utils/elementSize";
 
 interface MatrixRTCSdk {
   /**
@@ -109,14 +110,15 @@ export async function createMatrixRTCSdk(
   const scope = new ObservableScope();
 
   // widget client
-  initializeWidget(application, true);
-  const widget = _widget;
+  const widget = initializeWidget(application, true);
   if (!widget) throw Error("No widget. This webapp can only start as a widget");
   const client = await widget.client;
+  const hostBridge = createWidgetHostBridge(widget);
   logger.info("client created");
 
   // url params
-  const { roomId } = getUrlParams();
+  const urlParams = getUrlParams();
+  const { roomId, controlledAudioDevices, callIntent } = urlParams;
   if (roomId === null) throw Error("could not get roomId from url params");
   const room = client.getRoom(roomId);
   if (room === null) throw Error("could not get room from client");
@@ -128,11 +130,16 @@ export async function createMatrixRTCSdk(
   const rtcSession = rtcSessionManager.getRoomSession(room);
 
   // media devices
-  const mediaDevices = new MediaDevices(scope);
-  const muteStates = new MuteStates(scope, mediaDevices, {
-    audioEnabled: false,
-    videoEnabled: false,
+  const mediaDevices = new MediaDevices(scope, {
+    controlledAudioDevices,
+    callIntent,
   });
+  const muteStates = new MuteStates(
+    scope,
+    mediaDevices,
+    { audioEnabled: false, videoEnabled: false },
+    hostBridge,
+  );
 
   // call view model
   const callViewModel = createCallViewModel$(
@@ -141,7 +148,13 @@ export async function createMatrixRTCSdk(
     room,
     mediaDevices,
     muteStates,
-    { encryptionSystem: { kind: E2eeType.PER_PARTICIPANT } },
+    {
+      ...callViewModelOptionsFromParams(urlParams),
+      encryptionSystem: { kind: E2eeType.PER_PARTICIPANT },
+      hostBridge,
+      // The SDK owns its page, so the body is the space it has
+      windowSize$: scope.behavior(observeElementSize$(document.body)),
+    },
     of({}),
     of({}),
     constant({ supported: false, processor: undefined }),
@@ -282,18 +295,17 @@ export async function createMatrixRTCSdk(
       });
       await leaveResolver.promise;
       logger.info("send Unstick");
-      await widget.api
+      await hostBridge
         .setAlwaysOnScreen(false)
-        .catch((e) =>
-          logger.error(
-            "Failed to set call widget `alwaysOnScreen` to false",
-            e,
-          ),
+        .catch((e: unknown) =>
+          logger.error("Failed to set `alwaysOnScreen` to false", e),
         );
       logger.info("send Close");
-      await widget.api.transport
-        .send(ElementWidgetActions.Close, {})
-        .catch((e) => logger.error("Failed to send close action", e));
+      await hostBridge
+        .close?.()
+        .catch((e: unknown) =>
+          logger.error("Failed to ask the host to close", e),
+        );
     };
 
     // schedule close first and then leave (scope.end)

src/App.tsx

@@ -9,14 +9,22 @@ import {
   type FC,
   type JSX,
   Suspense,
+  useCallback,
   useEffect,
-  useMemo,
   useState,
 } from "react";
-import { BrowserRouter, Route, useLocation, Routes } from "react-router-dom";
+import {
+  BrowserRouter,
+  Route,
+  useLocation,
+  useNavigate,
+  Routes,
+} from "react-router-dom";
 import * as Sentry from "@sentry/react";
 import { TooltipProvider } from "@vector-im/compound-web";
 import { logger } from "matrix-js-sdk/lib/logger";
+import { type MatrixClient } from "matrix-js-sdk";
+import { I18nextProvider } from "react-i18next";
 
 import { HomePage } from "./home/HomePage";
 import { LoginPage } from "./auth/LoginPage";
@@ -25,13 +33,27 @@ import { RoomPage } from "./room/RoomPage";
 import { ClientProvider } from "./ClientContext";
 import { ErrorPage, LoadingPage } from "./FullScreenView";
 import { Initializer } from "./initializer";
-import { widget } from "./widget";
+import { type WidgetHelpers } from "./widget";
 import { useTheme } from "./useTheme";
 import { ProcessorProvider } from "./livekit/TrackProcessorContext";
 import { type AppViewModel } from "./state/AppViewModel";
 import { MediaDevicesContext } from "./MediaDevicesContext";
-import { getUrlParams, HeaderStyle, useUrlParams } from "./UrlParams";
+import {
+  HeaderStyle,
+  UrlParamsProvider,
+  useUrlParams,
+  useUrlParamsFromLocation,
+} from "./UrlParams";
 import { AppBar } from "./AppBar";
+import { i18n } from "./utils/i18n";
+import { useRootElement } from "./RootElementContext";
+import {
+  createWidgetHostBridge,
+  HostBridgeProvider,
+  nullHostBridge,
+} from "./HostBridge";
+import { useInitial } from "./useInitial";
+import { LeaveToHomeProvider } from "./LeaveToHomeContext";
 
 const SentryRoute = Sentry.withSentryReactRouterV7Routing(Route);
 
@@ -39,15 +61,38 @@ interface SimpleProviderProps {
   children: JSX.Element;
 }
 
+/**
+ * Supplies the URL-derived params to the rest of the app. Only the standalone
+ * and widget builds own the URL, so this lives here in the app shell rather
+ * than alongside the context itself.
+ */
+const LocationUrlParamsProvider: FC<SimpleProviderProps> = ({ children }) => {
+  const urlParams = useUrlParamsFromLocation();
+  return <UrlParamsProvider value={urlParams}>{children}</UrlParamsProvider>;
+};
+
+/**
+ * Supplies the way home. Only the app has one — its home page, with the list
+ * of recent calls — so this, too, lives in the app shell.
+ */
+const HomeProvider: FC<SimpleProviderProps> = ({ children }) => {
+  const navigate = useNavigate();
+  const leaveToHome = useCallback(() => {
+    navigate("/")?.catch((e) => logger.error("Failed to navigate home", e));
+  }, [navigate]);
+  return (
+    <LeaveToHomeProvider value={leaveToHome}>{children}</LeaveToHomeProvider>
+  );
+};
+
 const BackgroundProvider: FC<SimpleProviderProps> = ({ children }) => {
   const { pathname } = useLocation();
   const { background } = useUrlParams();
+  const rootElement = useRootElement();
 
   useEffect(() => {
-    document
-      .getElementsByTagName("body")[0]
-      .setAttribute("data-background", background);
-  }, [pathname, background]);
+    rootElement.setAttribute("data-background", background);
+  }, [pathname, background, rootElement]);
 
   return children;
 };
@@ -57,61 +102,89 @@ const ThemeProvider: FC<SimpleProviderProps> = ({ children }) => {
   return children;
 };
 
+/** Wraps the app in an {@link AppBar}, if the params ask for one. */
+const MaybeAppBar: FC<SimpleProviderProps> = ({ children }) => {
+  const { header } = useUrlParams();
+  return header === HeaderStyle.AppBar ? <AppBar>{children}</AppBar> : children;
+};
+
 interface Props {
   vm: AppViewModel;
+  /** A point of access to the widget API, if running as a widget. */
+  widget: WidgetHelpers | null;
 }
 
-export const App: FC<Props> = ({ vm }) => {
+export const App: FC<Props> = ({ vm, widget }) => {
+  // The standalone build has no host; the widget build's host is the client it
+  // is a widget of.
+  const hostBridge = useInitial(() =>
+    widget === null ? nullHostBridge : createWidgetHostBridge(widget),
+  );
   const [loaded, setLoaded] = useState(false);
   useEffect(() => {
     Initializer.init()
       ?.then(async () => {
         if (loaded) return;
         setLoaded(true);
-        await widget?.api.sendContentLoaded();
+        await hostBridge.contentLoaded();
       })
       .catch(logger.error);
   });
 
-  // Since we are outside the router component, we cannot use useUrlParams here
-  const { header } = useMemo(getUrlParams, []);
-
-  const content = loaded ? (
-    <ClientProvider>
-      <MediaDevicesContext value={vm.mediaDevices}>
-        <ProcessorProvider>
-          <Sentry.ErrorBoundary
-            fallback={(error) => <ErrorPage error={error} widget={widget} />}
-          >
-            <Routes>
-              <SentryRoute path="/" element={<HomePage />} />
-              <SentryRoute path="/login" element={<LoginPage />} />
-              <SentryRoute path="/register" element={<RegisterPage />} />
-              <SentryRoute path="*" element={<RoomPage />} />
-            </Routes>
-          </Sentry.ErrorBoundary>
-        </ProcessorProvider>
-      </MediaDevicesContext>
-    </ClientProvider>
-  ) : (
-    <LoadingPage />
+  // As a widget, the client comes from the host over the widget API. Standalone,
+  // Element Call finds one itself, so there is nothing to wait for here.
+  const [widgetClient, setWidgetClient] = useState<MatrixClient | undefined>(
+    undefined,
   );
+  useEffect(() => {
+    if (widget === null) return;
+    widget.client
+      .then(setWidgetClient)
+      .catch((e) => logger.error("Failed to obtain the host's client", e));
+  }, [widget]);
+  const clientReady = widget === null || widgetClient !== undefined;
+
+  const content =
+    loaded && clientReady ? (
+      <ClientProvider client={widgetClient}>
+        <MediaDevicesContext value={vm.mediaDevices}>
+          <ProcessorProvider>
+            <Sentry.ErrorBoundary
+              fallback={(error) => <ErrorPage error={error} />}
+            >
+              <Routes>
+                <SentryRoute path="/" element={<HomePage />} />
+                <SentryRoute path="/login" element={<LoginPage />} />
+                <SentryRoute path="/register" element={<RegisterPage />} />
+                <SentryRoute path="*" element={<RoomPage />} />
+              </Routes>
+            </Sentry.ErrorBoundary>
+          </ProcessorProvider>
+        </MediaDevicesContext>
+      </ClientProvider>
+    ) : (
+      <LoadingPage />
+    );
 
   return (
-    <BrowserRouter>
-      <BackgroundProvider>
-        <ThemeProvider>
-          <TooltipProvider>
-            <Suspense fallback={null}>
-              {header === HeaderStyle.AppBar ? (
-                <AppBar>{content}</AppBar>
-              ) : (
-                content
-              )}
-            </Suspense>
-          </TooltipProvider>
-        </ThemeProvider>
-      </BackgroundProvider>
-    </BrowserRouter>
+    <I18nextProvider i18n={i18n}>
+      <HostBridgeProvider value={hostBridge}>
+        <BrowserRouter>
+          <LocationUrlParamsProvider>
+            <HomeProvider>
+              <BackgroundProvider>
+                <ThemeProvider>
+                  <TooltipProvider>
+                    <Suspense fallback={null}>
+                      <MaybeAppBar>{content}</MaybeAppBar>
+                    </Suspense>
+                  </TooltipProvider>
+                </ThemeProvider>
+              </BackgroundProvider>
+            </HomeProvider>
+          </LocationUrlParamsProvider>
+        </BrowserRouter>
+      </HostBridgeProvider>
+    </I18nextProvider>
   );
 };

src/AppBar.module.css

@@ -68,7 +68,7 @@
 }
 
 /* Hide everything but the subtitle in small windows */
-@media (max-height: 450px) {
+@container element-call (max-height: 450px) {
   .bar {
     display: none;
   }
@@ -131,7 +131,7 @@
   }
 }
 
-body[data-platform="ios"] {
+[data-element-call-root][data-platform="ios"] {
   .bar > header {
     grid-template-rows: minmax(var(--cpd-space-11x), auto) var(--cpd-space-4x);
     grid-template-areas: "primaryButton title secondaryButton";
@@ -166,7 +166,7 @@ body[data-platform="ios"] {
   }
 
   /* Hide everything but the subtitle in small windows */
-  @media (max-height: 450px) {
+  @container element-call (max-height: 450px) {
     .bar:has(.subtitle) > header {
       grid-template-rows: var(--cpd-space-4x) minmax(var(--cpd-space-5x), auto);
       grid-template-areas: "." "subtitle";

src/Avatar.test.tsx

@@ -9,18 +9,22 @@ import { afterEach, expect, test, vi } from "vitest";
 import { render, screen } from "@testing-library/react";
 import { type MatrixClient } from "matrix-js-sdk";
 import { type FC, type PropsWithChildren } from "react";
-import { type WidgetApi } from "matrix-widget-api";
 
 import { ClientContextProvider } from "./ClientContext";
-import { Avatar, getAvatarFromWidgetAPI } from "./Avatar";
+import { Avatar } from "./Avatar";
 import { mockMatrixRoomMember, mockRtcMembership } from "./utils/test";
-import { widget } from "./widget";
+import {
+  type HostBridge,
+  HostBridgeProvider,
+  nullHostBridge,
+} from "./HostBridge";
 
 const TestComponent: FC<
   PropsWithChildren<{
     client: MatrixClient;
+    hostBridge?: HostBridge;
   }>
-> = ({ client, children }) => {
+> = ({ client, hostBridge = nullHostBridge, children }) => {
   return (
     <ClientContextProvider
       value={{
@@ -38,17 +42,11 @@ const TestComponent: FC<
         },
       }}
     >
-      {children}
+      <HostBridgeProvider value={hostBridge}>{children}</HostBridgeProvider>
     </ClientContextProvider>
   );
 };
 
-vi.mock("./widget", () => ({
-  widget: {
-    api: null, // Ideally we'd only mock this in the as a widget test so the whole module is otherwise null, but just nulling `api` by default works well enough
-  },
-}));
-
 afterEach(() => {
   vi.unstubAllGlobals();
 });
@@ -135,7 +133,7 @@ test("should attempt to fetch authenticated media from the server", async () =>
   });
 });
 
-test("should attempt to use widget API if running as a widget", async () => {
+test("should download media through the host when it offers to", async () => {
   const expectedMXCUrl = "mxc://example.org/alice-avatar";
   const expectedObjectURL = "my-object-url";
   const theBlob = new Blob([]);
@@ -151,8 +149,8 @@ test("should attempt to use widget API if running as a widget", async () => {
     getAccessToken: () => undefined,
   } as unknown as MatrixClient);
 
-  widget!.api = { downloadFile: vi.fn() } as unknown as WidgetApi;
-  vi.spyOn(widget!.api, "downloadFile").mockResolvedValue({ file: theBlob });
+  const downloadMedia = vi.fn().mockResolvedValue(theBlob);
+  const hostBridge: HostBridge = { ...nullHostBridge, downloadMedia };
   const member = mockMatrixRoomMember(
     mockRtcMembership("@alice:example.org", "AAAA"),
     {
@@ -161,7 +159,7 @@ test("should attempt to use widget API if running as a widget", async () => {
   );
   const displayName = "Alice";
   render(
-    <TestComponent client={client}>
+    <TestComponent client={client} hostBridge={hostBridge}>
       <Avatar
         id={member.userId}
         name={displayName}
@@ -176,38 +174,5 @@ test("should attempt to use widget API if running as a widget", async () => {
     document.querySelector(`img[src='${expectedObjectURL}']`),
   );
 
-  expect(widget!.api.downloadFile).toBeCalledWith(expectedMXCUrl);
-});
-
-test("Supports download files as base64", async () => {
-  const expectedMXCUrl = "mxc://example.org/alice-avatar";
-  const expectedBase64 =
-    "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAADIElEQVR4nAAQA+/8ApxhEfFNuwna" +
-    "+DO1pFMx5YDg6gb8p1WFkbFSox9H6r5c8jp1gxlHXrDfA/oQFi4A0gTXH9YBNgwRm12xO68QP6lv" +
-    "ZLKH9qW1VM6kz6zA3T1Ui8J+Xbnh2BZ7oXDe/2gajzoA6j1JGotpz99xO+T2NR634Nhx3zhuera/" +
-    "UdrpMLdEpwWXLnSqZRasGsrl93FjdTwRBMaqsx6vJksnPOmV9ttbXFIOb0XDGPbVythSC2n7P/bS" +
-    "Zv0U0QqbBLk/5Wu1werYzAHiz11Bj8bEylQ92Pxvo+PwF6/KbGnIHTvGZkFzDkMnqz3g7Pw3NOSP" +
-    "oV+qfyJuSI0AeZmrPejFQ8kzBSDWO8D7lr4+6ePRBRmZtKCf+fNjSCOyb5jqwhBnD2cycbJtQQbR" +
-    "A4qdPG2ONfTPeQgi96+zT7grBI0JwvgFBceJdLJd4BX1VQIyY+j7OYueNWqEpf8iYgMj78I95eRt" +
-    "nfPLwlxhVns84iL4Yvw8jDrB9vQi8ktpsdJOMiDwKrBGD3q56COD2oIA96CCBgiro4tkvkumZSAc" +
-    "ZKXRLsziUFGytWJLaPjwnzXv2hicPy6k9AXsF3QkysOZAkB3m9XPpixhq9b0OKqV/zZx3L79o6wZ" +
-    "Dr40J7sj7f+ARd545CP01r5omHt94tbnjgA46HsM2OhP+qQ882LN+Bhscq2WSHGSHT4J9MQcsWZP" +
-    "2+N2LdPy61MN4/1++BJHmDcDLQBUEwLvjZp1fRfzxV7yirwIiOA7Vr8z+1yvS/pSkfUzkjswybOd" +
-    "M5i0I8Q69MTXAKxqtR0/tyGkfCmHfupGASp/SAT9J8f3aQV+gDbpva592v4w8Cv5EMm7CzZPwThF" +
-    "kgTChNPts7F03ccxpblfIz0EiAON1DKk71rX07BvDlLHY1ItPuqZ7hjy19jrAgl+QqEE1btHVA5R" +
-    "uAnRXpEWc6rjARlJY5G1wbMk12rrqpr8rhR3YpFgLgOx4BtQ0D/hGe7KANSGBMQojmObId0asCmd" +
-    "XzmnQI9P8QnwsO9vtqZlgIoU4g+f2/G8Q3/nVMX7dujniwEAAP//KmiQs7P8MeIAAAAASUVORK5C" +
-    "YII=";
-  const mockWidgetAPI = {
-    downloadFile: vi.fn().mockImplementation(async (contentUri) => {
-      if (contentUri !== expectedMXCUrl) {
-        return Promise.reject(new Error("Unexpected content URI"));
-      }
-      return { file: expectedBase64 };
-    }),
-  } as unknown as WidgetApi;
-
-  const blob = await getAvatarFromWidgetAPI(mockWidgetAPI, expectedMXCUrl);
-
-  expect(blob).toBeInstanceOf(Blob);
+  expect(downloadMedia).toBeCalledWith(expectedMXCUrl);
 });

src/Avatar.tsx

@@ -14,10 +14,9 @@ import {
 } from "react";
 import { Avatar as CompoundAvatar } from "@vector-im/compound-web";
 import { type MatrixClient } from "matrix-js-sdk";
-import { type WidgetApi } from "matrix-widget-api";
 
 import { useClientState } from "./ClientContext";
-import { widget } from "./widget";
+import { useHostBridge } from "./HostBridge";
 
 export enum Size {
   XS = "xs",
@@ -76,6 +75,7 @@ export const Avatar: FC<Props> = ({
   ...props
 }) => {
   const clientState = useClientState();
+  const hostBridge = useHostBridge();
 
   const sizePx = useMemo(
     () =>
@@ -87,7 +87,8 @@ export const Avatar: FC<Props> = ({
 
   const [avatarUrl, setAvatarUrl] = useState<string | undefined>(undefined);
 
-  // In theory, a change in `clientState` or `sizePx` could run extra getAvatarFromWidgetAPI calls, but in practice they should be stable long before this code runs.
+  // In theory, a change in `clientState` or `sizePx` could run extra media
+  // downloads, but in practice they should be stable long before this code runs.
   useEffect(() => {
     if (!src) {
       setAvatarUrl(undefined);
@@ -96,8 +97,8 @@ export const Avatar: FC<Props> = ({
 
     let blob: Promise<Blob>;
 
-    if (widget?.api) {
-      blob = getAvatarFromWidgetAPI(widget.api, src);
+    if (hostBridge.downloadMedia) {
+      blob = hostBridge.downloadMedia(src);
     } else if (
       clientState?.state === "valid" &&
       clientState.authenticated?.client &&
@@ -132,7 +133,7 @@ export const Avatar: FC<Props> = ({
         URL.revokeObjectURL(objectUrl);
       }
     };
-  }, [clientState, src, sizePx]);
+  }, [clientState, hostBridge, src, sizePx]);
 
   return (
     <CompoundAvatar
@@ -172,24 +173,3 @@ async function getAvatarFromServer(
 
   return blob;
 }
-
-// export for testing
-export async function getAvatarFromWidgetAPI(
-  api: WidgetApi,
-  src: string,
-): Promise<Blob> {
-  const response = await api.downloadFile(src);
-  const file = response.file;
-
-  // element-web sends a Blob, and the MSC4039 is considering changing the spec to strictly Blob, so only handling that
-  if (file instanceof Blob) {
-    return file;
-  } else if (typeof file === "string") {
-    // it is a base64 string
-    const bytes = Uint8Array.from(atob(file), (c) => c.charCodeAt(0));
-    return new Blob([bytes]);
-  }
-  throw new Error(
-    "Downloaded file format is not supported: " + typeof file + "",
-  );
-}

src/ClientContext.test.tsx

@@ -0,0 +1,115 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { expect, test, vi } from "vitest";
+import { render, waitFor } from "@testing-library/react";
+import { BrowserRouter } from "react-router-dom";
+import { type MatrixClient } from "matrix-js-sdk";
+import { type FC } from "react";
+
+import { ClientProvider, useClientState } from "./ClientContext";
+
+const mockClient = (userId = "@alice:example.org"): MatrixClient =>
+  ({
+    on: vi.fn(),
+    removeListener: vi.fn(),
+    getUserId: () => userId,
+    getDeviceId: () => "AAAA",
+    stopClient: vi.fn(),
+  }) as Partial<MatrixClient> as MatrixClient;
+
+/** Reports what the context says, so a test can assert on it. */
+const ShowClientState: FC = () => {
+  const state = useClientState();
+  if (state === undefined) return <span>loading</span>;
+  if (state.state === "error") return <span>error</span>;
+  return (
+    <span>{state.authenticated?.client.getUserId() ?? "unauthenticated"}</span>
+  );
+};
+
+test("uses a client supplied by the host without waiting", () => {
+  const client = mockClient();
+
+  const { container } = render(
+    <BrowserRouter>
+      <ClientProvider client={client}>
+        <ShowClientState />
+      </ClientProvider>
+    </BrowserRouter>,
+  );
+
+  // Available on the very first render: a supplied client needs no session
+  // restoring, so there is no loading state to pass through.
+  expect(container.textContent).toBe("@alice:example.org");
+});
+
+test("does not claim exclusive use of storage when given a client", () => {
+  // The channel is created when the module loads, so spy on the prototype
+  // rather than trying to replace the global.
+  const postMessage = vi.spyOn(BroadcastChannel.prototype, "postMessage");
+
+  render(
+    <BrowserRouter>
+      <ClientProvider client={mockClient()}>
+        <ShowClientState />
+      </ClientProvider>
+    </BrowserRouter>,
+  );
+
+  // The broadcast shuts down other instances to protect Element Call's own
+  // stores. A host's client brings its own, so there is nothing to protect.
+  expect(postMessage).not.toHaveBeenCalled();
+
+  postMessage.mockRestore();
+});
+
+test("follows the client when the host swaps it", () => {
+  const first = mockClient();
+  const second = mockClient("@bob:example.org");
+
+  const { container, rerender } = render(
+    <BrowserRouter>
+      <ClientProvider client={first}>
+        <ShowClientState />
+      </ClientProvider>
+    </BrowserRouter>,
+  );
+  expect(container.textContent).toBe("@alice:example.org");
+
+  // A host that re-authenticates hands us a new client on a mounted component
+  rerender(
+    <BrowserRouter>
+      <ClientProvider client={second}>
+        <ShowClientState />
+      </ClientProvider>
+    </BrowserRouter>,
+  );
+
+  expect(container.textContent).toBe("@bob:example.org");
+});
+
+test("finds a client of its own when the host supplies none", async () => {
+  const client = mockClient();
+  vi.doMock("./utils/spa", () => ({
+    initSPA: vi.fn().mockResolvedValue({ client, passwordlessUser: true }),
+  }));
+
+  const { container } = render(
+    <BrowserRouter>
+      <ClientProvider>
+        <ShowClientState />
+      </ClientProvider>
+    </BrowserRouter>,
+  );
+
+  // Nothing to show until a session has been restored or created
+  expect(container.textContent).toBe("loading");
+  await waitFor(() => expect(container.textContent).toBe("@alice:example.org"));
+
+  vi.doUnmock("./utils/spa");
+});

src/ClientContext.tsx

@@ -16,14 +16,13 @@ import {
   useMemo,
   type JSX,
 } from "react";
-import { useNavigate } from "react-router-dom";
 import { logger } from "matrix-js-sdk/lib/logger";
 import { type ISyncStateData, type SyncState } from "matrix-js-sdk/lib/sync";
 import { ClientEvent, type MatrixClient } from "matrix-js-sdk";
 
-import type { WidgetApi } from "matrix-widget-api";
 import { ErrorPage } from "./FullScreenView";
-import { widget } from "./widget";
+import { useHostBridge } from "./HostBridge";
+import { useLeaveToHome } from "./LeaveToHomeContext";
 import {
   PosthogAnalytics,
   RegistrationType,
@@ -134,18 +133,48 @@ const loadChannel =
 
 interface Props {
   children: JSX.Element;
+  /**
+   * The client Element Call should use.
+   *
+   * An application hosting Element Call as a component already has a client,
+   * and owns the user's session; supplying it here means Element Call neither
+   * authenticates anyone nor manages their session. Left out, Element Call finds a client
+   * itself — from the widget API, or by restoring or creating a session of its
+   * own.
+   */
+  client?: MatrixClient;
 }
 
-export const ClientProvider: FC<Props> = ({ children }) => {
-  const navigate = useNavigate();
+export const ClientProvider: FC<Props> = ({ children, client }) => {
+  const leaveToHome = useLeaveToHome();
+  const hostBridge = useHostBridge();
 
   // null = signed out, undefined = loading
   const [initClientState, setInitClientState] = useState<
     InitResult | null | undefined
-  >(undefined);
+  >(
+    client === undefined
+      ? undefined
+      : // A supplied client belongs to the host, so there is no session of ours
+        // to restore and nothing to wait for.
+        { client, passwordlessUser: false },
+  );
 
   const initializing = useRef(false);
   useEffect(() => {
+    if (client !== undefined) {
+      // Nothing to load, but a host may hand us a different client later — on
+      // re-authenticating, say — so follow whichever one it has given us.
+      setInitClientState((current) =>
+        current?.client === client
+          ? current
+          : { client, passwordlessUser: false },
+      );
+      // Analytics still need to follow the user's choices.
+      if (PosthogAnalytics.instance.isEnabled())
+        PosthogAnalytics.instance.startListeningToSettingsChanges();
+      return;
+    }
     // In case the component is mounted, unmounted, and remounted quickly (as
     // React does in strict mode), we need to make sure not to doubly initialize
     // the client.
@@ -160,7 +189,7 @@ export const ClientProvider: FC<Props> = ({ children }) => {
       })
       .catch((err) => logger.error(err))
       .finally(() => (initializing.current = false));
-  }, []);
+  }, [client]);
 
   const changePassword = useCallback(
     async (password: string) => {
@@ -201,7 +230,6 @@ export const ClientProvider: FC<Props> = ({ children }) => {
 
       saveSession(session);
       setInitClientState({
-        widgetApi: null,
         client,
         passwordlessUser: session.passwordlessUser,
       });
@@ -221,18 +249,20 @@ export const ClientProvider: FC<Props> = ({ children }) => {
     await client.clearStores();
     clearSession();
     setInitClientState(null);
-    await navigate("/");
+    leaveToHome?.();
     PosthogAnalytics.instance.logout();
     PosthogAnalytics.instance.setRegistrationType(RegistrationType.Guest);
-  }, [navigate, initClientState?.client]);
+  }, [leaveToHome, initClientState?.client]);
 
   // To protect against multiple sessions writing to the same storage
   // simultaneously, we send a broadcast message that shuts down all other
-  // running instances of the app. This isn't necessary if the app is running in
-  // a widget though, since then it'll be mostly stateless.
+  // running instances of the app. Element Call only has storage of its own to
+  // protect when it created the session itself; given a client — by a host, or
+  // over the widget API — it is mostly stateless.
+  const ownsSession = client === undefined;
   useEffect(() => {
-    if (!widget) loadChannel?.postMessage({});
-  }, []);
+    if (ownsSession) loadChannel?.postMessage({});
+  }, [ownsSession]);
 
   const [alreadyOpenedErr, setAlreadyOpenedErr] = useState<Error | undefined>(
     undefined,
@@ -307,64 +337,36 @@ export const ClientProvider: FC<Props> = ({ children }) => {
       initClientState.client.on(ClientEvent.Sync, onSync);
     }
 
-    if (initClientState.widgetApi) {
-      const reactSend = initClientState.widgetApi.hasCapability(
-        "org.matrix.msc2762.send.event:m.reaction",
-      );
-      const redactSend = initClientState.widgetApi.hasCapability(
-        "org.matrix.msc2762.send.event:m.room.redaction",
-      );
-      const reactRcv = initClientState.widgetApi.hasCapability(
-        "org.matrix.msc2762.receive.event:m.reaction",
-      );
-      const redactRcv = initClientState.widgetApi.hasCapability(
-        "org.matrix.msc2762.receive.event:m.room.redaction",
-      );
-
-      if (!reactSend || !reactRcv || !redactSend || !redactRcv) {
-        logger.warn("Widget does not support reactions");
-        setSupportsReactions(false);
-      } else {
-        setSupportsReactions(true);
-      }
-    } else {
-      setSupportsReactions(true);
-    }
+    if (!hostBridge.supportsReactions)
+      logger.warn("The host does not permit reactions");
+    setSupportsReactions(hostBridge.supportsReactions);
 
     return (): void => {
       if (initClientState.client) {
         initClientState.client.removeListener(ClientEvent.Sync, onSync);
       }
     };
-  }, [initClientState, onSync]);
+  }, [initClientState, onSync, hostBridge]);
 
   if (alreadyOpenedErr) {
-    return <ErrorPage widget={widget} error={alreadyOpenedErr} />;
+    return <ErrorPage error={alreadyOpenedErr} />;
   }
 
   return <ClientContext value={state}>{children}</ClientContext>;
 };
 
 export type InitResult = {
-  widgetApi: WidgetApi | null;
   client: MatrixClient;
   passwordlessUser: boolean;
 };
 
+/**
+ * Restores or creates a session of Element Call's own. Only reached when no
+ * client was supplied for it to use.
+ */
 async function loadClient(): Promise<InitResult | null> {
-  if (widget) {
-    // We're inside a widget, so let's engage *matryoshka mode*
-    logger.log("Using a matryoshka client");
-    const client = await widget.client;
-    return {
-      widgetApi: widget.api,
-      client,
-      passwordlessUser: false,
-    };
-  } else {
-    const { initSPA } = await import("./utils/spa");
-    return initSPA(loadSession, clearSession);
-  }
+  const { initSPA } = await import("./utils/spa");
+  return initSPA(loadSession, clearSession);
 }
 
 export interface Session {

src/ErrorView.tsx

@@ -20,8 +20,8 @@ import { logger } from "matrix-js-sdk/lib/logger";
 import { RageshakeButton } from "./settings/RageshakeButton";
 import styles from "./ErrorView.module.css";
 import { useUrlParams } from "./UrlParams";
-import { LinkButton } from "./button";
-import { ElementWidgetActions, type WidgetHelpers } from "./widget.ts";
+import { useLeaveToHome } from "./LeaveToHomeContext";
+import { useHostBridge } from "./HostBridge.ts";
 
 interface Props {
   Icon: ComponentType<SVGAttributes<SVGElement>>;
@@ -38,7 +38,6 @@ interface Props {
    */
   fatal?: boolean;
   children: ReactNode;
-  widget: WidgetHelpers | null;
 }
 
 export const ErrorView: FC<Props> = ({
@@ -47,53 +46,47 @@ export const ErrorView: FC<Props> = ({
   rageshake,
   fatal,
   children,
-  widget,
 }) => {
   const { t } = useTranslation();
   const { confineToRoom } = useUrlParams();
+  const hostBridge = useHostBridge();
+  const leaveToHome = useLeaveToHome();
 
   const onReload = useCallback(() => {
     window.location.href = "/";
   }, []);
 
-  const CloseWidgetButton: FC<{ widget: WidgetHelpers }> = ({
-    widget,
+  const CloseButton: FC<{ close: () => Promise<void> }> = ({
+    close,
   }): ReactElement => {
-    // in widget mode we don't want to show the return home button but a close button
-    const closeWidget = (): void => {
-      widget.api.transport
-        .send(ElementWidgetActions.Close, {})
-        .catch((e) => {
-          // What to do here?
-          logger.error("Failed to send close action", e);
-        })
-        .finally(() => {
-          widget.api.transport.stop();
-        });
+    // When the host can dismiss us, offer that instead of a link home
+    const onClose = (): void => {
+      close().catch((e) => {
+        // What to do here?
+        logger.error("Failed to ask the host to close Element Call", e);
+      });
     };
     return (
-      <Button kind="primary" onClick={closeWidget}>
+      <Button kind="primary" onClick={onClose}>
         {t("action.close")}
       </Button>
     );
   };
 
   // Whether the error is considered fatal or pathname is `/` then reload the all app.
-  // If not then navigate to home page.
-  const ReturnToHomeButton = (): ReactElement => {
-    if (fatal || location.pathname === "/") {
-      return (
-        <Button kind="tertiary" className={styles.homeLink} onClick={onReload}>
-          {t("return_home_button")}
-        </Button>
-      );
-    } else {
-      return (
-        <LinkButton kind="tertiary" className={styles.homeLink} to="/">
-          {t("return_home_button")}
-        </LinkButton>
-      );
-    }
+  // If not then navigate to home page. Neither applies when there is no home
+  // to go to.
+  const ReturnToHomeButton = (): ReactElement | null => {
+    if (leaveToHome === null) return null;
+    return (
+      <Button
+        kind="tertiary"
+        className={styles.homeLink}
+        onClick={fatal || location.pathname === "/" ? onReload : leaveToHome}
+      >
+        {t("return_home_button")}
+      </Button>
+    );
   };
 
   return (
@@ -108,8 +101,8 @@ export const ErrorView: FC<Props> = ({
       {rageshake && (
         <RageshakeButton description={`***Error View***: ${title}`} />
       )}
-      {widget ? (
-        <CloseWidgetButton widget={widget} />
+      {hostBridge.close ? (
+        <CloseButton close={hostBridge.close} />
       ) : (
         !confineToRoom && <ReturnToHomeButton />
       )}

src/FullScreenView.tsx

@@ -17,7 +17,6 @@ import styles from "./FullScreenView.module.css";
 import { useUrlParams } from "./UrlParams";
 import { RichError } from "./RichError";
 import { ErrorView } from "./ErrorView";
-import { type WidgetHelpers } from "./widget.ts";
 
 interface FullScreenViewProps {
   className?: string;
@@ -48,12 +47,11 @@ export const FullScreenView: FC<FullScreenViewProps> = ({
 
 interface ErrorPageProps {
   error: unknown;
-  widget: WidgetHelpers | null;
 }
 
 // Due to this component being used as the crash fallback for Sentry, which has
 // weird type requirements, we can't just give this a type of FC<ErrorPageProps>
-export const ErrorPage = ({ error, widget }: ErrorPageProps): ReactElement => {
+export const ErrorPage = ({ error }: ErrorPageProps): ReactElement => {
   const { t } = useTranslation();
   useEffect(() => {
     logger.error(error);
@@ -66,7 +64,6 @@ export const ErrorPage = ({ error, widget }: ErrorPageProps): ReactElement => {
         error.richMessage
       ) : (
         <ErrorView
-          widget={widget}
           Icon={ErrorSolidIcon}
           title={t("error.generic")}
           rageshake

src/Header.module.css

@@ -30,6 +30,11 @@ Please see LICENSE in the repository root for full details.
   display: none;
   align-items: center;
   text-decoration: none;
+  /* A button when it leads home, so undo the browser's button styling */
+  background: none;
+  border: none;
+  padding: 0;
+  cursor: pointer;
 }
 
 .leftNav.hideMobile {
@@ -107,7 +112,7 @@ Please see LICENSE in the repository root for full details.
   gap: var(--cpd-space-1-5x);
 }
 
-@media (min-width: 800px) {
+@container element-call (min-width: 800px) {
   .headerLogo,
   .leftNav.hideMobile,
   .rightNav.hideMobile {

src/Header.tsx

@@ -6,8 +6,13 @@ Please see LICENSE in the repository root for full details.
 */
 
 import classNames from "classnames";
-import { type Ref, type FC, type HTMLAttributes, type ReactNode } from "react";
-import { Link } from "react-router-dom";
+import {
+  type Ref,
+  type FC,
+  type HTMLAttributes,
+  type ReactNode,
+  useCallback,
+} from "react";
 import { useTranslation } from "react-i18next";
 import { Heading, Text } from "@vector-im/compound-web";
 import { UserProfileIcon } from "@vector-im/compound-design-tokens/assets/web/icons";
@@ -16,7 +21,8 @@ import styles from "./Header.module.css";
 import Logo from "./icons/Logo.svg?react";
 import { Avatar, Size } from "./Avatar";
 import { EncryptionLock } from "./room/EncryptionLock";
-import { useMediaQuery } from "./useMediaQuery";
+import { useRootSizeMatches } from "./useRootSize";
+import { useLeaveToHome } from "./LeaveToHomeContext";
 import { DisconnectedBanner } from "./DisconnectedBanner";
 
 interface HeaderProps extends HTMLAttributes<HTMLElement> {
@@ -112,17 +118,30 @@ interface HeaderLogoProps {
   className?: string;
 }
 
+/**
+ * The logo, which is also the way home — when there is a home to go to. As a
+ * component there is not, and it is just the logo.
+ */
 export const HeaderLogo: FC<HeaderLogoProps> = ({ className }) => {
   const { t } = useTranslation();
+  const leaveToHome = useLeaveToHome();
+  const onClick = useCallback(() => leaveToHome?.(), [leaveToHome]);
 
+  if (leaveToHome === null)
+    return (
+      <div className={classNames(styles.headerLogo, className)}>
+        <Logo />
+      </div>
+    );
   return (
-    <Link
+    <button
+      type="button"
       className={classNames(styles.headerLogo, className)}
-      to="/"
+      onClick={onClick}
       aria-label={t("header_label")}
     >
       <Logo />
-    </Link>
+    </button>
   );
 };
 
@@ -142,7 +161,7 @@ export const RoomHeaderInfo: FC<RoomHeaderInfoProps> = ({
   participantCount,
 }) => {
   const { t } = useTranslation();
-  const size = useMediaQuery("(max-width: 550px)") ? "sm" : "lg";
+  const size = useRootSizeMatches(({ width }) => width <= 550) ? "sm" : "lg";
 
   return (
     <div className={styles.roomHeaderInfo} data-size={size}>

src/HostBridge.test.ts

@@ -0,0 +1,306 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { describe, expect, test, vi } from "vitest";
+import { type WidgetApi, WidgetApiToWidgetAction } from "matrix-widget-api";
+import EventEmitter from "events";
+
+import { type Observable } from "rxjs";
+
+import {
+  createWidgetHostBridge,
+  type HostBridge,
+  nullHostBridge,
+} from "./HostBridge";
+import { ElementWidgetActions, type WidgetHelpers } from "./widget";
+
+function mockWidget(api: Partial<WidgetApi>): WidgetHelpers {
+  return {
+    api: api as WidgetApi,
+    lazyActions: new EventEmitter(),
+    client: Promise.resolve(),
+  } as unknown as WidgetHelpers;
+}
+
+/** A widget whose transport records what Element Call sends it. */
+function mockTransport(): {
+  send: ReturnType<typeof vi.fn>;
+  reply: ReturnType<typeof vi.fn>;
+  stop: ReturnType<typeof vi.fn>;
+} {
+  return {
+    send: vi.fn().mockResolvedValue(undefined),
+    reply: vi.fn(),
+    stop: vi.fn(),
+  };
+}
+
+describe("createWidgetHostBridge", () => {
+  describe("telling the host what Element Call is doing", () => {
+    test("asks to be kept on screen, and to stop being", async () => {
+      const setAlwaysOnScreen = vi.fn().mockResolvedValue(true);
+      const bridge = createWidgetHostBridge(mockWidget({ setAlwaysOnScreen }));
+
+      await bridge.setAlwaysOnScreen(true);
+      await bridge.setAlwaysOnScreen(false);
+
+      expect(setAlwaysOnScreen).toHaveBeenNthCalledWith(1, true);
+      expect(setAlwaysOnScreen).toHaveBeenNthCalledWith(2, false);
+    });
+
+    test("reports that it has loaded", async () => {
+      const sendContentLoaded = vi.fn().mockResolvedValue(undefined);
+      const bridge = createWidgetHostBridge(mockWidget({ sendContentLoaded }));
+
+      await bridge.contentLoaded();
+
+      expect(sendContentLoaded).toHaveBeenCalledOnce();
+    });
+
+    test.each([
+      ["notifyJoined", ElementWidgetActions.JoinCall, {}],
+      ["notifyHungUp", ElementWidgetActions.HangupCall, {}],
+    ] as const)("sends %s as %s", async (method, action, payload) => {
+      const transport = mockTransport();
+      const bridge = createWidgetHostBridge(mockWidget({ transport } as never));
+
+      await bridge[method]();
+
+      expect(transport.send).toHaveBeenCalledWith(action, payload);
+    });
+
+    test("sends the mute state the host needs to mirror", async () => {
+      const transport = mockTransport();
+      const bridge = createWidgetHostBridge(mockWidget({ transport } as never));
+
+      await bridge.notifyDeviceMute({
+        audio_enabled: true,
+        video_enabled: false,
+      });
+
+      expect(transport.send).toHaveBeenCalledWith(
+        ElementWidgetActions.DeviceMute,
+        { audio_enabled: true, video_enabled: false },
+      );
+    });
+  });
+
+  describe("relaying what the host asks for", () => {
+    /** Emits a widget action the way widget.ts does, and returns the event. */
+    function askHost(
+      widget: WidgetHelpers,
+      action: string,
+      data: unknown,
+    ): CustomEvent {
+      const ev = new CustomEvent(action, { detail: { action, data } });
+      widget.lazyActions.emit(action, ev);
+      return ev;
+    }
+
+    // Selectors rather than keys, so each stream keeps its own request type
+    const inboundStreams: [
+      name: string,
+      select: (bridge: HostBridge) => Observable<{ data: unknown }>,
+      action: string,
+    ][] = [
+      [
+        "themeChange$",
+        (bridge) => bridge.themeChange$,
+        WidgetApiToWidgetAction.ThemeChange,
+      ],
+      ["join$", (bridge) => bridge.join$, ElementWidgetActions.JoinCall],
+      ["hangUp$", (bridge) => bridge.hangUp$, ElementWidgetActions.HangupCall],
+      [
+        "deviceMute$",
+        (bridge) => bridge.deviceMute$,
+        ElementWidgetActions.DeviceMute,
+      ],
+    ];
+
+    test.each(inboundStreams)(
+      "surfaces %s with the host's data",
+      (_name, select, action) => {
+        const widget = mockWidget({ transport: mockTransport() } as never);
+        const bridge = createWidgetHostBridge(widget);
+        const seen: unknown[] = [];
+        select(bridge).subscribe((request) => seen.push(request.data));
+
+        askHost(widget, action, { some: "payload" });
+
+        expect(seen).toEqual([{ some: "payload" }]);
+      },
+    );
+
+    test("replies to the host against the request it made", () => {
+      const transport = mockTransport();
+      const widget = mockWidget({ transport } as never);
+      const bridge = createWidgetHostBridge(widget);
+      bridge.deviceMute$.subscribe((request) =>
+        request.reply({ audio_enabled: false, video_enabled: true }),
+      );
+
+      const ev = askHost(widget, ElementWidgetActions.DeviceMute, {
+        audio_enabled: false,
+      });
+
+      expect(transport.reply).toHaveBeenCalledWith(ev.detail, {
+        audio_enabled: false,
+        video_enabled: true,
+      });
+    });
+
+    test("still replies when there is nothing to say", () => {
+      const transport = mockTransport();
+      const widget = mockWidget({ transport } as never);
+      const bridge = createWidgetHostBridge(widget);
+      bridge.hangUp$.subscribe((request) => request.reply());
+
+      const ev = askHost(widget, ElementWidgetActions.HangupCall, {});
+
+      // The widget API requires an answer, so an empty reply becomes {}
+      expect(transport.reply).toHaveBeenCalledWith(ev.detail, {});
+    });
+
+    test("stops listening once unsubscribed", () => {
+      const widget = mockWidget({ transport: mockTransport() } as never);
+      const bridge = createWidgetHostBridge(widget);
+      const seen: unknown[] = [];
+      const subscription = bridge.hangUp$.subscribe((r) => seen.push(r.data));
+
+      subscription.unsubscribe();
+      askHost(widget, ElementWidgetActions.HangupCall, {});
+
+      expect(seen).toEqual([]);
+    });
+  });
+
+  describe("downloadMedia", () => {
+    const mxcUri = "mxc://example.org/alice-avatar";
+
+    test("passes a Blob through unchanged", async () => {
+      const file = new Blob([]);
+      const bridge = createWidgetHostBridge(
+        mockWidget({ downloadFile: vi.fn().mockResolvedValue({ file }) }),
+      );
+
+      await expect(bridge.downloadMedia!(mxcUri)).resolves.toBe(file);
+    });
+
+    test("decodes a base64 string into a Blob", async () => {
+      const bridge = createWidgetHostBridge(
+        mockWidget({
+          // "hello" in base64
+          downloadFile: vi.fn().mockResolvedValue({ file: "aGVsbG8=" }),
+        }),
+      );
+
+      const blob = await bridge.downloadMedia!(mxcUri);
+
+      expect(blob).toBeInstanceOf(Blob);
+      // The five decoded bytes, rather than the eight characters of base64 —
+      // which is what we'd get if the string were stored verbatim.
+      expect(blob.size).toBe(5);
+    });
+
+    test("rejects a file format it does not understand", async () => {
+      const bridge = createWidgetHostBridge(
+        mockWidget({ downloadFile: vi.fn().mockResolvedValue({ file: 42 }) }),
+      );
+
+      await expect(bridge.downloadMedia!(mxcUri)).rejects.toThrow(
+        "Downloaded file format is not supported",
+      );
+    });
+  });
+
+  describe("close", () => {
+    test("asks the host to close, then stops the transport", async () => {
+      const transport = {
+        send: vi.fn().mockResolvedValue(undefined),
+        stop: vi.fn(),
+      };
+      const bridge = createWidgetHostBridge(mockWidget({ transport } as never));
+
+      await bridge.close!();
+
+      expect(transport.send).toHaveBeenCalledWith(
+        ElementWidgetActions.Close,
+        {},
+      );
+      expect(transport.stop).toHaveBeenCalledOnce();
+    });
+
+    test("stops the transport even when the host refuses to close", async () => {
+      const transport = {
+        send: vi.fn().mockRejectedValue(new Error("no")),
+        stop: vi.fn(),
+      };
+      const bridge = createWidgetHostBridge(mockWidget({ transport } as never));
+
+      // Leaving the messaging live would leave the close affordance dead
+      await expect(bridge.close!()).rejects.toThrow("no");
+      expect(transport.stop).toHaveBeenCalledOnce();
+    });
+  });
+
+  test("does not offer profile changes, since the host signed the user in", () => {
+    const bridge = createWidgetHostBridge(mockWidget({}));
+    expect(bridge.supportsProfileChanges).toBe(false);
+  });
+
+  test("allows joining unmuted on the intent, since the host asked for the call", () => {
+    const bridge = createWidgetHostBridge(mockWidget({}));
+    expect(bridge.allowJoinUnmutedViaIntent).toBe(true);
+  });
+
+  describe("supportsReactions", () => {
+    const capabilities = [
+      "org.matrix.msc2762.send.event:m.reaction",
+      "org.matrix.msc2762.send.event:m.room.redaction",
+      "org.matrix.msc2762.receive.event:m.reaction",
+      "org.matrix.msc2762.receive.event:m.room.redaction",
+    ];
+
+    test("is true when the host grants every reaction capability", () => {
+      const bridge = createWidgetHostBridge(
+        mockWidget({ hasCapability: () => true }),
+      );
+
+      expect(bridge.supportsReactions).toBe(true);
+    });
+
+    test.each(capabilities)("is false without %s", (missing) => {
+      const bridge = createWidgetHostBridge(
+        mockWidget({ hasCapability: (c) => c !== missing }),
+      );
+
+      expect(bridge.supportsReactions).toBe(false);
+    });
+  });
+});
+
+describe("nullHostBridge", () => {
+  test("offers no way to close, so the interface falls back to navigation", () => {
+    expect(nullHostBridge.close).toBeUndefined();
+  });
+
+  test("supports profile changes, since Element Call signed the user in itself", () => {
+    expect(nullHostBridge.supportsProfileChanges).toBe(true);
+  });
+
+  test("offers no media download, so Element Call uses its own client", () => {
+    expect(nullHostBridge.downloadMedia).toBeUndefined();
+  });
+
+  test("supports reactions, since nothing is mediating its homeserver access", () => {
+    expect(nullHostBridge.supportsReactions).toBe(true);
+  });
+
+  test("does not allow joining unmuted on the intent, since nobody vouched for it", () => {
+    expect(nullHostBridge.allowJoinUnmutedViaIntent).toBe(false);
+  });
+});

src/HostBridge.ts

@@ -0,0 +1,248 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { createContext, use } from "react";
+import { fromEvent, map, NEVER, type Observable } from "rxjs";
+import {
+  type IWidgetApiRequest,
+  type IWidgetApiRequestData,
+  WidgetApiToWidgetAction,
+} from "matrix-widget-api";
+
+import {
+  ElementWidgetActions,
+  type JoinCallData,
+  type WidgetHelpers,
+} from "./widget";
+
+// Note: these are type aliases rather than interfaces so that they satisfy the
+// widget API's index-signature payload types.
+
+/** The mute state Element Call and its host exchange. */
+export type DeviceMuteState = {
+  audio_enabled: boolean;
+  video_enabled: boolean;
+};
+
+/**
+ * A mute state change requested by the host. An absent field means "leave this
+ * one as it is".
+ */
+export type DeviceMuteRequest = {
+  audio_enabled?: boolean;
+  video_enabled?: boolean;
+};
+
+/**
+ * Something the host has asked of Element Call, which it is expected to
+ * acknowledge.
+ */
+export interface HostRequest<Data, Reply = void> {
+  data: Data;
+  /** Acknowledges the request. Should be called exactly once. */
+  reply(reply: Reply): void;
+}
+
+/**
+ * Element Call's view of the application hosting it.
+ *
+ * Element Call can run as its own page, as a widget inside a Matrix client, or
+ * as a component inside one. Only the last two give it a host, and each of
+ * them reaches it by a different route — so everything Element Call needs from
+ * whatever is hosting it goes through this interface, rather than being
+ * expressed in terms of the widget API.
+ *
+ * This covers the interactions Element Call has with its host while running.
+ * The Matrix client it talks to is supplied separately, at startup.
+ */
+export interface HostBridge {
+  // What Element Call tells the host.
+
+  /**
+   * Asks the host to keep Element Call on screen (or stop doing so), so that a
+   * call in progress is not torn down when the user navigates elsewhere.
+   */
+  setAlwaysOnScreen(alwaysOnScreen: boolean): Promise<void>;
+  /** Tells the host that Element Call has finished loading. */
+  contentLoaded(): Promise<void>;
+  /** Tells the host that the user has joined the call. */
+  notifyJoined(): Promise<void>;
+  /** Tells the host that the user has hung up. */
+  notifyHungUp(): Promise<void>;
+  /** Tells the host the user's current audio and video mute state. */
+  notifyDeviceMute(state: DeviceMuteState): Promise<void>;
+  /**
+   * Asks the host to close Element Call, and stops communicating with it. No
+   * further calls should be made on this bridge afterwards.
+   *
+   * Absent when the host has no way to dismiss Element Call — standalone, the
+   * user navigates away instead — so its presence is what tells the interface
+   * whether to offer a close affordance.
+   */
+  close?(): Promise<void>;
+
+  // What the host asks of Element Call.
+
+  /** The host has changed the theme Element Call should use. */
+  themeChange$: Observable<HostRequest<{ name?: string }>>;
+  /** The host wants a preloaded Element Call to join the call now. */
+  join$: Observable<HostRequest<JoinCallData>>;
+  /** The host wants Element Call to leave the call. */
+  hangUp$: Observable<HostRequest<Record<string, never>>>;
+  /** The host wants to change, or read back, the device mute state. */
+  deviceMute$: Observable<HostRequest<DeviceMuteRequest, DeviceMuteState>>;
+
+  // What the host is, and is capable of.
+
+  /**
+   * Whether Element Call may offer to change the user's profile — their
+   * display name and avatar. Only when the account is Element Call's own,
+   * which is to say standalone: a widget's host and an application hosting
+   * the component both signed the user in themselves, so the profile is theirs
+   * to manage and Element Call must not offer to edit it.
+   */
+  readonly supportsProfileChanges: boolean;
+  /** Whether the host permits Element Call to send and receive reactions. */
+  readonly supportsReactions: boolean;
+  /**
+   * Whether the user may be put into a call unmuted on the strength of the
+   * intent alone, when the lobby is skipped and so they get no chance to check
+   * their devices first. A host that asked for the call on the user's behalf
+   * has that much of their trust; standalone Element Call does not, and starts
+   * them muted instead.
+   */
+  readonly allowJoinUnmutedViaIntent: boolean;
+  /**
+   * Fetches media on Element Call's behalf, for hosts that do not give it
+   * direct access to the homeserver. Absent when Element Call should fetch
+   * media itself using its own client.
+   */
+  downloadMedia?(mxcUri: string): Promise<Blob>;
+}
+
+/**
+ * A bridge to nowhere, for when Element Call has no host — that is, when it is
+ * running as its own page and talks to the homeserver directly.
+ */
+export const nullHostBridge: HostBridge = {
+  setAlwaysOnScreen: async () => {},
+  contentLoaded: async () => {},
+  notifyJoined: async () => {},
+  notifyHungUp: async () => {},
+  notifyDeviceMute: async () => {},
+  themeChange$: NEVER,
+  join$: NEVER,
+  hangUp$: NEVER,
+  deviceMute$: NEVER,
+  // Standalone, the account is Element Call's own: it signed the user in, so
+  // it may offer to change the profile.
+  supportsProfileChanges: true,
+  // Standalone Element Call reaches the homeserver itself, so nothing is
+  // withholding these from it.
+  supportsReactions: true,
+  // Standalone, nobody vouched for the intent: it came from a URL, which is
+  // not enough to switch the user's camera and microphone on unasked.
+  allowJoinUnmutedViaIntent: false,
+};
+
+/** Bridges to a host that Element Call is a widget of. */
+export function createWidgetHostBridge(widget: WidgetHelpers): HostBridge {
+  const requests = <Data, Reply>(
+    action: string,
+  ): Observable<HostRequest<Data, Reply>> =>
+    (
+      fromEvent(widget.lazyActions, action) as Observable<
+        CustomEvent<IWidgetApiRequest>
+      >
+    ).pipe(
+      map((ev) => ({
+        data: ev.detail.data as Data,
+        // The widget API requires a reply for every request, and carries the
+        // payload as a plain object, so an empty reply becomes {}.
+        reply: (reply: Reply): void =>
+          widget.api.transport.reply(ev.detail, reply ?? {}),
+      })),
+    );
+
+  const send = async (
+    action: ElementWidgetActions,
+    data: IWidgetApiRequestData = {},
+  ): Promise<void> => {
+    await widget.api.transport.send(action, data);
+  };
+
+  return {
+    setAlwaysOnScreen: async (alwaysOnScreen) => {
+      await widget.api.setAlwaysOnScreen(alwaysOnScreen);
+    },
+    contentLoaded: async () => widget.api.sendContentLoaded(),
+    notifyJoined: async () => send(ElementWidgetActions.JoinCall),
+    notifyHungUp: async () => send(ElementWidgetActions.HangupCall),
+    notifyDeviceMute: async (state) =>
+      send(ElementWidgetActions.DeviceMute, state),
+    close: async () => {
+      try {
+        await send(ElementWidgetActions.Close);
+      } finally {
+        // Stop regardless of whether the host acknowledged the request. A host
+        // that rejects or never answers would otherwise leave the messaging
+        // live, and the close affordance doing nothing at all.
+        widget.api.transport.stop();
+      }
+    },
+    themeChange$: requests(WidgetApiToWidgetAction.ThemeChange),
+    join$: requests(ElementWidgetActions.JoinCall),
+    hangUp$: requests(ElementWidgetActions.HangupCall),
+    deviceMute$: requests(ElementWidgetActions.DeviceMute),
+    // The client we are a widget of signed the user in, so the profile is its
+    // to manage
+    supportsProfileChanges: false,
+    // The client we are a widget of asked for this call on the user's behalf,
+    // so its intent may be trusted to say whether they start unmuted
+    allowJoinUnmutedViaIntent: true,
+    // Element Call needs the host's permission to send reactions on its behalf.
+    // Read on access rather than up front: the widget API negotiates its
+    // capabilities asynchronously, and the bridge is built before that settles.
+    get supportsReactions(): boolean {
+      return (
+        widget.api.hasCapability("org.matrix.msc2762.send.event:m.reaction") &&
+        widget.api.hasCapability(
+          "org.matrix.msc2762.send.event:m.room.redaction",
+        ) &&
+        widget.api.hasCapability(
+          "org.matrix.msc2762.receive.event:m.reaction",
+        ) &&
+        widget.api.hasCapability(
+          "org.matrix.msc2762.receive.event:m.room.redaction",
+        )
+      );
+    },
+    downloadMedia: async (mxcUri) => {
+      const { file } = await widget.api.downloadFile(mxcUri);
+      if (file instanceof Blob) return file;
+      if (typeof file === "string")
+        // it is a base64 string
+        return new Blob([Uint8Array.from(atob(file), (c) => c.charCodeAt(0))]);
+      throw new Error(
+        `Downloaded file format is not supported: ${typeof file}`,
+      );
+    },
+  };
+}
+
+const HostBridgeContext = createContext<HostBridge | null>(null);
+
+export const HostBridgeProvider = HostBridgeContext.Provider;
+
+/**
+ * The application hosting Element Call.
+ *
+ * Defaults to {@link nullHostBridge}, so that tests and stories, which have no
+ * host, need no provider.
+ */
+export const useHostBridge = (): HostBridge =>
+  use(HostBridgeContext) ?? nullHostBridge;

src/LeaveToHomeContext.ts

@@ -0,0 +1,29 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { createContext, use } from "react";
+
+/**
+ * How the user leaves the call for wherever they came from: the standalone
+ * app's home page, with its list of recent calls.
+ *
+ * The call itself has no idea where that is, or whether there is such a place
+ * at all. Standalone there is, and the shell navigates to it; as a component
+ * there is not — the host decides what happens after a call — so nothing is
+ * supplied, and the call offers no way out of its own. This is what lets the
+ * call be rendered without a router.
+ */
+const LeaveToHomeContext = createContext<(() => void) | null>(null);
+
+export const LeaveToHomeProvider = LeaveToHomeContext.Provider;
+
+/**
+ * The way out of the call, or null when there is nowhere to go and the call
+ * should not offer one.
+ */
+export const useLeaveToHome = (): (() => void) | null =>
+  use(LeaveToHomeContext);

src/Modal.module.css

@@ -48,7 +48,7 @@ Please see LICENSE in the repository root for full details.
   --handle-inset-block-end: var(--cpd-space-4x);
 }
 
-body[data-platform="ios"] .drawer {
+[data-element-call-root][data-platform="ios"] .drawer {
   --border-radius: 10px;
   --handle-block-size: 5px;
   --handle-inline-size: 36px;

src/Modal.tsx

@@ -24,6 +24,7 @@ import { Heading, Glass } from "@vector-im/compound-web";
 import styles from "./Modal.module.css";
 import overlayStyles from "./Overlay.module.css";
 import { useMediaQuery } from "./useMediaQuery";
+import { useRootElement } from "./RootElementContext";
 
 export interface Props {
   title: string;
@@ -78,6 +79,7 @@ export const Modal: FC<Props> = ({
   ...rest
 }) => {
   const { t } = useTranslation();
+  const rootElement = useRootElement();
   // Empirically, Chrome on Android can end up not matching (hover: none), but
   // still matching (pointer: coarse) :/
   const touchscreen = useMediaQuery("(hover: none) or (pointer: coarse)");
@@ -100,7 +102,7 @@ export const Modal: FC<Props> = ({
         onOpenChange={onOpenChange}
         dismissible={onDismiss !== undefined}
       >
-        <Drawer.Portal>
+        <Drawer.Portal container={rootElement}>
           <Drawer.Overlay className={classNames(overlayStyles.bg)} />
           <Drawer.Content
             className={classNames(
@@ -155,7 +157,7 @@ export const Modal: FC<Props> = ({
 
     return (
       <DialogRoot open={open} onOpenChange={onOpenChange}>
-        <DialogPortal>
+        <DialogPortal container={rootElement}>
           <DialogOverlay
             className={classNames(overlayStyles.bg, overlayStyles.animate)}
           />

src/QrCode.tsx

@@ -8,7 +8,7 @@ Please see LICENSE in the repository root for full details.
 import { type FC, useEffect, useState } from "react";
 import { toDataURL } from "qrcode";
 import classNames from "classnames";
-import { t } from "i18next";
+import { useTranslation } from "react-i18next";
 
 import styles from "./QrCode.module.css";
 
@@ -18,6 +18,7 @@ interface Props {
 }
 
 export const QrCode: FC<Props> = ({ data, className }) => {
+  const { t } = useTranslation();
   const [url, setUrl] = useState<string | null>(null);
 
   useEffect(() => {

src/RichError.tsx

@@ -10,7 +10,6 @@ import { PopOutIcon } from "@vector-im/compound-design-tokens/assets/web/icons";
 
 import type { FC, ReactNode } from "react";
 import { ErrorView } from "./ErrorView";
-import { widget } from "./widget.ts";
 
 /**
  * An error consisting of a terse message to be logged to the console and a
@@ -32,11 +31,7 @@ const OpenElsewhere: FC = () => {
   const { t } = useTranslation();
 
   return (
-    <ErrorView
-      widget={widget}
-      Icon={PopOutIcon}
-      title={t("error.open_elsewhere")}
-    >
+    <ErrorView Icon={PopOutIcon} title={t("error.open_elsewhere")}>
       <p>
         {t("error.open_elsewhere_description", {
           brand: import.meta.env.VITE_PRODUCT_NAME || "Element Call",

src/RootElementContext.ts

@@ -0,0 +1,43 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { createContext, use } from "react";
+
+/**
+ * The element that Element Call treats as the root of its own interface.
+ *
+ * Element Call decorates this element with the theme, layout and background
+ * attributes its stylesheets key off, and portals its modals into it. When
+ * Element Call owns the page this is simply the document body; as a component
+ * it is the container the host mounted it into, so that Element Call does not
+ * reach outside its own subtree.
+ *
+ * The stylesheets find this element by its `data-element-call-root` attribute,
+ * which {@link useTheme} sets along with the platform and theme, so they no
+ * longer depend on it being the body.
+ *
+ * What remains body-specific is the standalone page's own furniture: the
+ * `body` rule in `index.css` still sets the page background and margin, and
+ * `index.html` starts the body hidden with `no-theme` until the theme lands.
+ * Neither applies when a host mounts Element Call into a container of its own.
+ */
+const RootElementContext = createContext<HTMLElement | null>(null);
+
+/**
+ * Supplies the element Element Call should confine itself to. The standalone
+ * and widget builds need no provider, since for them that element is the body.
+ */
+export const RootElementProvider = RootElementContext.Provider;
+
+/**
+ * The element Element Call should decorate and portal into.
+ *
+ * Defaults to the document body, so that the standalone and widget builds work
+ * without a provider.
+ */
+export const useRootElement = (): HTMLElement =>
+  use(RootElementContext) ?? document.body;

src/Toast.tsx

@@ -25,6 +25,7 @@ import { Text } from "@vector-im/compound-web";
 
 import styles from "./Toast.module.css";
 import overlayStyles from "./Overlay.module.css";
+import { useRootElement } from "./RootElementContext";
 
 interface Props {
   /**
@@ -64,6 +65,7 @@ export const Toast: FC<Props> = ({
   Icon,
   modal = true,
 }) => {
+  const rootElement = useRootElement();
   const onOpenChange = useCallback(
     (open: boolean) => {
       if (!open) onDismiss();
@@ -104,7 +106,11 @@ export const Toast: FC<Props> = ({
 
   return (
     <DialogRoot open={open} onOpenChange={onOpenChange} modal={modal}>
-      {modal ? <DialogPortal>{content}</DialogPortal> : content}
+      {modal ? (
+        <DialogPortal container={rootElement}>{content}</DialogPortal>
+      ) : (
+        content
+      )}
     </DialogRoot>
   );
 };

src/UrlParams.test.ts

@@ -11,10 +11,14 @@ import { logger } from "matrix-js-sdk/lib/logger";
 
 import * as PlatformMod from "../src/Platform";
 import {
+  BackgroundStyle,
+  configurationForIntent,
   getRoomIdentifierFromUrl,
   computeUrlParams,
   HeaderStyle,
   getUrlParams,
+  componentProperties,
+  UserIntent,
 } from "../src/UrlParams";
 import { mockConfig } from "./utils/test";
 
@@ -335,6 +339,50 @@ describe("UrlParams", () => {
         callIntent: "audio",
       });
     });
+
+    it("accepts start_call_dm_voice", () => {
+      expect(
+        computeUrlParams(
+          "?intent=start_call_dm_voice&widgetId=1234&parentUrl=parent.org",
+        ),
+      ).toMatchObject({
+        ...startNewCallDefaults("desktop"),
+        // A DM rings the other side and waits for them, whichever platform
+        sendNotificationType: "ring",
+        autoLeaveWhenOthersLeft: true,
+        waitForCallPickup: true,
+        callIntent: "audio",
+      });
+    });
+
+    it("accepts join_existing_dm", () => {
+      expect(
+        computeUrlParams(
+          "?intent=join_existing_dm&widgetId=1234&parentUrl=parent.org",
+        ),
+      ).toMatchObject({
+        ...joinExistingCallDefaults("desktop"),
+        // Straight in: the other side is already waiting
+        skipLobby: true,
+        autoLeaveWhenOthersLeft: true,
+        waitForCallPickup: false,
+        callIntent: "video",
+      });
+    });
+
+    it("accepts join_existing_dm_voice", () => {
+      expect(
+        computeUrlParams(
+          "?intent=join_existing_dm_voice&widgetId=1234&parentUrl=parent.org",
+        ),
+      ).toMatchObject({
+        ...joinExistingCallDefaults("desktop"),
+        skipLobby: true,
+        autoLeaveWhenOthersLeft: true,
+        waitForCallPickup: false,
+        callIntent: "audio",
+      });
+    });
   });
 
   describe("skipLobby", () => {
@@ -424,4 +472,48 @@ describe("UrlParams", () => {
       );
     });
   });
+
+  // What Element Call runs with when a host embeds it as a component, which
+  // has no URL of its own for any of this to come from
+  describe("hosted defaults", () => {
+    it("assume nothing about a session or a page", () => {
+      expect(componentProperties).toMatchObject({
+        // The host is not a widget host, and supplies the client itself, so
+        // none of the widget or session plumbing applies
+        isWidget: false,
+        widgetId: null,
+        parentUrl: null,
+        userId: null,
+        deviceId: null,
+        baseUrl: null,
+        homeserver: null,
+        // The gradient is drawn by a `position: fixed` pseudo-element, which
+        // would escape the container and cover the host's own interface
+        background: BackgroundStyle.Solid,
+      });
+    });
+
+    it("keep a hosted call inside its room", () => {
+      const hosted = configurationForIntent(UserIntent.JoinExistingCall);
+      expect(hosted).toMatchObject({
+        // A host owns navigation, so Element Call must not offer a way out of
+        // the room
+        confineToRoom: true,
+        perParticipantE2EE: true,
+        // The lobby first, so that the user picks their devices rather than
+        // being thrown into the call by the act of being rendered
+        skipLobby: false,
+      });
+      // No Element Call branding inside someone else's application
+      expect(hosted.header).not.toBe(HeaderStyle.Standard);
+    });
+
+    it("fall back to the standalone app's when no intent is stated", () => {
+      expect(configurationForIntent(UserIntent.Unknown)).toMatchObject({
+        confineToRoom: false,
+        header: HeaderStyle.Standard,
+        perParticipantE2EE: false,
+      });
+    });
+  });
 });

src/UrlParams.ts

@@ -6,7 +6,7 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE in the repository root for full details.
 */
 
-import { useMemo } from "react";
+import { createContext, use, useMemo } from "react";
 import { useLocation } from "react-router-dom";
 import { logger } from "matrix-js-sdk/lib/logger";
 import {
@@ -59,6 +59,17 @@ export interface UrlProperties {
   // Widget api related params
   widgetId: string | null;
   parentUrl: string | null;
+  /**
+   * Whether Element Call was started as a widget of a Matrix client, which is
+   * to say whether it was given a widget ID and a parent to talk to.
+   *
+   * Only meaningful to the standalone and widget builds, which own the URL —
+   * so use it for decisions that belong to the app shell, such as whether
+   * Element Call is responsible for authenticating the user. Anything the call
+   * interface itself needs to know about its host should come from the host
+   * bridge instead.
+   */
+  isWidget: boolean;
   /**
    * Anything about what room we're pointed to should be from useRoomIdentifier which
    * parses the path and resolves alias with respect to the default server name, however
@@ -343,6 +354,136 @@ export const getUrlParams = (
   return params;
 };
 
+/**
+ * The configuration implied by what the user meant to do — if they pressed a
+ * Start Call button this would be `start_call`, and if they pressed Join Call,
+ * `join_existing`.
+ *
+ * These are platform-specific defaults, so that a host can start a call by
+ * saying what the user asked for rather than by setting every parameter itself,
+ * and so that what each intent means is Element Call's decision, made in one
+ * place. A host that wants something else states it alongside the intent.
+ *
+ * {@link UserIntent.Unknown} means no intent was stated, and gives the
+ * standalone app's defaults: Element Call owns the whole page, so it offers the
+ * way out of the room that a hosted call must not.
+ */
+export function configurationForIntent(intent: UserIntent): UrlConfiguration {
+  // Only constants and `platform` here, so that this depends on nothing but
+  // the intent.
+  let preset: UrlConfiguration = {
+    confineToRoom: true,
+    preload: false,
+    header: platform === "desktop" ? HeaderStyle.None : HeaderStyle.AppBar,
+    showControls: true,
+    hideScreensharing: false,
+    allowIceFallback: true,
+    perParticipantE2EE: true,
+    controlledAudioDevices: platform === "desktop" ? false : true,
+    skipLobby: true,
+    returnToLobby: false,
+    sendNotificationType: "notification",
+    autoLeaveWhenOthersLeft: false,
+    waitForCallPickup: false,
+  };
+  switch (intent) {
+    case UserIntent.StartNewCall:
+      preset.skipLobby = false;
+      preset.callIntent = "video";
+      break;
+    case UserIntent.JoinExistingCall:
+      // On desktop this will be overridden based on which button was used to join the call
+      preset.skipLobby = false;
+      preset.callIntent = "video";
+      break;
+    case UserIntent.StartNewCallVoice:
+      preset.skipLobby = false;
+      preset.callIntent = "audio";
+      break;
+    case UserIntent.JoinExistingCallVoice:
+      // On desktop this will be overridden based on which button was used to join the call
+      preset.skipLobby = false;
+      preset.callIntent = "audio";
+      break;
+    case UserIntent.StartNewCallDMVoice:
+      preset.callIntent = "audio";
+    // Fall through
+    case UserIntent.StartNewCallDM:
+      preset.skipLobby = true;
+      preset.sendNotificationType = "ring";
+      preset.autoLeaveWhenOthersLeft = true;
+      preset.waitForCallPickup = true;
+      preset.callIntent = preset.callIntent ?? "video";
+      break;
+    case UserIntent.JoinExistingCallDMVoice:
+      preset.callIntent = "audio";
+    // Fall through
+    case UserIntent.JoinExistingCallDM:
+      // On desktop this will be overridden based on which button was used to join the call
+      preset.skipLobby = true;
+      preset.autoLeaveWhenOthersLeft = true;
+      preset.callIntent = preset.callIntent ?? "video";
+      break;
+    // Non widget usecase defaults
+    default:
+      preset = {
+        confineToRoom: false,
+        preload: false,
+        header: HeaderStyle.Standard,
+        showControls: true,
+        hideScreensharing: false,
+        allowIceFallback: false,
+        perParticipantE2EE: false,
+        controlledAudioDevices: false,
+        skipLobby: false,
+        returnToLobby: false,
+        sendNotificationType: undefined,
+        autoLeaveWhenOthersLeft: false,
+        waitForCallPickup: false,
+      };
+  }
+  return preset;
+}
+
+/**
+ * The {@link UrlProperties} for Element Call running as a component inside a
+ * host application.
+ *
+ * It has no URL of its own to read these from, and it does not need most of
+ * them: the widget plumbing does not apply, the Matrix client and the analytics
+ * configuration come from the host by other routes, and what is left is either
+ * the host's to state through the component's props or Element Call's own
+ * default.
+ */
+export const componentProperties: UrlProperties = {
+  widgetId: null,
+  parentUrl: null,
+  isWidget: false,
+  roomId: null,
+  userId: null,
+  displayName: null,
+  deviceId: null,
+  baseUrl: null,
+  lang: null,
+  fonts: [],
+  fontScale: null,
+  posthogUserId: null,
+  posthogApiHost: null,
+  posthogApiKey: null,
+  e2eEnabled: true,
+  password: null,
+  viaServers: null,
+  homeserver: null,
+  rageshakeSubmitUrl: null,
+  sentryDsn: null,
+  sentryEnvironment: null,
+  theme: null,
+  // Solid rather than the gradient the standalone app defaults to: the gradient
+  // is drawn by a `position: fixed` pseudo-element, which would escape the
+  // container Element Call was given and cover the host's own interface.
+  background: BackgroundStyle.Solid,
+};
+
 /**
  * Gets the app parameters for the current URL.
  * @param search The URL search string
@@ -372,82 +513,12 @@ export const computeUrlParams = (search = "", hash = ""): UrlParams => {
   const intent = !isWidget
     ? UserIntent.Unknown
     : (parser.getEnumParam("intent", UserIntent) ?? UserIntent.Unknown);
-  // Here we only use constants and `platform` to determine the intent preset.
-  let intentPreset: UrlConfiguration = {
-    confineToRoom: true,
-    preload: false,
-    header: platform === "desktop" ? HeaderStyle.None : HeaderStyle.AppBar,
-    showControls: true,
-    hideScreensharing: false,
-    allowIceFallback: true,
-    perParticipantE2EE: true,
-    controlledAudioDevices: platform === "desktop" ? false : true,
-    skipLobby: true,
-    returnToLobby: false,
-    sendNotificationType: "notification",
-    autoLeaveWhenOthersLeft: false,
-    waitForCallPickup: false,
-  };
-  switch (intent) {
-    case UserIntent.StartNewCall:
-      intentPreset.skipLobby = false;
-      intentPreset.callIntent = "video";
-      break;
-    case UserIntent.JoinExistingCall:
-      // On desktop this will be overridden based on which button was used to join the call
-      intentPreset.skipLobby = false;
-      intentPreset.callIntent = "video";
-      break;
-    case UserIntent.StartNewCallVoice:
-      intentPreset.skipLobby = false;
-      intentPreset.callIntent = "audio";
-      break;
-    case UserIntent.JoinExistingCallVoice:
-      // On desktop this will be overridden based on which button was used to join the call
-      intentPreset.skipLobby = false;
-      intentPreset.callIntent = "audio";
-      break;
-    case UserIntent.StartNewCallDMVoice:
-      intentPreset.callIntent = "audio";
-    // Fall through
-    case UserIntent.StartNewCallDM:
-      intentPreset.skipLobby = true;
-      intentPreset.sendNotificationType = "ring";
-      intentPreset.autoLeaveWhenOthersLeft = true;
-      intentPreset.waitForCallPickup = true;
-      intentPreset.callIntent = intentPreset.callIntent ?? "video";
-      break;
-    case UserIntent.JoinExistingCallDMVoice:
-      intentPreset.callIntent = "audio";
-    // Fall through
-    case UserIntent.JoinExistingCallDM:
-      // On desktop this will be overridden based on which button was used to join the call
-      intentPreset.skipLobby = true;
-      intentPreset.autoLeaveWhenOthersLeft = true;
-      intentPreset.callIntent = intentPreset.callIntent ?? "video";
-      break;
-    // Non widget usecase defaults
-    default:
-      intentPreset = {
-        confineToRoom: false,
-        preload: false,
-        header: HeaderStyle.Standard,
-        showControls: true,
-        hideScreensharing: false,
-        allowIceFallback: false,
-        perParticipantE2EE: false,
-        controlledAudioDevices: false,
-        skipLobby: false,
-        returnToLobby: false,
-        sendNotificationType: undefined,
-        autoLeaveWhenOthersLeft: false,
-        waitForCallPickup: false,
-      };
-  }
+  const intentPreset = configurationForIntent(intent);
 
   const properties: UrlProperties = {
     widgetId,
     parentUrl,
+    isWidget,
     // NB. we don't validate roomId here as we do in getRoomIdentifierFromUrl:
     // what would we do if it were invalid? If the widget API says that's what
     // the room ID is, then that's what it is.
@@ -519,11 +590,37 @@ export const computeUrlParams = (search = "", hash = ""): UrlParams => {
   };
 };
 
+const UrlParamsContext = createContext<UrlParams | null>(null);
+
 /**
- * Hook to simplify use of getUrlParams.
- * @returns The app parameters for the current URL
+ * Supplies the parameters Element Call should run with.
+ *
+ * The standalone and widget builds derive these from the URL, but the
+ * component has no URL of its own to read them from, so its host provides them
+ * directly instead.
+ *
+ * TODO: `UrlParams` is no longer an accurate name now that these need not come
+ * from a URL. Renaming it touches every consumer, so it is left until the rest
+ * of the de-globalisation work has settled.
  */
-export const useUrlParams = (): UrlParams => {
+export const UrlParamsProvider = UrlParamsContext.Provider;
+
+/**
+ * The parameters Element Call is running with.
+ *
+ * Falls back to parsing `window.location` when no provider is present, so that
+ * tests and stories keep working without one.
+ */
+export const useUrlParams = (): UrlParams =>
+  use(UrlParamsContext) ?? getUrlParams();
+
+/**
+ * Derives {@link UrlParams} from the current router location.
+ *
+ * Only meaningful when Element Call owns the URL; the component is given its
+ * params directly through {@link UrlParamsProvider}.
+ */
+export const useUrlParamsFromLocation = (): UrlParams => {
   const { search, hash } = useLocation();
   return useMemo(() => getUrlParams(search, hash), [search, hash]);
 };

src/analytics/PosthogAnalytics.test.ts

@@ -15,6 +15,7 @@ import {
   afterAll,
 } from "vitest";
 import posthog, { type CaptureResult } from "posthog-js";
+import { type MatrixClient } from "matrix-js-sdk";
 
 import {
   Anonymity,
@@ -22,75 +23,122 @@ import {
   PosthogAnalytics,
 } from "./PosthogAnalytics";
 import { mockConfig } from "../utils/test";
+import { analyticsConfigFromEnvironment } from "../initializer";
+import { optInAnalytics } from "../settings/settings";
 
 describe("PosthogAnalytics", () => {
-  describe("embedded package", () => {
-    beforeAll(() => {
-      vi.stubEnv("VITE_PACKAGE", "embedded");
-    });
-
+  describe("enablement", () => {
     beforeEach(() => {
-      mockConfig({});
-      window.location.hash = "#";
       PosthogAnalytics.resetInstance();
     });
 
-    afterAll(() => {
-      vi.unstubAllEnvs();
-    });
-
-    it("does not create instance without config value or URL params", () => {
+    it("stays off until it is configured", () => {
       expect(PosthogAnalytics.instance.isEnabled()).toBe(false);
     });
 
-    it("ignores config value and does not create instance", () => {
-      mockConfig({
-        posthog: {
-          api_host: "https://api.example.com.localhost",
-          api_key: "api_key",
-        },
+    it("stays off when configured without credentials", () => {
+      PosthogAnalytics.configure({ matrixBackend: "jssdk" });
+      expect(PosthogAnalytics.instance.isEnabled()).toBe(false);
+    });
+
+    it("stays off when given only a key", () => {
+      PosthogAnalytics.configure({
+        matrixBackend: "jssdk",
+        apiKey: "api_key",
       });
       expect(PosthogAnalytics.instance.isEnabled()).toBe(false);
     });
 
-    it("uses URL params if both set", () => {
-      window.location.hash = `#?posthogApiHost=${encodeURIComponent("https://url.example.com.localhost")}&posthogApiKey=api_key`;
+    it("turns on when given both a key and a host", () => {
+      PosthogAnalytics.configure({
+        matrixBackend: "jssdk",
+        apiKey: "api_key",
+        apiHost: "https://api.example.com.localhost",
+      });
       expect(PosthogAnalytics.instance.isEnabled()).toBe(true);
     });
   });
 
-  describe("full package", () => {
-    beforeAll(() => {
-      vi.stubEnv("VITE_PACKAGE", "full");
-    });
-
+  // Which of the URL and config.json the credentials come from is a deliberate
+  // policy: an embedder is responsible for its own users' telemetry, so it must
+  // not pick up the deployment's, and vice versa.
+  describe("analyticsConfigFromEnvironment", () => {
     beforeEach(() => {
       mockConfig({});
       window.location.hash = "#";
-      PosthogAnalytics.resetInstance();
     });
 
     afterAll(() => {
       vi.unstubAllEnvs();
     });
 
-    it("does not create instance without config value", () => {
-      expect(PosthogAnalytics.instance.isEnabled()).toBe(false);
-    });
+    const urlCredentials = `posthogApiHost=${encodeURIComponent("https://url.example.com.localhost")}&posthogApiKey=url_key`;
+    const configCredentials = {
+      posthog: {
+        api_host: "https://config.example.com.localhost",
+        api_key: "config_key",
+      },
+    };
 
-    it("ignores URL params and does not create instance", () => {
-      window.location.hash = `#?posthogApiHost=${encodeURIComponent("https://url.example.com.localhost")}&posthogApiKey=api_key`;
-      expect(PosthogAnalytics.instance.isEnabled()).toBe(false);
-    });
-
-    it("creates instance with config value", () => {
-      mockConfig({
-        posthog: {
-          api_host: "https://api.example.com.localhost",
-          api_key: "api_key",
-        },
+    describe("embedded package", () => {
+      beforeAll(() => {
+        vi.stubEnv("VITE_PACKAGE", "embedded");
       });
-      expect(PosthogAnalytics.instance.isEnabled()).toBe(true);
+
+      it("has no credentials without URL params", () => {
+        expect(analyticsConfigFromEnvironment().apiKey).toBeUndefined();
+      });
+
+      it("takes the credentials from the URL", () => {
+        window.location.hash = `#?${urlCredentials}`;
+        expect(analyticsConfigFromEnvironment()).toMatchObject({
+          apiKey: "url_key",
+          apiHost: "https://url.example.com.localhost",
+        });
+      });
+
+      it("ignores the deployment's config", () => {
+        mockConfig(configCredentials);
+        expect(analyticsConfigFromEnvironment().apiKey).toBeUndefined();
+      });
+    });
+
+    describe("full package", () => {
+      beforeAll(() => {
+        vi.stubEnv("VITE_PACKAGE", "full");
+      });
+
+      it("has no credentials without config", () => {
+        expect(analyticsConfigFromEnvironment().apiKey).toBeUndefined();
+      });
+
+      it("takes the credentials from the config", () => {
+        mockConfig(configCredentials);
+        expect(analyticsConfigFromEnvironment()).toMatchObject({
+          apiKey: "config_key",
+          apiHost: "https://config.example.com.localhost",
+        });
+      });
+
+      it("ignores the URL params", () => {
+        window.location.hash = `#?${urlCredentials}`;
+        expect(analyticsConfigFromEnvironment().apiKey).toBeUndefined();
+      });
+    });
+
+    // Who owns the user's analytics identity depends on how Element Call is
+    // running, not on which package it was built as.
+    it("reports the embedded backend when running as a widget", () => {
+      vi.stubEnv("VITE_PACKAGE", "full");
+      window.location.hash = `#?widgetId=id&parentUrl=${encodeURIComponent("https://host.example.com.localhost")}&posthogUserId=given_id`;
+      expect(analyticsConfigFromEnvironment()).toMatchObject({
+        matrixBackend: "embedded",
+        hostAnalyticsId: "given_id",
+      });
+    });
+
+    it("reports the jssdk backend when running standalone", () => {
+      expect(analyticsConfigFromEnvironment().matrixBackend).toBe("jssdk");
     });
   });
 
@@ -204,22 +252,13 @@ describe("PosthogAnalytics", () => {
   // posthog-js bumps renaming/removing the hook. The filter logic itself is
   // covered by the applyPrivacyFilters block above.
   describe("posthog.init wiring", () => {
-    beforeAll(() => {
-      vi.stubEnv("VITE_PACKAGE", "full");
-    });
-
     beforeEach(() => {
-      mockConfig({
-        posthog: {
-          api_host: "https://api.example.com.localhost",
-          api_key: "api_key",
-        },
-      });
       PosthogAnalytics.resetInstance();
-    });
-
-    afterAll(() => {
-      vi.unstubAllEnvs();
+      PosthogAnalytics.configure({
+        matrixBackend: "jssdk",
+        apiKey: "api_key",
+        apiHost: "https://api.example.com.localhost",
+      });
     });
 
     it("passes events through the privacy filter via before_send", () => {
@@ -244,3 +283,86 @@ describe("PosthogAnalytics", () => {
     });
   });
 });
+
+describe("identifying the user", () => {
+  const credentials = {
+    apiKey: "api_key",
+    apiHost: "https://api.example.com.localhost",
+  };
+
+  function mockClient(accountDataId: string | null): MatrixClient {
+    return {
+      isGuest: () => false,
+      getCrypto: () => undefined,
+      getAccountDataFromServer: vi
+        .fn()
+        .mockResolvedValue(
+          accountDataId === null ? null : { id: accountDataId },
+        ),
+      setAccountData: vi.fn().mockResolvedValue({}),
+    } as Partial<MatrixClient> as MatrixClient;
+  }
+
+  beforeEach(() => {
+    PosthogAnalytics.resetInstance();
+    optInAnalytics.setValue(true);
+  });
+
+  it("reports under the ID its host assigned, and stores nothing", async () => {
+    const client = mockClient(null);
+    window.matrixclient = client;
+    PosthogAnalytics.configure({
+      ...credentials,
+      matrixBackend: "embedded",
+      hostAnalyticsId: "assigned-by-host",
+    });
+    const identify = vi.spyOn(posthog, "identify");
+
+    PosthogAnalytics.instance.startListeningToSettingsChanges();
+    await vi.waitFor(() =>
+      expect(identify).toHaveBeenCalledWith("assigned-by-host"),
+    );
+
+    // The host owns the user's account, so Element Call must not write to it
+    expect(client.setAccountData).not.toHaveBeenCalled();
+  });
+
+  it("keeps its own ID in account data when it owns the session", async () => {
+    const client = mockClient(null);
+    window.matrixclient = client;
+    PosthogAnalytics.configure({ ...credentials, matrixBackend: "jssdk" });
+
+    PosthogAnalytics.instance.startListeningToSettingsChanges();
+
+    // No ID on the server yet, so one is minted and stored for other devices
+    await vi.waitFor(() => expect(client.setAccountData).toHaveBeenCalled());
+  });
+
+  it("reuses the ID already in account data", async () => {
+    const client = mockClient("stored-earlier");
+    window.matrixclient = client;
+    PosthogAnalytics.configure({ ...credentials, matrixBackend: "jssdk" });
+    const identify = vi.spyOn(posthog, "identify");
+
+    PosthogAnalytics.instance.startListeningToSettingsChanges();
+    await vi.waitFor(() =>
+      expect(identify).toHaveBeenCalledWith("stored-earlier"),
+    );
+
+    expect(client.setAccountData).not.toHaveBeenCalled();
+  });
+
+  it("records how it reaches Matrix as a super property", async () => {
+    window.matrixclient = mockClient("stored-earlier");
+    PosthogAnalytics.configure({ ...credentials, matrixBackend: "embedded" });
+    const register = vi.spyOn(posthog, "register");
+
+    PosthogAnalytics.instance.startListeningToSettingsChanges();
+
+    await vi.waitFor(() =>
+      expect(register).toHaveBeenCalledWith(
+        expect.objectContaining({ matrixBackend: "embedded" }),
+      ),
+    );
+  });
+});

src/analytics/PosthogAnalytics.ts

@@ -15,7 +15,6 @@ import { logger } from "matrix-js-sdk/lib/logger";
 import { type MatrixClient } from "matrix-js-sdk";
 import { type Subscription } from "rxjs";
 
-import { widget } from "../widget";
 import {
   CallEndedTracker,
   CallStartedTracker,
@@ -29,8 +28,6 @@ import {
   CallConnectDurationTracker,
   CallReconnectingTracker,
 } from "./PosthogEvents";
-import { Config } from "../config/Config";
-import { getUrlParams } from "../UrlParams";
 import { optInAnalytics } from "../settings/settings";
 
 /* Posthog analytics tracking.
@@ -140,6 +137,27 @@ interface PlatformProperties {
   cryptoVersion?: string;
 }
 
+/**
+ * How analytics reporting should be set up, supplied by whoever is starting
+ * Element Call rather than discovered from the page it happens to be on.
+ */
+export interface AnalyticsConfig {
+  /** The PostHog project key. Without one, analytics stay switched off. */
+  apiKey?: string;
+  apiHost?: string;
+  /**
+   * How Element Call reaches Matrix. When `embedded`, the host owns the user's
+   * identity: it supplies the analytics ID, and Element Call must not store one
+   * in the user's account data.
+   */
+  matrixBackend: "embedded" | "jssdk";
+  /** The analytics ID the host has assigned to this user, when embedded. */
+  hostAnalyticsId?: string | null;
+}
+
+/** Analytics are off until someone asks for them. */
+const analyticsDisabled: AnalyticsConfig = { matrixBackend: "jssdk" };
+
 export class PosthogAnalytics {
   /* Wrapper for Posthog analytics.
    * 3 modes of anonymity are supported, governed by this.anonymity
@@ -167,13 +185,32 @@ export class PosthogAnalytics {
   private registrationType: RegistrationType = RegistrationType.Guest;
   private optInListener: Subscription | null = null;
 
+  private static analyticsConfig: AnalyticsConfig = analyticsDisabled;
+
+  /**
+   * Sets up analytics reporting. Must be called before the instance is first
+   * used; without it, analytics stay switched off.
+   */
+  public static configure(config: AnalyticsConfig): void {
+    if (this.internalInstance)
+      // Configuration is read once, when the instance is built, so arriving
+      // late means analytics are already running unconfigured.
+      logger.warn(
+        "Analytics were configured after they had already been started; the new configuration will not take effect",
+      );
+    this.analyticsConfig = config;
+  }
+
   public static hasInstance(): boolean {
     return Boolean(this.internalInstance);
   }
 
   public static get instance(): PosthogAnalytics {
     if (!this.internalInstance) {
-      this.internalInstance = new PosthogAnalytics(posthog);
+      this.internalInstance = new PosthogAnalytics(
+        posthog,
+        PosthogAnalytics.analyticsConfig,
+      );
     }
     return this.internalInstance;
   }
@@ -181,20 +218,14 @@ export class PosthogAnalytics {
   public static resetInstance(): void {
     // Reset the singleton instance
     this.internalInstance = null;
+    this.analyticsConfig = analyticsDisabled;
   }
 
-  private constructor(private readonly posthog: PostHog) {
-    let apiKey: string | undefined;
-    let apiHost: string | undefined;
-    if (import.meta.env.VITE_PACKAGE === "embedded") {
-      // for the embedded package we always use the values from the URL as the widget host is responsible for analytics configuration
-      apiKey = getUrlParams().posthogApiKey ?? undefined;
-      apiHost = getUrlParams().posthogApiHost ?? undefined;
-    } else if (import.meta.env.VITE_PACKAGE === "full") {
-      // in full package it is the server responsible for the analytics
-      apiKey = Config.get().posthog?.api_key;
-      apiHost = Config.get().posthog?.api_host;
-    }
+  private constructor(
+    private readonly posthog: PostHog,
+    private readonly config: AnalyticsConfig,
+  ) {
+    const { apiKey, apiHost } = config;
 
     if (apiKey && apiHost) {
       const beforeSend = (event: CaptureResult | null): CaptureResult | null =>
@@ -225,15 +256,15 @@ export class PosthogAnalytics {
     }
   }
 
-  private static getPlatformProperties(): PlatformProperties {
+  private getPlatformProperties(): PlatformProperties {
     const appVersion = import.meta.env.VITE_APP_VERSION || "dev";
     return {
       appVersion,
-      matrixBackend: widget ? "embedded" : "jssdk",
+      matrixBackend: this.config.matrixBackend,
       callBackend: "livekit",
-      cryptoVersion: widget
-        ? undefined
-        : window.matrixclient?.getCrypto()?.getVersion(),
+      // Undefined when Element Call has no crypto of its own, which is the case
+      // whenever a host is doing the encrypting for it.
+      cryptoVersion: window.matrixclient?.getCrypto()?.getVersion(),
     };
   }
 
@@ -283,8 +314,8 @@ export class PosthogAnalytics {
       // different devices to send the same ID.
       let analyticsID = await this.getAnalyticsId();
       try {
-        if (!analyticsID && !widget) {
-          // only try setting up a new analytics ID in the standalone app.
+        if (!analyticsID && this.config.matrixBackend !== "embedded") {
+          // only mint an analytics ID when we are the ones storing it.
 
           // Couldn't retrieve an analytics ID from user settings, so create one and set it on the server.
           // Note there's a race condition here - if two devices do these steps at the same time, last write
@@ -313,8 +344,8 @@ export class PosthogAnalytics {
 
   private async getAnalyticsId(): Promise<string | null> {
     const client: MatrixClient = window.matrixclient;
-    if (widget) {
-      return getUrlParams().posthogUserId;
+    if (this.config.matrixBackend === "embedded") {
+      return this.config.hostAnalyticsId ?? null;
     } else {
       const accountData = await client.getAccountDataFromServer(
         PosthogAnalytics.ANALYTICS_EVENT_TYPE,
@@ -324,7 +355,7 @@ export class PosthogAnalytics {
   }
 
   private async setAccountAnalyticsId(analyticsID: string): Promise<void> {
-    if (!widget) {
+    if (this.config.matrixBackend !== "embedded") {
       const client = window.matrixclient;
 
       // the analytics ID only needs to be set in the standalone version.
@@ -362,7 +393,7 @@ export class PosthogAnalytics {
     // These properties will be subsequently passed in every event.
     //
     // This only needs to be done once per page lifetime. Note that getPlatformProperties
-    this.platformSuperProperties = PosthogAnalytics.getPlatformProperties();
+    this.platformSuperProperties = this.getPlatformProperties();
     this.registerSuperProperties({
       ...this.platformSuperProperties,
       registrationType:

src/auth/useInteractiveRegistration.ts

@@ -17,7 +17,7 @@ import { logger } from "matrix-js-sdk/lib/logger";
 import { initClient } from "../utils/matrix";
 import { type Session } from "../ClientContext";
 import { Config } from "../config/Config";
-import { widget } from "../widget";
+import { useUrlParams } from "../UrlParams";
 
 export const useInteractiveRegistration = (
   oldClient?: MatrixClient,
@@ -32,6 +32,7 @@ export const useInteractiveRegistration = (
     passwordlessUser: boolean,
   ) => Promise<[MatrixClient, Session]>;
 } => {
+  const { isWidget } = useUrlParams();
   const [privacyPolicyUrl, setPrivacyPolicyUrl] = useState<string | undefined>(
     undefined,
   );
@@ -47,7 +48,7 @@ export const useInteractiveRegistration = (
   }
 
   useEffect(() => {
-    if (widget) return;
+    if (isWidget) return;
     // An empty registerRequest is used to get the privacy policy and recaptcha key.
     authClient.current!.registerRequest({}).catch((error) => {
       setPrivacyPolicyUrl(
@@ -55,7 +56,7 @@ export const useInteractiveRegistration = (
       );
       setRecaptchaKey(error.data?.params["m.login.recaptcha"]?.public_key);
     });
-  }, []);
+  }, [isWidget]);
 
   const register = useCallback(
     async (

src/auth/useRegisterPasswordlessUser.ts

@@ -12,7 +12,7 @@ import { useClient } from "../ClientContext";
 import { useInteractiveRegistration } from "../auth/useInteractiveRegistration";
 import { generateRandomName } from "../auth/generateRandomName";
 import { useRecaptcha } from "../auth/useRecaptcha";
-import { widget } from "../widget";
+import { useUrlParams } from "../UrlParams";
 
 interface UseRegisterPasswordlessUserType {
   privacyPolicyUrl?: string;
@@ -22,6 +22,7 @@ interface UseRegisterPasswordlessUserType {
 
 export function useRegisterPasswordlessUser(): UseRegisterPasswordlessUserType {
   const { setClient } = useClient();
+  const { isWidget } = useUrlParams();
   const { privacyPolicyUrl, recaptchaKey, register } =
     useInteractiveRegistration();
   const { execute, reset, recaptchaId } = useRecaptcha(recaptchaKey);
@@ -31,7 +32,7 @@ export function useRegisterPasswordlessUser(): UseRegisterPasswordlessUserType {
       if (!setClient) {
         throw new Error("No client context");
       }
-      if (widget) {
+      if (isWidget) {
         throw new Error(
           "Registration was skipped: We should never try to register password-less user in embedded mode.",
         );
@@ -53,7 +54,7 @@ export function useRegisterPasswordlessUser(): UseRegisterPasswordlessUserType {
         throw e;
       }
     },
-    [execute, reset, register, setClient],
+    [execute, reset, register, setClient, isWidget],
   );
 
   return { privacyPolicyUrl, registerPasswordlessUser, recaptchaId };

src/base.css

@@ -0,0 +1,223 @@
+/*
+Copyright 2021-2024 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+/* The styles Element Call needs wherever it is shown: the design tokens, fonts
+and element defaults its own stylesheets build on top of.
+
+Split out from index.css so that Element Call as a component can have these
+without also being given the standalone page's layout, which would style the
+host's own document. What remains here still speaks of the
+document — normalize.css and the typography below use bare element selectors,
+and the custom properties are declared on `:root` — which is right for the
+page, and is why the component build rewrites it: there every selector is
+confined to Element Call's root element (see component/build/scopeStylesToRoot.ts),
+with `html`, `body` and `:root` becoming that element. Nothing needs to be
+written differently here for that to work, but nothing here may rely on
+reaching the host's document either.
+
+Nothing here should depend on where it lands relative to Element Call's
+component stylesheets: the bundler decides that, and it decides differently for
+the app and for the component build. */
+
+@layer normalize, compound-legacy, compound;
+
+@import url("@fontsource/inter/400.css");
+@import url("@fontsource/inter/500.css");
+@import url("@fontsource/inter/600.css");
+@import url("@fontsource/inter/700.css");
+@import url("@fontsource/inconsolata/400.css");
+@import url("@fontsource/inconsolata/700.css");
+
+@import url("normalize.css/normalize.css") layer(normalize);
+@import url("@vector-im/compound-design-tokens/assets/web/css/compound-design-tokens.css") layer(compound);
+@import url("@vector-im/compound-web/dist/style.css") layer(compound.components);
+
+:root {
+  --font-scale: 1;
+  --font-size-micro: calc(10px * var(--font-scale));
+  --font-size-caption: calc(12px * var(--font-scale));
+  --font-size-body: calc(15px * var(--font-scale));
+  --font-size-subtitle: calc(18px * var(--font-scale));
+  --font-size-title: calc(24px * var(--font-scale));
+  --font-size-headline: calc(32px * var(--font-scale));
+
+  --cpd-color-border-accent: var(--cpd-color-green-800);
+  /* The distance to inset non-full-width content from the edge of Element
+  Call's root along the inline axis. This ramps up from 16px for typical mobile
+  windows, to 96px for typical desktop windows, and accounts for the safe area.
+  Container units resolve where the property is used, so this must only be used
+  by elements whose nearest query container is the root. */
+  --content-inset-left: calc(
+    env(safe-area-inset-left) +
+      min(
+        var(--cpd-space-24x),
+        max(var(--cpd-space-4x), calc((100cqw - 900px) / 3))
+      )
+  );
+  --content-inset-right: calc(
+    env(safe-area-inset-right) +
+      min(
+        var(--cpd-space-24x),
+        max(var(--cpd-space-4x), calc((100cqw - 900px) / 3))
+      )
+  );
+  --small-drop-shadow: 0px 1.2px 2.4px 0px rgba(0, 0, 0, 0.15);
+  --big-drop-shadow: 0px 0px 24px 0px #1b1d221a;
+  --subtle-drop-shadow: 0px 1px 2px 0px rgba(16, 24, 40, 0.05);
+
+  --call-view-overlay-layer: 1;
+  --call-view-header-footer-layer: 2;
+}
+
+:root,
+[class*="cpd-theme-"] {
+  --video-tile-background: var(--cpd-color-bg-subtle-secondary);
+}
+
+/* The breakpoints in Element Call's stylesheets are container queries against
+this element rather than media queries against the viewport. For the standalone
+app the two are the same thing, since the root is the page; for a host that
+embeds Element Call in a corner of its own page they are not, and it is the
+corner that the layout has to fit.
+
+For the same reason, lengths that were once a share of the viewport (`100vw`)
+are a share of the nearest query container (`100cqw`). Container units cannot
+name their container, so they only mean this element where no other query
+container — a spotlight layout, a media tile — lies in between; check that
+before using one further down the tree. */
+[data-element-call-root] {
+  container: element-call / size;
+}
+
+.cpd-theme-dark {
+  --cpd-color-border-accent: var(--cpd-color-green-1100);
+  --stopgap-color-on-solid-accent: var(--cpd-color-text-primary);
+  --stopgap-background-85: rgba(16, 19, 23, 0.85);
+}
+
+@media (min-height: 330px) {
+  [data-element-call-root][data-background="gradient"]::before {
+    content: "";
+    position: fixed;
+    /* Chromium abruptly fades our images to fully transparent at the edge of
+    the element. If we just make the element a little bigger than the viewport,
+    this is no longer visible. */
+    inset: -20px;
+    background-image: url("graphics/mobile-gradient.png");
+    background-size: 1400px 305px;
+    background-position: bottom;
+    background-repeat: no-repeat;
+  }
+
+  [data-element-call-root][data-background="gradient"][data-platform="desktop"]::before {
+    background-image: url("graphics/desktop-gradient.png");
+    background-size: max(1440px, 100cqw) max(1440px, 100cqh);
+    background-position: center;
+  }
+}
+
+/* We use this to not render the page at all until we know the theme.*/
+.no-theme {
+  opacity: 0;
+}
+
+/* On Android and iOS, prefer native system fonts. The global.css file of
+Compound Web is where these variables ultimately get consumed to set the page's
+font-family. */
+[data-element-call-root][data-platform="android"] {
+  --cpd-font-family-sans: "Roboto", "Noto", "Inter", sans-serif;
+}
+
+[data-element-call-root][data-platform="ios"] {
+  --cpd-font-family-sans:
+    -apple-system, BlinkMacSystemFont, "Inter", sans-serif;
+}
+
+@layer compound-legacy {
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6,
+  p,
+  a {
+    margin-top: 0;
+  }
+
+  /* Headline Semi Bold */
+  h1 {
+    font-weight: 600;
+    font-size: var(--font-size-headline);
+  }
+
+  /* Title */
+  h2 {
+    font-weight: 600;
+    font-size: var(--font-size-title);
+  }
+
+  /* Subtitle */
+  h3 {
+    font-weight: 600;
+    font-size: var(--font-size-subtitle);
+  }
+
+  /* Body Semi Bold */
+  h4 {
+    font-weight: 600;
+    font-size: var(--font-size-body);
+  }
+
+  h1,
+  h2,
+  h3 {
+    line-height: 1.2;
+  }
+
+  /* Body */
+  p {
+    font-size: var(--font-size-body);
+    line-height: var(--font-size-title);
+  }
+
+  hr {
+    width: calc(100% - 24px);
+    border: none;
+    border-top: 1px solid var(--cpd-color-border-interactive-secondary);
+    color: var(--cpd-color-border-interactive-secondary);
+    overflow: visible;
+    text-align: center;
+    height: 5px;
+    font-weight: 600;
+    font-size: var(--font-size-body);
+    line-height: 24px;
+    margin: 0 12px;
+  }
+
+  summary {
+    font-size: var(--font-size-body);
+  }
+
+  details > :not(summary) {
+    margin-left: var(--font-size-body);
+  }
+
+  details[open] > summary {
+    margin-bottom: var(--font-size-body);
+  }
+}
+
+/* normalize.css sets the focus rings on buttons in Firefox to an unusual custom
+outline, which is inconsistent with our other components and is not sufficiently
+visible to be accessible. This resets it back to 'auto'. */
+button:-moz-focusring,
+[type="button"]:-moz-focusring,
+[type="reset"]:-moz-focusring,
+[type="submit"]:-moz-focusring {
+  outline: auto;
+}

src/button/LeaveToHomeLink.tsx

@@ -0,0 +1,40 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { type FC, type MouseEvent, type ReactNode, useCallback } from "react";
+import { Link } from "@vector-im/compound-web";
+
+import { useLeaveToHome } from "../LeaveToHomeContext";
+
+interface Props {
+  className?: string;
+  children: ReactNode;
+}
+
+/**
+ * A link out of the call, to wherever the user came from. Renders nothing when
+ * there is nowhere to go (see {@link useLeaveToHome}).
+ */
+export const LeaveToHomeLink: FC<Props> = ({ className, children }) => {
+  const leaveToHome = useLeaveToHome();
+  const onClick = useCallback(
+    (e: MouseEvent<HTMLAnchorElement>) => {
+      e.preventDefault();
+      leaveToHome?.();
+    },
+    [leaveToHome],
+  );
+
+  if (leaveToHome === null) return null;
+  // Where this leads is the shell's business, so the link has no address of
+  // its own to offer
+  return (
+    <Link className={className} href="#" onClick={onClick}>
+      {children}
+    </Link>
+  );
+};

src/button/ReactionToggleButton.module.css

@@ -10,7 +10,7 @@
   width: fit-content;
 }
 
-@media (max-width: 420px) {
+@container element-call (max-width: 420px) {
   .reactionPopupMenu {
     --reaction-button-padding: 8px;
     --reaction-button-fontsize: 16px;
@@ -19,7 +19,12 @@
 }
 
 div.reactionPopupMenuRoot.reactionPopupMenuModal {
-  --overlay-top: 82vh;
+  /* Down near the footer it belongs to, rather than centred like other modals.
+  A percentage, not a viewport unit: the overlay is positioned `fixed`, so this
+  resolves against the page in the standalone app and against the container
+  when a host embeds us — where 82vh would put it below the container
+  entirely. */
+  --overlay-top: 82%;
   width: fit-content;
 }
 
@@ -30,7 +35,7 @@ div.reactionPopupMenuRoot {
 
 .reactionPopupMenuRoot > div {
   width: fit-content;
-  max-width: 100vw;
+  max-width: 100cqw;
 }
 
 div.reactionPopupMenuRoot.reactionPopupMenuModal > div > div {

src/components/AudioLevelMeter.module.css

@@ -0,0 +1,76 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+.meter {
+  display: flex;
+  align-items: center;
+  gap: var(--cpd-space-3x);
+  padding-block: var(--cpd-space-2x);
+  padding-inline-start: var(--cpd-space-4x);
+  /* Stop the bars where the device labels stop rather than at the menu edge:
+     a menu item keeps a 4x margin after its label plus a 2x column reserved
+     for the chevron, on top of the menu's own 4x padding. */
+  padding-inline-end: calc(2 * var(--cpd-space-4x) + var(--cpd-space-2x));
+  border-radius: var(--cpd-radius-pill-effect);
+}
+
+.meter:focus-visible {
+  outline: 2px solid var(--cpd-color-border-focused);
+  outline-offset: -2px;
+}
+
+.icon {
+  color: var(--cpd-color-icon-secondary);
+  flex-shrink: 0;
+}
+
+.bars {
+  display: flex;
+  align-items: center;
+  gap: var(--cpd-space-2x);
+  flex: 1;
+}
+
+.bar {
+  /* The bars share out whatever the gaps leave over, so the gap above and the
+     bar count together set how thick a bar is. Across the inset row that lands
+     near 6px per bar against the 8px gap, as in the design. */
+  flex: 1;
+  height: 20px;
+  border-radius: var(--cpd-radius-pill-effect);
+  background-color: var(--cpd-color-bg-subtle-primary);
+  transition: background-color 60ms linear;
+}
+
+.lit {
+  background-color: var(--cpd-color-icon-accent-primary);
+}
+
+.unavailable .icon,
+.unavailable .bar {
+  opacity: 0.5;
+}
+
+.message {
+  display: flex;
+  align-items: center;
+  gap: var(--cpd-space-3x);
+  padding-block: var(--cpd-space-2x);
+  padding-inline-start: var(--cpd-space-4x);
+  padding-inline-end: calc(2 * var(--cpd-space-4x) + var(--cpd-space-2x));
+  color: var(--cpd-color-text-secondary);
+  font: var(--cpd-font-body-sm-regular);
+}
+
+.srOnly {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}

src/components/AudioLevelMeter.stories.tsx

@@ -0,0 +1,81 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { expect, within } from "storybook/test";
+import { type JSX } from "react";
+
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { AudioLevelMeter } from "./AudioLevelMeter";
+
+const meta = {
+  component: AudioLevelMeter,
+  // The meter is only ever seen inside the audio menu, so give it a comparable
+  // width to judge the bar spacing against.
+  decorators: [
+    (Story): JSX.Element => (
+      <div style={{ width: 300 }}>
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof AudioLevelMeter>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Silent: Story = {
+  args: { state: { type: "active", level: 0 } },
+  play: async ({ canvasElement }) => {
+    const meter = within(canvasElement).getByRole("meter");
+    await expect(meter).toHaveAttribute("aria-valuetext", "No sound detected");
+  },
+};
+
+export const Speaking: Story = {
+  args: { state: { type: "active", level: 0.45 } },
+  play: async ({ canvasElement }) => {
+    const meter = within(canvasElement).getByRole("meter");
+    await expect(meter).toHaveAttribute("aria-valuetext", "Picking up sound");
+  },
+};
+
+export const Loud: Story = {
+  args: { state: { type: "active", level: 0.95 } },
+};
+
+/** Named apart from the footer's own "Unavailable Media Devices" story. */
+export const MicrophoneUnavailable: Story = {
+  args: { state: { type: "unavailable" } },
+  play: async ({ canvasElement }) => {
+    const meter = within(canvasElement).getByRole("meter");
+    await expect(meter).toHaveAttribute("data-unavailable", "true");
+    // The greying is the point, and it is done in CSS: an attribute alone
+    // would still be there with the rule gone.
+    const bar = meter.querySelector("span");
+    await expect(Number(getComputedStyle(bar!).opacity)).toBeLessThan(1);
+  },
+};
+
+export const NoMicrophone: Story = {
+  args: { state: { type: "absent" } },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.queryByRole("meter")).toBe(null);
+    await expect(canvas.getByText(/No microphone found/)).toBeInTheDocument();
+  },
+};
+
+export const PermissionDenied: Story = {
+  args: { state: { type: "denied" } },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.queryByRole("meter")).toBe(null);
+    await expect(
+      canvas.getByText(/Microphone access is blocked/),
+    ).toBeInTheDocument();
+  },
+};

src/components/AudioLevelMeter.test.tsx

@@ -0,0 +1,72 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { describe, expect, test } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { AudioLevelMeter } from "./AudioLevelMeter";
+
+describe("AudioLevelMeter", () => {
+  test("a missing microphone is named rather than drawn as silence", () => {
+    render(<AudioLevelMeter state={{ type: "absent" }} />);
+    expect(screen.getByTestId("mic_absent")).toHaveTextContent(
+      /no microphone found/i,
+    );
+    // Bars resting at zero would read as a microphone that hears nothing,
+    // which is a different thing and the one people act on.
+    expect(screen.queryByRole("meter")).toBe(null);
+  });
+
+  test("a denied microphone renders a hint instead of the meter", () => {
+    render(<AudioLevelMeter state={{ type: "denied" }} />);
+    expect(screen.getByTestId("mic_level_denied")).toHaveTextContent(
+      /microphone access is blocked/i,
+    );
+    // A hint replaces the meter rather than sitting next to a dead one.
+    expect(screen.queryByRole("meter")).toBe(null);
+  });
+
+  test("level indicator greys out when the microphone is unavailable", () => {
+    render(<AudioLevelMeter state={{ type: "unavailable" }} />);
+    const meter = screen.getByRole("meter");
+    expect(meter).toHaveAttribute("data-unavailable", "true");
+    expect(meter).toHaveAttribute("aria-valuetext", "Microphone unavailable");
+  });
+
+  test("level indicator reports its level to assistive technology", () => {
+    const { rerender } = render(
+      <AudioLevelMeter state={{ type: "active", level: 0 }} />,
+    );
+    const meter = screen.getByRole("meter");
+    expect(meter).toHaveAttribute("aria-valuenow", "0");
+    expect(meter).toHaveAttribute("aria-valuetext", "No sound detected");
+
+    rerender(<AudioLevelMeter state={{ type: "active", level: 0.7 }} />);
+    expect(screen.getByRole("meter")).toHaveAttribute(
+      "aria-valuetext",
+      "Picking up sound",
+    );
+  });
+
+  test("level indicator announces its state only while focused", async () => {
+    const user = userEvent.setup();
+    render(<AudioLevelMeter state={{ type: "active", level: 0.7 }} />);
+    const meter = screen.getByRole("meter");
+
+    // Nothing is announced until the user puts the meter in focus, so the
+    // level does not talk over the rest of the menu.
+    const announcer = meter.querySelector("[aria-live]");
+    expect(announcer).toHaveAttribute("aria-live", "off");
+    await user.tab();
+    expect(meter).toHaveFocus();
+    expect(announcer).toHaveAttribute("aria-live", "polite");
+    expect(announcer).toHaveTextContent("Picking up sound");
+    await user.tab();
+    expect(announcer).toHaveAttribute("aria-live", "off");
+  });
+});

src/components/AudioLevelMeter.tsx

@@ -0,0 +1,133 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { type FC, useState } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  MicOnIcon,
+  MicOffIcon,
+} from "@vector-im/compound-design-tokens/assets/web/icons";
+import classNames from "classnames";
+
+import styles from "./AudioLevelMeter.module.css";
+import {
+  useMicrophoneLevel,
+  type MicrophoneLevelState,
+} from "./useMicrophoneLevel";
+
+// The level is quantised into this many bars. They share the row, so the
+// count also sets how thick they are.
+const BAR_COUNT = 18;
+/**
+ * Level below which the meter reads as silent. Above the noise floor of a
+ * typical desk microphone, so an idle room does not announce itself as sound.
+ */
+const SPEECH_THRESHOLD = 0.06;
+
+export interface AudioLevelMeterProps {
+  state: MicrophoneLevelState;
+}
+
+/**
+ * A live indicator of the signal level at the selected microphone.
+ *
+ * Focusable, so that a screen reader user can put it in focus and hear whether
+ * the microphone is picking anything up; the bars alone carry that information
+ * for everyone else.
+ */
+export const AudioLevelMeter: FC<AudioLevelMeterProps> = ({ state }) => {
+  const { t } = useTranslation();
+  const [focused, setFocused] = useState(false);
+
+  // Bars resting at zero would read as a microphone that hears nothing, which
+  // is a different thing and the one people act on.
+  if (state.type === "absent")
+    return (
+      <div className={styles.message} data-testid="mic_absent">
+        <MicOffIcon width={24} height={24} aria-hidden />
+        <span>{t("audio_menu.mic_absent")}</span>
+      </div>
+    );
+
+  if (state.type === "denied")
+    return (
+      <div className={styles.message} data-testid="mic_level_denied">
+        <MicOffIcon width={24} height={24} aria-hidden />
+        <span>{t("audio_menu.mic_permission_denied")}</span>
+      </div>
+    );
+
+  const unavailable = state.type === "unavailable";
+  const level = state.type === "active" ? state.level : 0;
+  const litBars = unavailable ? 0 : Math.round(level * BAR_COUNT);
+  const speaking = !unavailable && level >= SPEECH_THRESHOLD;
+  const stateText = unavailable
+    ? t("audio_menu.mic_unavailable")
+    : speaking
+      ? t("audio_menu.mic_level_active")
+      : t("audio_menu.mic_level_silent");
+
+  return (
+    <div
+      className={classNames(styles.meter, {
+        [styles.unavailable]: unavailable,
+      })}
+      data-testid="mic_level_meter"
+      data-unavailable={unavailable || undefined}
+      role="meter"
+      // The meter is the only place the "is my microphone working?" answer
+      // lives, so it has to be reachable without a pointer even though a
+      // meter is not an interactive control.
+      // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
+      tabIndex={0}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+      aria-label={t("audio_menu.mic_level_label")}
+      aria-valuemin={0}
+      aria-valuemax={1}
+      aria-valuenow={level}
+      aria-valuetext={stateText}
+    >
+      <MicOnIcon width={24} height={24} className={styles.icon} aria-hidden />
+      <div className={styles.bars}>
+        {Array.from({ length: BAR_COUNT }, (_, i) => (
+          <span
+            key={i}
+            className={classNames(styles.bar, { [styles.lit]: i < litBars })}
+          />
+        ))}
+      </div>
+      {/* Announces changes only while the meter holds focus, so the level does
+          not talk over a screen reader reading the rest of the menu. The text
+          stays in the DOM either way: removing it on blur would hand the
+          menu's focus trap an empty active element mid-Tab, and it would pull
+          focus back into the menu instead of letting it reach the slider. */}
+      <span className={styles.srOnly} aria-live={focused ? "polite" : "off"}>
+        {stateText}
+      </span>
+    </div>
+  );
+};
+
+export interface MicrophoneLevelProps {
+  /** The microphone to follow, or undefined if none is selected. */
+  deviceId: string | undefined;
+  /** Whether to hold a capture and report a level at all. */
+  active: boolean;
+}
+
+/**
+ * The level meter, following a microphone of its own.
+ *
+ * Re-renders when the level moves to another bar, and only itself.
+ */
+export const MicrophoneLevel: FC<MicrophoneLevelProps> = ({
+  deviceId,
+  active,
+}) => (
+  <AudioLevelMeter state={useMicrophoneLevel(deviceId, active, BAR_COUNT)} />
+);

src/components/CallFooter.module.css

@@ -77,7 +77,7 @@ Please see LICENSE in the repository root for full details.
 }
 
 /*First hide the logo*/
-@media (max-width: 750px) {
+@container element-call (max-width: 750px) {
   .logo {
     display: none;
   }
@@ -94,7 +94,7 @@ Please see LICENSE in the repository root for full details.
 With the logo hidden >500px is enough space to show overflow, buttons, layout.
 Once we exceed 500 we hide everything except the buttons.
 */
-@media (max-width: 500px) {
+@container element-call (max-width: 500px) {
   .footer {
     grid-template-areas: "buttons buttons buttons";
   }
@@ -115,27 +115,27 @@ Once we exceed 500 we hide everything except the buttons.
   }
 }
 
-@media (max-height: 800px) {
+@container element-call (max-height: 800px) {
   .footer {
     padding-block: var(--cpd-space-8x)
       calc(env(safe-area-inset-bottom) + var(--cpd-space-8x));
   }
 }
 
-@media (max-height: 400px) {
+@container element-call (max-height: 400px) {
   .footer {
     padding-block: var(--cpd-space-4x)
       calc(env(safe-area-inset-bottom) + var(--cpd-space-4x));
   }
 }
 
-@media (max-width: 370px) {
+@container element-call (max-width: 370px) {
   .shareScreen {
     display: none;
   }
 
   /* PIP custom css */
-  @media (max-height: 400px) {
+  @container element-call (max-height: 400px) {
     .shareScreen {
       display: flex;
     }
@@ -148,13 +148,13 @@ Once we exceed 500 we hide everything except the buttons.
   }
 }
 
-@media (max-width: 320px) {
+@container element-call (max-width: 320px) {
   .raiseHand {
     display: none;
   }
 }
 
-@media (min-width: 800px) {
+@container element-call (min-width: 800px) {
   .buttons {
     gap: var(--cpd-space-4x);
   }

src/components/CallFooter.stories.tsx

@@ -5,7 +5,7 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE in the repository root for full details.
 */
 
-import { expect, fn, userEvent, within } from "storybook/test";
+import { expect, fn, screen, userEvent, within } from "storybook/test";
 import { BehaviorSubject } from "rxjs";
 import { type JSX, type ReactNode } from "react";
 import { Link } from "@vector-im/compound-web";
@@ -29,7 +29,9 @@ const reactionData = {
   reactions$: new BehaviorSubject({}),
 };
 
-const mediaDevices = new MediaDevices(globalScope);
+const mediaDevices = new MediaDevices(globalScope, {
+  controlledAudioDevices: false,
+});
 
 /**
  * A wrapper component that is used for:
@@ -101,6 +103,8 @@ const meta = {
     toggleAudio: fnArgType,
     toggleVideo: fnArgType,
     hangup: fnArgType,
+    selectAudioOutputOption: fnArgType,
+    setSoundEffectVolume: fnArgType,
   },
 } satisfies Meta<typeof CallFooterStoryWrapper>;
 
@@ -140,6 +144,11 @@ export const Default: Story = {
     selectedVideo: undefined,
     selectAudioButtonOption: undefined,
     selectVideoButtonOption: undefined,
+    audioOutputOptions: [],
+    selectedAudioOutput: undefined,
+    selectAudioOutputOption: undefined,
+    soundEffectVolume: 0.5,
+    setSoundEffectVolume: undefined,
   },
   parameters: {
     layout: "fullscreen",
@@ -352,10 +361,29 @@ export const MobileLayout: Story = {
   },
 };
 
+/** Devices and controls of the audio menu, as the lobby offers them. */
+const audioMenuArgs = {
+  audioOptions: [
+    { label: { type: "name", name: "MacBook Pro Microphone" }, id: "1" },
+    { label: { type: "name", name: "Jabra Evolve 65" }, id: "2" },
+  ],
+  selectedAudio: "1",
+  selectAudioButtonOption: fn(),
+  audioOutputOptions: [
+    { label: { type: "default", name: "MacBook Pro Speakers" }, id: "" },
+    { label: { type: "name", name: "Jabra Evolve 65" }, id: "2" },
+  ],
+  selectedAudioOutput: "",
+  selectAudioOutputOption: fn(),
+  soundEffectVolume: 0.5,
+  setSoundEffectVolume: fn(),
+} satisfies Partial<FooterSnapshot>;
+
 export const Lobby: Story = {
   ...Default,
   args: {
     ...Default.args,
+    ...audioMenuArgs,
     showLogo: false,
     openSettings: undefined,
     layout: null,
@@ -370,6 +398,7 @@ export const LobbyMobile: Story = {
   ...Default,
   args: {
     ...Default.args,
+    ...audioMenuArgs,
     showLogo: false,
 
     layout: null,
@@ -413,3 +442,105 @@ export const LobbyRecentButtonMobile: Story = {
     ...Default.parameters,
   },
 };
+
+/** The microphone chevron opens the audio menu: microphones and speakers. */
+export const WithAudioMenu: Story = {
+  ...Default,
+  args: {
+    ...Default.args,
+    audioEnabled: true,
+    ...audioMenuArgs,
+  },
+  play: async ({ args, canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole("button", { name: "Microphone" }));
+
+    const menu = within(await screen.findByRole("menu"));
+    await expect(
+      menu.getByRole("heading", { name: "Audio controls" }),
+    ).toBeInTheDocument();
+    // The headset appears in both groups under the same name, as a real one
+    // does. The speaker rows are the scroll area's own children; the
+    // microphone rows sit one level deeper, inside their group.
+    const scroll = menu.getByTestId("audio_menu_scroll");
+    const outputs = [...scroll.children].filter(
+      (el) => el.getAttribute("role") === "menuitemradio",
+    );
+    await userEvent.click(outputs[1]);
+    await expect(args.selectAudioOutputOption).toHaveBeenCalledWith("2");
+    // The menu stays open after a selection.
+    await expect(screen.getByRole("menu")).toBeInTheDocument();
+    await expect(
+      menu.getByRole("slider", { name: /Sound effect volume/ }),
+    ).toBeInTheDocument();
+  },
+};
+
+/** One output only: the speaker group names it without offering a choice. */
+export const WithSingleAudioOutput: Story = {
+  ...WithAudioMenu,
+  args: {
+    ...WithAudioMenu.args,
+    audioOutputOptions: [
+      { label: { type: "default", name: "MacBook Pro Speakers" }, id: "" },
+    ],
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole("button", { name: "Microphone" }));
+
+    await expect(
+      await screen.findByTestId("speaker_readonly"),
+    ).toHaveTextContent("MacBook Pro Speakers");
+    await expect(
+      screen.queryByRole("menuitemradio", { name: /Speakers/ }),
+    ).toBe(null);
+  },
+};
+
+/**
+ * More devices than fit on screen: the heading and the slider stay put while
+ * the device lists scroll between them.
+ */
+export const WithManyDevices: Story = {
+  ...WithAudioMenu,
+  args: {
+    ...WithAudioMenu.args,
+    audioOptions: Array.from({ length: 12 }, (_, i) => ({
+      label: { type: "name", name: `Microphone ${i + 1} (USB Audio Device)` },
+      id: `mic-${i}`,
+    })),
+    selectedAudio: "mic-0",
+    audioOutputOptions: Array.from({ length: 8 }, (_, i) => ({
+      label: { type: "name", name: `Speaker ${i + 1} (DisplayPort)` },
+      id: `out-${i}`,
+    })),
+    selectedAudioOutput: "out-0",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole("button", { name: "Microphone" }));
+    const menu = await screen.findByRole("menu");
+    const heading = within(menu).getByRole("heading", {
+      name: "Audio controls",
+    });
+    const slider = within(menu).getByRole("slider");
+    const scroll = within(menu).getByTestId("audio_menu_scroll");
+
+    // The menu slides in; measure once it has settled.
+    await Promise.all(
+      menu.getAnimations({ subtree: true }).map(async (a) => a.finished),
+    );
+
+    // The whole menu is on screen, so the heading and the slider are too.
+    const menuBox = menu.getBoundingClientRect();
+    await expect(menuBox.top).toBeGreaterThanOrEqual(0);
+    await expect(menuBox.bottom).toBeLessThanOrEqual(window.innerHeight);
+    await expect(heading.getBoundingClientRect().top).toBeGreaterThanOrEqual(0);
+    await expect(slider.getBoundingClientRect().bottom).toBeLessThanOrEqual(
+      window.innerHeight,
+    );
+    // Only the device lists scroll.
+    await expect(scroll.scrollHeight).toBeGreaterThan(scroll.clientHeight);
+  },
+};

src/components/CallFooter.test.tsx

@@ -0,0 +1,179 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { BehaviorSubject } from "rxjs";
+import { Root as Form, TooltipProvider } from "@vector-im/compound-web";
+import { type JSX, type ReactNode } from "react";
+
+import { CallFooter } from "./CallFooter";
+import { DeviceSelection } from "../settings/DeviceSelection";
+import { MediaDevicesContext } from "../MediaDevicesContext";
+import { ReactionsSenderContext } from "../reactions/useReactionsSender";
+import {
+  type AudioOutputDeviceLabel,
+  type MediaDevices,
+  type SelectedAudioOutputDevice,
+} from "../state/MediaDevices";
+import { constant } from "../state/Behavior";
+import { mockMediaDevices } from "../utils/test";
+import {
+  soundEffectVolume as soundEffectVolumeSetting,
+  useSetting,
+} from "../settings/settings";
+import { getBasicCallViewModelEnvironment } from "../utils/test-viewmodel";
+import { alice, local } from "../utils/test-fixtures";
+
+describe("CallFooter", () => {
+  afterEach(() => soundEffectVolumeSetting.setValue(0.5));
+
+  test("sound effects volume from the menu applies to the next effect", async () => {
+    const user = userEvent.setup();
+    renderFooter(mediaDevicesWithOutputs());
+
+    await user.click(screen.getByRole("button", { name: "Microphone" }));
+    await screen.findByRole("menu");
+    await user.keyboard("[ArrowDown]");
+    await user.tab();
+    await user.tab();
+    await user.keyboard("[ArrowRight]");
+
+    // The committed value lands in the setting the sound-effect player reads,
+    // so the next effect plays at the new level.
+    expect(soundEffectVolumeSetting.value$.value).toBe(0.51);
+  });
+
+  test("sound effects volume is shared between menu and settings", async () => {
+    const user = userEvent.setup();
+    renderFooter(mediaDevicesWithOutputs(), <SettingsVolume />);
+
+    // Set from the menu, shown in settings.
+    await user.click(screen.getByRole("button", { name: "Microphone" }));
+    await screen.findByRole("menu");
+    await user.keyboard("[ArrowDown]");
+    await user.tab();
+    await user.tab();
+    await user.keyboard("[ArrowRight]");
+    await user.keyboard("[Escape]");
+    expect(screen.getByRole("status")).toHaveTextContent("51%");
+
+    // Set from settings, shown in the menu.
+    await user.click(screen.getByRole("button", { name: "Set to 20%" }));
+    await user.click(screen.getByRole("button", { name: "Microphone" }));
+    expect(
+      await screen.findByRole("slider", { name: /Sound effect volume/ }),
+    ).toHaveAttribute("aria-valuenow", "0.2");
+  });
+
+  test("audio menu is headed Audio controls", async () => {
+    const user = userEvent.setup();
+    renderFooter(mediaDevicesWithOutputs());
+
+    await user.click(screen.getByRole("button", { name: "Microphone" }));
+
+    const menu = await screen.findByRole("menu");
+    expect(
+      within(menu).getByRole("heading", { name: "Audio controls" }),
+    ).toBeInTheDocument();
+  });
+
+  test("audio output selection is shared between menu and settings", async () => {
+    const user = userEvent.setup();
+    const mediaDevices = mediaDevicesWithOutputs();
+    renderFooter(
+      mediaDevices,
+      <Form>
+        <DeviceSelection
+          device={mediaDevices.audioOutput}
+          title="Speaker"
+          numberedLabel={(n) => `Speaker ${n}`}
+        />
+      </Form>,
+    );
+
+    // Chosen in the menu, shown in settings. The open menu hides the rest of
+    // the page from assistive technology, so it closes before settings is read.
+    await user.click(screen.getByRole("button", { name: "Microphone" }));
+    await user.click(
+      await screen.findByRole("menuitemradio", { name: "Headset" }),
+    );
+    await user.keyboard("[Escape]");
+    expect(screen.getByRole("radio", { name: "Headset" })).toBeChecked();
+
+    // Chosen in settings, shown in the menu.
+    await user.click(screen.getByRole("radio", { name: "Built-in Speakers" }));
+    await user.click(screen.getByRole("button", { name: "Microphone" }));
+    expect(
+      await screen.findByRole("menuitemradio", { name: "Built-in Speakers" }),
+    ).toHaveAttribute("aria-checked", "true");
+    expect(
+      screen.getByRole("menuitemradio", { name: "Headset" }),
+    ).toHaveAttribute("aria-checked", "false");
+  });
+
+  /** The in-call footer over its real view model, with settings beside it. */
+  function renderFooter(
+    mediaDevices: MediaDevices,
+    settings?: ReactNode,
+  ): void {
+    const { footerVm } = getBasicCallViewModelEnvironment(
+      [local, alice],
+      undefined,
+      mediaDevices,
+    );
+    render(
+      <TooltipProvider>
+        <MediaDevicesContext value={mediaDevices}>
+          <ReactionsSenderContext
+            value={{
+              supportsReactions: false,
+              toggleRaisedHand: async (): Promise<void> => Promise.resolve(),
+              sendReaction: async (): Promise<void> => Promise.resolve(),
+            }}
+          >
+            <CallFooter vm={footerVm} />
+            {settings}
+          </ReactionsSenderContext>
+        </MediaDevicesContext>
+      </TooltipProvider>,
+    );
+  }
+
+  /** Reads and writes the volume the way the settings dialog does. */
+  function SettingsVolume(): JSX.Element {
+    const [volume, setVolume] = useSetting(soundEffectVolumeSetting);
+    return (
+      <>
+        <output>{Math.round(volume * 100)}%</output>
+        <button onClick={() => setVolume(0.2)}>Set to 20%</button>
+      </>
+    );
+  }
+
+  /** Two outputs whose selection is one shared value, as in MediaDevices. */
+  function mediaDevicesWithOutputs(): MediaDevices {
+    const selected$ = new BehaviorSubject<
+      SelectedAudioOutputDevice | undefined
+    >({ id: "out-1", virtualEarpiece: false });
+    return mockMediaDevices({
+      requestDeviceNames: vi.fn(),
+      audioOutput: {
+        available$: constant(
+          new Map<string, AudioOutputDeviceLabel>([
+            ["out-1", { type: "name", name: "Built-in Speakers" }],
+            ["out-2", { type: "name", name: "Headset" }],
+          ]),
+        ),
+        selected$,
+        select: (id: string): void =>
+          selected$.next({ id, virtualEarpiece: false }),
+      },
+    });
+  }
+});

src/components/CallFooter.tsx

@@ -7,6 +7,7 @@ Please see LICENSE in the repository root for full details.
 
 import { type FC, type JSX, type Ref, useMemo } from "react";
 import classNames from "classnames";
+import { useTranslation } from "react-i18next";
 
 import LogoMark from "../icons/LogoMark.svg?react";
 import LogoType from "../icons/LogoType.svg?react";
@@ -25,6 +26,7 @@ import styles from "./CallFooter.module.css";
 import {
   MediaMuteAndSwitchButton,
   type MenuOptions,
+  type OutputMenuOptions,
 } from "./MediaMuteAndSwitchButton";
 import { type Behavior } from "../state/Behavior";
 import { type ViewModel } from "../state/ViewModel";
@@ -105,6 +107,18 @@ export interface FooterState {
   selectedVideo: string | undefined;
   selectAudioButtonOption: ((deviceId: string) => void) | undefined;
   selectVideoButtonOption: ((option: string) => void) | undefined;
+
+  /**
+   * The audio outputs offered by the audio menu. Empty where the browser does
+   * not allow choosing one; the menu then names the default output.
+   */
+  audioOutputOptions: OutputMenuOptions[];
+  selectedAudioOutput: string | undefined;
+  /** Also controls whether the microphone chevron opens the audio menu */
+  selectAudioOutputOption: ((deviceId: string) => void) | undefined;
+  soundEffectVolume: number;
+  /** Also controls whether the microphone chevron opens the audio menu */
+  setSoundEffectVolume: ((volume: number) => void) | undefined;
 }
 
 export interface FooterProps {
@@ -119,6 +133,7 @@ export const CallFooter: FC<FooterProps> = ({
   children,
   vm,
 }) => {
+  const { t } = useTranslation();
   const asOverlay = useBehavior(vm.asOverlay$);
   const showFooter = useBehavior(vm.showFooter$);
   const hideControls = useBehavior(vm.hideControls$);
@@ -144,6 +159,11 @@ export const CallFooter: FC<FooterProps> = ({
   const selectedAudio = useBehavior(vm.selectedAudio$);
   const selectAudioButtonOption = useBehavior(vm.selectAudioButtonOption$);
   const selectVideoButtonOption = useBehavior(vm.selectVideoButtonOption$);
+  const audioOutputOptions = useBehavior(vm.audioOutputOptions$);
+  const selectedAudioOutput = useBehavior(vm.selectedAudioOutput$);
+  const selectAudioOutputOption = useBehavior(vm.selectAudioOutputOption$);
+  const soundEffectVolume = useBehavior(vm.soundEffectVolume$);
+  const setSoundEffectVolume = useBehavior(vm.setSoundEffectVolume$);
   const toggleBlur = useBehavior(vm.toggleBlur$);
   const videoBlurEnabled = useBehavior(vm.videoBlurEnabled$);
   const buttonSize = useBehavior(vm.buttonSize$);
@@ -165,10 +185,24 @@ export const CallFooter: FC<FooterProps> = ({
     );
   }
 
-  if ((audioOptions?.length ?? 0) > 0) {
+  // The audio menu exists wherever its actions do. It names the output in use
+  // even when there is no microphone to list.
+  const audioControls =
+    selectAudioOutputOption === undefined || setSoundEffectVolume === undefined
+      ? undefined
+      : {
+          outputOptions: audioOutputOptions ?? [],
+          selectedOutput: selectedAudioOutput,
+          onSelectOutput: selectAudioOutputOption,
+          micDeviceId: selectedAudio,
+          soundEffectVolume: soundEffectVolume ?? 0,
+          onSoundEffectVolumeCommit: setSoundEffectVolume,
+        };
+
+  if ((audioOptions?.length ?? 0) > 0 || audioControls !== undefined) {
     buttons.push(
       <MediaMuteAndSwitchButton
-        title={"Mic Source"}
+        title={audioControls ? t("audio_menu.title") : "Mic Source"}
         key="audio"
         iconsAndLabels="audio"
         enabled={audioEnabled ?? false}
@@ -178,6 +212,7 @@ export const CallFooter: FC<FooterProps> = ({
         options={audioOptions}
         selectedOption={selectedAudio}
         onSelect={selectAudioButtonOption}
+        audioControls={audioControls}
       />,
     );
   } else {

src/components/CallFooterViewModel.test.ts

@@ -5,7 +5,7 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE in the repository root for full details.
 */
 
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { BehaviorSubject } from "rxjs";
 
 import { testScope, mockMuteStates, mockMediaDevices } from "../utils/test";
@@ -13,8 +13,18 @@ import { constant } from "../state/Behavior";
 import type { CallViewModel } from "../state/CallViewModel/CallViewModel";
 import type { Alignment, Layout } from "../state/layout-types";
 import type { SpotlightTileViewModel } from "../state/TileViewModel";
-import type { DeviceLabel } from "../state/MediaDevices";
-import { createCallFooterViewModel } from "./CallFooterViewModel";
+import type {
+  AudioOutputDeviceLabel,
+  DeviceLabel,
+} from "../state/MediaDevices";
+import {
+  createCallFooterViewModel,
+  createLobbyFooterViewModel,
+} from "./CallFooterViewModel";
+import { HeaderStyle } from "../UrlParams";
+import { type FooterSnapshot } from "./CallFooter";
+import { type ViewModel } from "../state/ViewModel";
+import { soundEffectVolume } from "../settings/settings";
 
 const platformMock = vi.hoisted(() => vi.fn(() => "desktop"));
 vi.mock("../Platform", () => ({
@@ -94,7 +104,92 @@ const twoMicsAndOneCamMediaDevices = mockMediaDevices({
   },
 });
 
+const selectOutput = vi.fn();
+const twoOutputsMediaDevices = mockMediaDevices({
+  audioOutput: {
+    available$: constant(
+      new Map<string, AudioOutputDeviceLabel>([
+        ["", { type: "default", name: "Built-in Speakers" }],
+        ["out2", { type: "name", name: "Headset" }],
+      ]),
+    ),
+    selected$: constant({ id: "out2", virtualEarpiece: false }),
+    select: selectOutput,
+  },
+});
+
 describe("createCallFooterViewModel", () => {
+  describe("audio menu", () => {
+    afterEach(() => soundEffectVolume.setValue(0.5));
+
+    function createVm(
+      platform: string,
+      layout: Layout,
+    ): ViewModel<FooterSnapshot> {
+      platformMock.mockReturnValue(platform);
+      return createCallFooterViewModel(
+        testScope(),
+        buildMinimalCallViewModel(layout),
+        mockMuteStates(),
+        twoOutputsMediaDevices,
+        /* reactionIdentifier */ undefined,
+        { showControls: true, header: HeaderStyle.Standard },
+      );
+    }
+
+    it("offers no audio menu when the platform is iOS", () => {
+      const vm = createVm("ios", gridLayout);
+      expect(vm.audioOutputOptions$.value).toEqual([]);
+      expect(vm.selectAudioOutputOption$.value).toBeUndefined();
+      expect(vm.setSoundEffectVolume$.value).toBeUndefined();
+    });
+
+    it("offers no audio menu when the layout is pip", () => {
+      const vm = createVm("desktop", pipLayout);
+      expect(vm.audioOutputOptions$.value).toEqual([]);
+      expect(vm.selectAudioOutputOption$.value).toBeUndefined();
+      expect(vm.setSoundEffectVolume$.value).toBeUndefined();
+    });
+
+    it("audio menu is present pre-join on every platform", () => {
+      for (const platform of ["desktop", "android", "ios"]) {
+        platformMock.mockReturnValue(platform);
+        const vm = createLobbyFooterViewModel(
+          testScope(),
+          mockMuteStates(),
+          twoOutputsMediaDevices,
+          undefined,
+          undefined,
+          false,
+        );
+        expect(vm.audioOutputOptions$.value).toHaveLength(2);
+        expect(vm.selectAudioOutputOption$.value).toBeDefined();
+        expect(vm.setSoundEffectVolume$.value).toBeDefined();
+      }
+    });
+
+    it("reads and writes the sound-effect volume setting on desktop", () => {
+      const vm = createVm("desktop", gridLayout);
+      expect(vm.soundEffectVolume$.value).toBe(0.5);
+
+      vm.setSoundEffectVolume$.value?.(0.2);
+      expect(soundEffectVolume.value$.value).toBe(0.2);
+      expect(vm.soundEffectVolume$.value).toBe(0.2);
+    });
+
+    it("lists the outputs and the selection on desktop", () => {
+      const vm = createVm("desktop", gridLayout);
+      expect(vm.audioOutputOptions$.value).toEqual([
+        { id: "", label: { type: "default", name: "Built-in Speakers" } },
+        { id: "out2", label: { type: "name", name: "Headset" } },
+      ]);
+      expect(vm.selectedAudioOutput$.value).toBe("out2");
+
+      vm.selectAudioOutputOption$.value?.("");
+      expect(selectOutput).toHaveBeenCalledWith("");
+    });
+  });
+
   describe("audioOptions and videoOptions", () => {
     function checkEmptyFor(platform: string, layout: Layout): void {
       platformMock.mockReturnValue(platform);
@@ -105,6 +200,7 @@ describe("createCallFooterViewModel", () => {
         mockMuteStates(),
         twoMicsAndOneCamMediaDevices,
         /* reactionIdentifier */ undefined,
+        { showControls: true, header: HeaderStyle.Standard },
       );
 
       expect(vm.audioOptions$.value).toEqual([]);
@@ -126,6 +222,7 @@ describe("createCallFooterViewModel", () => {
         mockMuteStates(),
         twoMicsAndOneCamMediaDevices,
         /* reactionIdentifier */ undefined,
+        { showControls: true, header: HeaderStyle.Standard },
       );
 
       expect(vm.audioOptions$?.value).toEqual([

src/components/CallFooterViewModel.tsx

@@ -9,17 +9,21 @@ import { combineLatest, map, switchMap } from "rxjs";
 import { supportsBackgroundProcessors } from "@livekit/track-processors";
 
 import { type CallViewModel } from "../state/CallViewModel/CallViewModel";
-import { type MenuOptions } from "./MediaMuteAndSwitchButton";
+import {
+  type MenuOptions,
+  type OutputMenuOptions,
+} from "./MediaMuteAndSwitchButton";
 import { type MediaDevices } from "../state/MediaDevices";
 import {
   backgroundBlur as backgroundBlurSettings,
   debugTileLayout as debugTileLayoutSetting,
+  soundEffectVolume as soundEffectVolumeSetting,
 } from "../settings/settings";
 import { type Behavior, constant } from "../state/Behavior";
 import type { ObservableScope } from "../state/ObservableScope";
 import { type MuteStates } from "../state/MuteStates";
 import { createStaticViewModel, type ViewModel } from "../state/ViewModel";
-import { getUrlParams, HeaderStyle } from "../UrlParams";
+import { HeaderStyle } from "../UrlParams";
 import { platform } from "../Platform";
 import { type FooterSnapshot } from "./CallFooter";
 
@@ -54,8 +58,10 @@ function buildMuteBehaviors(
 }
 
 /**
- * Shared helper: maps MediaDevices into the audio/video device-list behaviors
- * needed by FooterSnapshot (options, selection, callbacks, blur toggle).
+ * Shared helper: maps MediaDevices and the sound-effect setting into every
+ * device behavior FooterSnapshot needs, for the switcher menus and the audio
+ * menu alike. The output list is empty wherever the browser cannot switch
+ * output; the menu then names the default rather than hiding the group.
  */
 function buildDeviceBehaviors(
   scope: ObservableScope,
@@ -72,6 +78,11 @@ function buildDeviceBehaviors(
   | "selectVideoButtonOption$"
   | "toggleBlur$"
   | "videoBlurEnabled$"
+  | "audioOutputOptions$"
+  | "selectedAudioOutput$"
+  | "selectAudioOutputOption$"
+  | "soundEffectVolume$"
+  | "setSoundEffectVolume$"
 > {
   return {
     audioOptions$: scope.behavior(
@@ -126,6 +137,45 @@ function buildDeviceBehaviors(
       ),
     ),
     videoBlurEnabled$: backgroundBlurSettings.value$,
+    audioOutputOptions$: scope.behavior(
+      disableSwitcher$.pipe(
+        switchMap((disable) =>
+          disable
+            ? constant([] as OutputMenuOptions[])
+            : mediaDevices.audioOutput.available$.pipe(
+                map((available) =>
+                  [...available.entries()].map(([id, label]) => ({
+                    id,
+                    label,
+                  })),
+                ),
+              ),
+        ),
+      ),
+    ),
+    selectedAudioOutput$: scope.behavior(
+      mediaDevices.audioOutput.selected$.pipe(map((s) => s?.id)),
+    ),
+    selectAudioOutputOption$: scope.behavior(
+      disableSwitcher$.pipe(
+        map((disable) =>
+          disable
+            ? undefined
+            : (id: string): void => mediaDevices.audioOutput.select(id),
+        ),
+      ),
+    ),
+    soundEffectVolume$: soundEffectVolumeSetting.value$,
+    setSoundEffectVolume$: scope.behavior(
+      disableSwitcher$.pipe(
+        map((disable) =>
+          disable
+            ? undefined
+            : (volume: number): void =>
+                soundEffectVolumeSetting.setValue(volume),
+        ),
+      ),
+    ),
   };
 }
 
@@ -138,6 +188,8 @@ function buildDeviceBehaviors(
  * @param mediaDevices - Available and selected input devices.
  * @param reactionIdentifier - The local user's reaction identifier string, or
  *   undefined when reactions are not supported (hides the reaction button).
+ * @param options - `showControls`: whether the call controls should be shown.
+ *   `header`: the style of header, which decides whether to show the logo.
  */
 export function createCallFooterViewModel(
   scope: ObservableScope,
@@ -145,8 +197,9 @@ export function createCallFooterViewModel(
   muteStates: MuteStates,
   mediaDevices: MediaDevices,
   reactionIdentifier: string | undefined,
+  options: { showControls: boolean; header: HeaderStyle },
 ): ViewModel<FooterSnapshot> {
-  const { showControls, header: headerStyle } = getUrlParams();
+  const { showControls, header: headerStyle } = options;
   const showLogo = headerStyle === HeaderStyle.Standard;
 
   const isPip$ = scope.behavior(
@@ -267,6 +320,8 @@ export function createLobbyFooterViewModel(
       selectVideoButtonOption: undefined,
     }),
     ...buildMuteBehaviors(scope, muteStates),
+    // Nothing is gated before joining: the chevron already exists on every
+    // platform there, and a device check matters most before a call starts.
     ...buildDeviceBehaviors(scope, mediaDevices, constant(false)),
   };
 }

src/components/MediaMuteAndSwitchButton.module.css

@@ -35,3 +35,92 @@ Please see LICENSE in the repository root for full details.
     transform: rotate(360deg);
   }
 }
+
+/* The speaker group's one row where there is no choice to make: it names the
+   output in use wherever audio cannot be redirected. Laid out like a menu item
+   so it lines up with the rows around it. */
+.readOnlyRow {
+  display: flex;
+  align-items: center;
+  gap: var(--cpd-space-4x);
+  padding: var(--cpd-space-3x) var(--cpd-space-4x);
+  color: var(--cpd-color-text-primary);
+  font: var(--cpd-font-body-md-regular);
+}
+
+.micSection {
+  display: flex;
+  flex-direction: column;
+  gap: var(--cpd-space-1x);
+}
+
+.stickyMeter {
+  position: sticky;
+  inset-block-end: 0;
+  /* Opaque, so the device rows scrolling underneath do not show through. */
+  background: var(--cpd-color-bg-canvas-default);
+  padding-block-start: var(--cpd-space-1x);
+  /* The menu draws its border as an outline inset by one border width. This
+     row is positioned and opaque, so without the matching inset it paints over
+     that border at the left and right edges. */
+  margin-inline: var(--cpd-border-width-1);
+}
+
+/* Bound the whole menu to the space Radix reports for it, so that the scroll
+   area below can shrink while the heading and the slider, its flex siblings,
+   keep their size and stay on screen. The bound has to cover the menu's own
+   padding, or the padding lands outside it and carries the heading off the
+   top of the viewport; the 2x keeps a small gap to the viewport edge. */
+.menu {
+  box-sizing: border-box;
+  max-block-size: calc(
+    var(--radix-dropdown-menu-content-available-height) - var(--cpd-space-2x)
+  );
+}
+
+.scrollArea {
+  flex: 1 1 auto;
+  min-block-size: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  scrollbar-gutter: stable;
+  /* The menu lays its children out as a flex column; the scroll area has to
+     repeat that for the children it now owns. */
+  display: flex;
+  flex-direction: column;
+  gap: var(--cpd-space-1x);
+}
+
+.volumeRow {
+  display: flex;
+  flex-direction: column;
+  gap: var(--cpd-space-2x);
+  padding: var(--cpd-space-3x) var(--cpd-space-4x);
+}
+
+.volumeLabel {
+  font: var(--cpd-font-body-md-medium);
+  color: var(--cpd-color-text-primary);
+}
+
+.volumeControl {
+  display: flex;
+  align-items: center;
+  gap: var(--cpd-space-3x);
+}
+
+.volumeSlider {
+  flex: 1;
+}
+
+/* The menu moves focus onto whichever item the pointer is over, so the
+   browser's own focus ring shows up during mouse use. Keyboard navigation
+   gets the border; the pointer gets the hover background and nothing else. */
+.menu [role^="menuitem"]:focus {
+  outline: none;
+}
+
+.keyboardNav [role^="menuitem"]:focus {
+  outline: var(--cpd-border-width-2) solid var(--cpd-color-border-focused);
+  outline-offset: calc(-1 * var(--cpd-border-width-2));
+}

src/components/MediaMuteAndSwitchButton.stories.tsx

@@ -14,7 +14,9 @@ import { MediaDevicesContext } from "../MediaDevicesContext";
 import { MediaDevices } from "../state/MediaDevices";
 import { globalScope } from "../state/ObservableScope";
 
-const mediaDevices = new MediaDevices(globalScope);
+const mediaDevices = new MediaDevices(globalScope, {
+  controlledAudioDevices: false,
+});
 
 const meta = {
   component: MediaMuteAndSwitchButton,

src/components/MediaMuteAndSwitchButton.test.tsx

@@ -5,13 +5,22 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE in the repository root for full details.
 */
 
-import { describe, expect, test, vi } from "vitest";
-import { act, render, screen, type RenderResult } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import {
+  act,
+  render,
+  screen,
+  waitFor,
+  type RenderResult,
+} from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { type JSX, useState, type ReactNode } from "react";
 import { TooltipProvider } from "@vector-im/compound-web";
 
-import { MediaMuteAndSwitchButton } from "./MediaMuteAndSwitchButton";
+import {
+  MediaMuteAndSwitchButton,
+  type AudioControls,
+} from "./MediaMuteAndSwitchButton";
 import { MediaDevicesContext } from "../MediaDevicesContext";
 import { type MediaDevices } from "../state/MediaDevices";
 
@@ -358,3 +367,426 @@ describe("MediaMuteAndSwitchButton", () => {
     expect(mic2Item.querySelectorAll("svg").length).toBe(1);
   });
 });
+
+describe("audio menu", () => {
+  test("level indicator is on screen as soon as the menu opens", async () => {
+    // A microphone takes a moment to open. The meter waits at rest rather
+    // than appearing late and pushing the rest of the menu down.
+    getUserMedia.mockReturnValue(new Promise<MediaStream>(() => {}));
+    await openAudioMenu();
+
+    const meter = screen.getByRole("meter");
+    expect(meter).toHaveAttribute("aria-valuenow", "0");
+    expect(screen.queryByTestId("mic_absent")).toBe(null);
+  });
+
+  test("level indicator responds while muted", async () => {
+    await openAudioMenu({ enabled: false });
+
+    // Muting must not stop the meter: checking the microphone before unmuting
+    // is the whole point of it.
+    await waitFor(() =>
+      expect(getUserMedia).toHaveBeenCalledWith({
+        audio: { deviceId: { exact: "mic-1" } },
+      }),
+    );
+    expect(screen.getByRole("meter")).toBeInTheDocument();
+  });
+
+  test("audio menu starts capture on open and stops on close", async () => {
+    const user = userEvent.setup();
+    renderAudioMenu();
+    expect(getUserMedia).not.toHaveBeenCalled();
+
+    await user.click(screen.getByRole("button", { name: "Microphone" }));
+    await waitFor(() => expect(getUserMedia).toHaveBeenCalledTimes(1));
+
+    await user.keyboard("[Escape]");
+    await waitFor(() => expect(stop).toHaveBeenCalled());
+  });
+
+  test("level indicator follows a microphone change", async () => {
+    const user = userEvent.setup();
+    function Wrapper(): JSX.Element {
+      const [mic, setMic] = useState("mic-1");
+      return (
+        <MediaMuteAndSwitchButton
+          title="Audio controls"
+          iconsAndLabels="audio"
+          enabled
+          onMuteClick={vi.fn()}
+          options={micOptions}
+          selectedOption={mic}
+          onSelect={setMic}
+          audioControls={audioControls({ micDeviceId: mic })}
+        />
+      );
+    }
+    renderComponent(<Wrapper />);
+    await user.click(screen.getByRole("button", { name: "Microphone" }));
+    await waitFor(() =>
+      expect(getUserMedia).toHaveBeenLastCalledWith({
+        audio: { deviceId: { exact: "mic-1" } },
+      }),
+    );
+
+    await user.click(
+      screen.getByRole("menuitemradio", { name: "Headset Microphone" }),
+    );
+
+    await waitFor(() =>
+      expect(getUserMedia).toHaveBeenLastCalledWith({
+        audio: { deviceId: { exact: "mic-2" } },
+      }),
+    );
+    expect(stop).toHaveBeenCalled();
+    expect(screen.getByRole("menu")).toBeInTheDocument();
+    expect(screen.getByRole("meter")).toBeInTheDocument();
+  });
+
+  test("audio menu hints when microphone permission is denied", async () => {
+    getUserMedia.mockRejectedValue(
+      Object.assign(new Error("no"), { name: "NotAllowedError" }),
+    );
+    await openAudioMenu();
+
+    expect(await screen.findByTestId("mic_level_denied")).toHaveTextContent(
+      /microphone access is blocked/i,
+    );
+    expect(screen.queryByRole("meter")).toBe(null);
+  });
+
+  test("level indicator stays with the microphone list rather than the speakers", async () => {
+    await openAudioMenu();
+
+    // The meter reads the microphone, so it belongs to that group and never
+    // sits among the output controls.
+    const micSection = screen.getByTestId("audio_menu_mic_section");
+    expect(micSection).toContainElement(
+      screen.getByRole("menuitemradio", { name: "Headset Microphone" }),
+    );
+    expect(micSection).toContainElement(screen.getByTestId("mic_level_meter"));
+    expect(micSection).not.toContainElement(
+      screen.getByRole("menuitemradio", { name: "Headset" }),
+    );
+  });
+
+  test("audio menu switches microphone and stays open", async () => {
+    const onSelect = vi.fn();
+    const user = await openAudioMenu({ onSelect });
+
+    await user.click(
+      screen.getByRole("menuitemradio", { name: "Headset Microphone" }),
+    );
+
+    expect(onSelect).toHaveBeenCalledWith("mic-2");
+    // Selecting a device must not dismiss the menu: the user needs to see the
+    // choice take effect and may want to change it again.
+    expect(screen.getByRole("menu")).toBeInTheDocument();
+  });
+
+  test("audio menu switches audio output and stays open", async () => {
+    const controls = audioControls();
+    const user = await openAudioMenu({ audioControls: controls });
+
+    await user.click(screen.getByRole("menuitemradio", { name: "Headset" }));
+
+    expect(controls.onSelectOutput).toHaveBeenCalledWith("out-2");
+    expect(screen.getByRole("menu")).toBeInTheDocument();
+  });
+
+  test("audio menu says when there is no microphone", async () => {
+    await openAudioMenu({
+      micOptions: [],
+      audioControls: audioControls({ micDeviceId: undefined }),
+    });
+
+    // A meter resting at zero would read as a microphone that hears nothing,
+    // so the group names the absence instead.
+    expect(screen.getByTestId("mic_absent")).toHaveTextContent(
+      /no microphone found/i,
+    );
+    expect(screen.queryByRole("meter")).toBe(null);
+    // The rest of the menu is unaffected.
+    expect(
+      screen.getByRole("menuitemradio", { name: "Built-in Speakers" }),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("sound_effect_volume")).toBeInTheDocument();
+  });
+
+  test("audio menu marks the active output", async () => {
+    await openAudioMenu();
+
+    expect(
+      screen.getByRole("menuitemradio", { name: "Built-in Speakers" }),
+    ).toHaveAttribute("aria-checked", "true");
+    expect(
+      screen.getByRole("menuitemradio", { name: "Headset" }),
+    ).toHaveAttribute("aria-checked", "false");
+  });
+
+  test("audio menu separates microphone speaker and sound effects groups", async () => {
+    await openAudioMenu();
+
+    // One rule after the microphone group, one after the speaker group.
+    expect(screen.getByRole("menu").querySelectorAll("hr")).toHaveLength(2);
+    expect(screen.getByTestId("mic_level_meter")).toBeInTheDocument();
+    expect(screen.getByTestId("sound_effect_volume")).toBeInTheDocument();
+  });
+
+  test("audio menu keeps its title and volume slider out of the scrolling area", async () => {
+    await openAudioMenu();
+
+    // Machines with many inputs and outputs produce a device list taller than
+    // the menu can be. Only that list scrolls; the heading above it and the
+    // sound-effect slider below it stay put.
+    const scroll = screen.getByTestId("audio_menu_scroll");
+    expect(scroll).toContainElement(
+      screen.getByRole("menuitemradio", { name: "Headset Microphone" }),
+    );
+    expect(scroll).toContainElement(
+      screen.getByRole("menuitemradio", { name: "Headset" }),
+    );
+    expect(scroll).not.toContainElement(
+      screen.getByTestId("sound_effect_volume"),
+    );
+    expect(scroll).not.toContainElement(
+      screen.getByRole("heading", { name: "Audio controls" }),
+    );
+  });
+
+  test("the focus border marks keyboard use and never the pointer", async () => {
+    const user = await openAudioMenu();
+    const menu = screen.getByRole("menu");
+    const rows = screen.getAllByRole("menuitemradio");
+
+    // Opened and driven by pointer: the hover background alone.
+    await user.hover(rows[1]);
+    expect(menu.className).not.toMatch(/keyboardNav/);
+
+    // One arrow key, and the border marks where the keyboard is.
+    await user.keyboard("[ArrowDown]");
+    expect(menu.className).toMatch(/keyboardNav/);
+
+    // Back to the pointer, and the border goes with it: the browser calls
+    // every focus after a key press keyboard-driven, so this cannot be left
+    // to :focus-visible.
+    await user.hover(rows[0]);
+    expect(menu.className).not.toMatch(/keyboardNav/);
+  });
+
+  test("audio menu is fully operable from the keyboard", async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    const controls = audioControls();
+    renderAudioMenu({ onSelect, audioControls: controls });
+
+    // Open from the chevron; the first device row takes focus.
+    await user.tab();
+    await user.tab();
+    expect(screen.getByRole("button", { name: "Microphone" })).toHaveFocus();
+    await user.keyboard("[Enter]");
+    await screen.findByRole("menu");
+    expect(
+      screen.getByRole("menuitemradio", { name: "Built-in Microphone" }),
+    ).toHaveFocus();
+
+    // Arrow keys walk the microphone rows; Enter selects and keeps the menu.
+    await user.keyboard("[ArrowDown]");
+    const headsetMic = screen.getByRole("menuitemradio", {
+      name: /Headset Microphone/,
+    });
+    expect(headsetMic).toHaveFocus();
+    await user.keyboard("[Enter]");
+    expect(onSelect).toHaveBeenCalledWith("mic-2");
+    expect(screen.getByRole("menu")).toBeInTheDocument();
+
+    // Tab reaches the meter below the microphones, then the slider; arrow
+    // keys adjust the slider without moving the menu's focus.
+    await user.tab();
+    expect(screen.getByRole("meter")).toHaveFocus();
+    await user.tab();
+    const slider = screen.getByRole("slider", { name: /Sound effect volume/ });
+    expect(slider).toHaveFocus();
+    await user.keyboard("[ArrowRight]");
+    expect(controls.onSoundEffectVolumeCommit).toHaveBeenCalledWith(0.51);
+    expect(slider).toHaveFocus();
+
+    // Shift+Tab walks back to the meter and the current row; from there the
+    // arrow keys carry on into the speaker rows.
+    await user.tab({ shift: true });
+    expect(screen.getByRole("meter")).toHaveFocus();
+    await user.tab({ shift: true });
+    expect(headsetMic).toHaveFocus();
+    await user.keyboard("[ArrowDown][ArrowDown]");
+    expect(
+      screen.getByRole("menuitemradio", { name: "Headset" }),
+    ).toHaveFocus();
+    await user.keyboard("[Enter]");
+    expect(controls.onSelectOutput).toHaveBeenCalledWith("out-2");
+    expect(screen.getByRole("menu")).toBeInTheDocument();
+  });
+
+  test("audio menu does not reselect the active output", async () => {
+    const controls = audioControls();
+    const user = await openAudioMenu({ audioControls: controls });
+
+    await user.click(
+      screen.getByRole("menuitemradio", { name: "Built-in Speakers" }),
+    );
+
+    expect(controls.onSelectOutput).not.toHaveBeenCalled();
+  });
+
+  test("audio menu shows single audio output as non-selectable", async () => {
+    await openAudioMenu({
+      audioControls: audioControls({
+        outputOptions: [
+          { label: { type: "name", name: "Built-in Speakers" }, id: "out-1" },
+        ],
+      }),
+    });
+
+    expect(screen.getByTestId("speaker_readonly")).toHaveTextContent(
+      "Built-in Speakers",
+    );
+    // The one output must not present itself as a choice.
+    expect(
+      screen.queryByRole("menuitemradio", { name: "Built-in Speakers" }),
+    ).toBe(null);
+  });
+
+  test("audio menu names the default output where none can be chosen", async () => {
+    await openAudioMenu({
+      audioControls: audioControls({ outputOptions: [] }),
+    });
+    expect(screen.getByTestId("speaker_readonly")).toHaveTextContent("Default");
+  });
+
+  test("audio menu labels every kind of output", async () => {
+    await openAudioMenu({
+      audioControls: audioControls({
+        outputOptions: [
+          { label: { type: "default", name: "Built-in Speakers" }, id: "" },
+          { label: { type: "default", name: null }, id: "default" },
+          { label: { type: "number", number: 2 }, id: "out-2" },
+          { label: { type: "speaker" }, id: "speaker" },
+          { label: { type: "earpiece" }, id: "earpiece" },
+        ],
+        selectedOutput: "",
+      }),
+    });
+
+    for (const name of [
+      "Default (Built-in Speakers)",
+      "Default",
+      "Speaker 2",
+      "Loudspeaker",
+      "Handset",
+    ])
+      expect(screen.getByRole("menuitemradio", { name })).toBeInTheDocument();
+  });
+
+  const stop = vi.fn();
+  const getUserMedia = vi.fn();
+
+  beforeEach(() => {
+    stop.mockClear();
+    getUserMedia.mockReset().mockResolvedValue({
+      getTracks: () => [{ stop }],
+    } as unknown as MediaStream);
+    // Define only mediaDevices: replacing the whole navigator drops the
+    // prototype getters that user-event relies on.
+    Object.defineProperty(navigator, "mediaDevices", {
+      value: { getUserMedia },
+      configurable: true,
+    });
+    // jsdom has no AudioContext; the meter only needs a silent analyser.
+    vi.stubGlobal(
+      "AudioContext",
+      class {
+        public createAnalyser(): unknown {
+          return {
+            fftSize: 1024,
+            getFloatTimeDomainData: (out: Float32Array): void => {
+              out.fill(0);
+            },
+          };
+        }
+        public createMediaStreamSource(): { connect: () => void } {
+          return { connect: (): void => {} };
+        }
+        public async resume(): Promise<void> {}
+        public async close(): Promise<void> {}
+      },
+    );
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    Reflect.deleteProperty(navigator, "mediaDevices");
+  });
+
+  const micOptions = [
+    {
+      label: { type: "name" as const, name: "Built-in Microphone" },
+      id: "mic-1",
+    },
+    {
+      label: { type: "name" as const, name: "Headset Microphone" },
+      id: "mic-2",
+    },
+  ];
+
+  function audioControls(over: Partial<AudioControls> = {}): AudioControls {
+    return {
+      outputOptions: [
+        {
+          label: { type: "name" as const, name: "Built-in Speakers" },
+          id: "out-1",
+        },
+        { label: { type: "name" as const, name: "Headset" }, id: "out-2" },
+      ],
+      selectedOutput: "out-1",
+      onSelectOutput: vi.fn(),
+      micDeviceId: "mic-1",
+      soundEffectVolume: 0.5,
+      onSoundEffectVolumeCommit: vi.fn(),
+      ...over,
+    };
+  }
+
+  interface AudioMenuProps {
+    enabled?: boolean;
+    audioControls?: AudioControls;
+    onSelect?: (id: string) => void;
+    micOptions?: typeof micOptions;
+  }
+
+  /** Renders the microphone button with the audio menu, closed. */
+  function renderAudioMenu(props: AudioMenuProps = {}): void {
+    renderComponent(
+      <MediaMuteAndSwitchButton
+        title="Audio controls"
+        iconsAndLabels="audio"
+        enabled={props.enabled ?? true}
+        onMuteClick={vi.fn()}
+        options={props.micOptions ?? micOptions}
+        selectedOption="mic-1"
+        onSelect={props.onSelect ?? vi.fn()}
+        audioControls={props.audioControls ?? audioControls()}
+      />,
+    );
+  }
+
+  /** Renders the microphone button with the audio menu and opens the menu. */
+  async function openAudioMenu(
+    props: AudioMenuProps = {},
+  ): Promise<ReturnType<typeof userEvent.setup>> {
+    const user = userEvent.setup();
+    renderAudioMenu(props);
+    await user.click(screen.getByRole("button", { name: "Microphone" }));
+    await screen.findByRole("menu");
+    return user;
+  }
+});

src/components/MediaMuteAndSwitchButton.tsx

@@ -5,7 +5,14 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE in the repository root for full details.
 */
 
-import { type ComponentType, useState, type FC, useEffect } from "react";
+import {
+  type ComponentType,
+  useState,
+  type FC,
+  useEffect,
+  type JSX,
+  type KeyboardEvent,
+} from "react";
 import {
   Button,
   Menu,
@@ -19,20 +26,50 @@ import {
   MicOnIcon,
   SpinnerIcon,
   VideoCallIcon,
+  VolumeOnIcon,
 } from "@vector-im/compound-design-tokens/assets/web/icons";
 import classNames from "classnames";
 import { useTranslation } from "react-i18next";
 
 import styles from "./MediaMuteAndSwitchButton.module.css";
 import { MicButton, VideoButton } from "../button";
-import { type DeviceLabel } from "../state/MediaDevices";
+import {
+  type AudioOutputDeviceLabel,
+  type DeviceLabel,
+} from "../state/MediaDevices";
 import { useMediaDevices } from "../MediaDevicesContext";
+import { MicrophoneLevel } from "./AudioLevelMeter";
+import { Slider } from "../Slider";
 
 export interface MenuOptions {
   label: DeviceLabel;
   id: string;
 }
 
+export interface OutputMenuOptions {
+  label: AudioOutputDeviceLabel;
+  id: string;
+}
+
+/**
+ * The controls that turn the microphone chevron menu into the audio menu: a
+ * speaker group and the sound-effect volume below the microphone list. Absent
+ * for the camera menu.
+ */
+export interface AudioControls {
+  /**
+   * The audio outputs to choose from. Empty where the browser does not allow
+   * choosing one; the menu then names the default output instead.
+   */
+  outputOptions: OutputMenuOptions[];
+  selectedOutput: string | undefined;
+  onSelectOutput: (id: string) => void;
+  /** The microphone the level meter follows. */
+  micDeviceId: string | undefined;
+  soundEffectVolume: number;
+  onSoundEffectVolumeCommit: (volume: number) => void;
+}
+
 export interface MediaMuteAndSwitchButtonProps {
   /** The title used in the Switcher modal. */
   title: string;
@@ -49,6 +86,8 @@ export interface MediaMuteAndSwitchButtonProps {
   selectedOption?: string;
   videoBlurToggleClick?: () => void;
   videoBlurEnabled?: boolean;
+  /** When present, the menu renders the speaker group below the microphone list. */
+  audioControls?: AudioControls;
   /**
    * For any toggle and option this method will be called.
    * So toggles need to be implemented by listening here and setting the right toggle item to `enabled`
@@ -57,6 +96,17 @@ export interface MediaMuteAndSwitchButtonProps {
 }
 
 const BLUR_ID = "blur";
+/** The keys a slider reads; inside the menu they must not move focus. */
+const SLIDER_KEYS = new Set([
+  "ArrowLeft",
+  "ArrowRight",
+  "ArrowUp",
+  "ArrowDown",
+  "Home",
+  "End",
+  "PageUp",
+  "PageDown",
+]);
 
 export const MediaMuteAndSwitchButton: FC<MediaMuteAndSwitchButtonProps> = ({
   title,
@@ -69,9 +119,17 @@ export const MediaMuteAndSwitchButton: FC<MediaMuteAndSwitchButtonProps> = ({
   videoBlurEnabled,
   videoBlurToggleClick,
   onSelect,
+  audioControls,
 }) => {
   const [plannedSelection, setPlannedSelection] = useState<string | null>(null);
   const [menuOpen, setMenuOpen] = useState(false);
+  // Which of the two reached the current item, since `:focus-visible` cannot
+  // tell: the menu focuses whatever the pointer is over.
+  const [keyboardNav, setKeyboardNav] = useState(false);
+  const modality = {
+    onKeyDown: (): void => setKeyboardNav(true),
+    onPointerMove: (): void => setKeyboardNav(false),
+  };
   const isBusy = busy ?? false;
   const { t } = useTranslation();
   const devices = useMediaDevices();
@@ -142,6 +200,60 @@ export const MediaMuteAndSwitchButton: FC<MediaMuteAndSwitchButtonProps> = ({
       break;
   }
 
+  const deviceItems = options?.map(({ label, id }) => {
+    let labelText: string;
+    switch (label.type) {
+      case "name":
+        labelText = label.name;
+        break;
+      case "number":
+        labelText = numberedLabel(label.number);
+        break;
+    }
+    return (
+      <MenuItem
+        hideChevron
+        label={labelText}
+        Icon={
+          IconOptions && (
+            <IconOptions
+              width={24}
+              height={24}
+              className={styles.itemIcon}
+              aria-hidden
+            />
+          )
+        }
+        onSelect={(e) => {
+          e.preventDefault();
+          if (id === selectedOption) return;
+          setPlannedSelection(id);
+          onSelect?.(id);
+        }}
+        key={id}
+        role="menuitemradio"
+        aria-checked={selectedOption === id}
+        {...modality}
+      >
+        {selectedOption === id && (
+          <CheckIcon
+            width={24}
+            height={24}
+            aria-hidden // A label would be redundant to aria-checked above
+          />
+        )}
+        {selectedOption !== id && plannedSelection === id && (
+          <SpinnerIcon
+            width={24}
+            height={24}
+            className={styles.rotate}
+            aria-label={t("settings.devices.activating")}
+          />
+        )}
+      </MenuItem>
+    );
+  });
+
   return (
     <div
       className={classNames({
@@ -152,6 +264,9 @@ export const MediaMuteAndSwitchButton: FC<MediaMuteAndSwitchButtonProps> = ({
       {/* The mute button lives inside */}
       {button}
       <Menu
+        className={classNames(styles.menu, {
+          [styles.keyboardNav]: keyboardNav,
+        })}
         title={title}
         showTitle={true}
         open={menuOpen}
@@ -168,64 +283,65 @@ export const MediaMuteAndSwitchButton: FC<MediaMuteAndSwitchButtonProps> = ({
             kind={"tertiary"}
             size="lg"
             aria-label={optionsButtonLabel}
+            onKeyDown={() => setKeyboardNav(true)}
+            onPointerDown={() => setKeyboardNav(false)}
           />
         }
       >
-        {options?.map(({ label, id }) => {
-          let labelText: string;
-          switch (label.type) {
-            case "name":
-              labelText = label.name;
-              break;
-            case "number":
-              labelText = numberedLabel(label.number);
-              break;
-          }
-          return (
-            <MenuItem
-              hideChevron
-              label={labelText}
-              Icon={
-                IconOptions && (
-                  <IconOptions
-                    width={24}
-                    height={24}
-                    className={styles.itemIcon}
-                    aria-hidden
-                  />
-                )
-              }
-              onSelect={(e) => {
-                e.preventDefault();
-                if (id === selectedOption) return;
-                setPlannedSelection(id);
-                onSelect?.(id);
-              }}
-              key={id}
-              role="menuitemradio"
-              aria-checked={selectedOption === id}
+        {audioControls ? (
+          // Only the device lists scroll; the title above and the slider below
+          // stay put. Tab moves between the device rows, the meter and the
+          // slider; see keepTabInsideMenu.
+          // eslint-disable-next-line jsx-a11y/no-static-element-interactions
+          <div
+            className={styles.scrollArea}
+            data-testid="audio_menu_scroll"
+            onKeyDown={keepTabInsideMenu}
+          >
+            <div
+              className={styles.micSection}
+              data-testid="audio_menu_mic_section"
             >
-              {selectedOption === id && (
-                <CheckIcon
-                  width={24}
-                  height={24}
-                  aria-hidden // A label would be redundant to aria-checked above
+              {deviceItems}
+              {/* The meter reads the microphone, so it travels with the
+                  microphone list rather than sitting among the output
+                  controls; pinned to the foot of the scroll port, it stays on
+                  screen for as long as any microphone is. */}
+              <div className={styles.stickyMeter} {...modality}>
+                {/* The capture is bound to the menu being open, so the
+                    microphone is only ever held while the user is looking at
+                    the level. */}
+                <MicrophoneLevel
+                  deviceId={audioControls.micDeviceId}
+                  active={menuOpen}
                 />
-              )}
-              {selectedOption !== id && plannedSelection === id && (
-                <SpinnerIcon
-                  width={24}
-                  height={24}
-                  className={styles.rotate}
-                  aria-label={t("settings.devices.activating")}
-                />
-              )}
-            </MenuItem>
-          );
-        })}
+              </div>
+            </div>
+            <hr />
+            <SpeakerSection
+              options={audioControls.outputOptions}
+              selected={audioControls.selectedOutput}
+              onSelect={audioControls.onSelectOutput}
+              modality={modality}
+            />
+          </div>
+        ) : (
+          deviceItems
+        )}
+        {audioControls && (
+          <>
+            <hr />
+            <SoundEffectVolume
+              volume={audioControls.soundEffectVolume}
+              onCommit={audioControls.onSoundEffectVolumeCommit}
+              onPointerMove={modality.onPointerMove}
+            />
+          </>
+        )}
         {(toggles?.length ?? 0) > 0 && <hr />}
         {toggles?.map((toggle) => (
           <ToggleMenuItem
+            {...modality}
             label={toggle.label}
             onSelect={(e) => {
               videoBlurToggleClick?.();
@@ -239,3 +355,164 @@ export const MediaMuteAndSwitchButton: FC<MediaMuteAndSwitchButtonProps> = ({
     </div>
   );
 };
+
+interface SpeakerSectionProps {
+  options: OutputMenuOptions[];
+  selected: string | undefined;
+  onSelect: (id: string) => void;
+  /** Reports whether a row was reached by pointer or by keyboard. */
+  modality: {
+    onKeyDown: () => void;
+    onPointerMove: () => void;
+  };
+}
+
+/**
+ * The speaker group of the audio menu.
+ *
+ * With more than one output to choose from this is a radio group. With one or
+ * none it still names the output in use, as a plain row: knowing where audio
+ * goes is useful even where it cannot be redirected, as in browsers that do
+ * not support choosing an output at all.
+ */
+function SpeakerSection({
+  options,
+  selected,
+  onSelect,
+  modality,
+}: SpeakerSectionProps): JSX.Element {
+  const { t } = useTranslation();
+  const labelText = (label: AudioOutputDeviceLabel): string => {
+    switch (label.type) {
+      case "name":
+        return label.name;
+      case "number":
+        return t("settings.devices.speaker_numbered", { n: label.number });
+      case "speaker":
+        return t("settings.devices.loudspeaker");
+      case "earpiece":
+        return t("settings.devices.handset");
+      case "default":
+        return label.name === null
+          ? t("settings.devices.default")
+          : t("settings.devices.default_named_plain", { name: label.name });
+    }
+  };
+  const icon = (
+    <VolumeOnIcon
+      width={24}
+      height={24}
+      className={styles.itemIcon}
+      aria-hidden
+    />
+  );
+
+  if (options.length <= 1) {
+    const only = options[0];
+    return (
+      <div className={styles.readOnlyRow} data-testid="speaker_readonly">
+        {icon}
+        <span>
+          {only ? labelText(only.label) : t("settings.devices.default")}
+        </span>
+      </div>
+    );
+  }
+
+  return (
+    <>
+      {options.map(({ id, label }) => (
+        <MenuItem
+          hideChevron
+          key={id}
+          label={labelText(label)}
+          Icon={icon}
+          onSelect={(e) => {
+            e.preventDefault();
+            if (id !== selected) onSelect(id);
+          }}
+          role="menuitemradio"
+          aria-checked={selected === id}
+          {...modality}
+        >
+          {selected === id && <CheckIcon width={24} height={24} aria-hidden />}
+        </MenuItem>
+      ))}
+    </>
+  );
+}
+
+interface SoundEffectVolumeProps {
+  volume: number;
+  onCommit: (volume: number) => void;
+  onPointerMove: () => void;
+}
+
+/** The sound-effect volume slider: the same stored value as in settings. */
+function SoundEffectVolume({
+  volume,
+  onCommit,
+  onPointerMove,
+}: SoundEffectVolumeProps): JSX.Element {
+  const { t } = useTranslation();
+  const label = t("settings.audio_tab.effect_volume_label");
+  // Tracked locally so dragging is smooth; only the committed value is
+  // stored. A change made in settings while the menu is open resets it.
+  const [raw, setRaw] = useState(volume);
+  const [committed, setCommitted] = useState(volume);
+  if (volume !== committed) {
+    setCommitted(volume);
+    setRaw(volume);
+  }
+
+  return (
+    // The menu treats the slider's keys as navigation between its items, which
+    // would otherwise stop the slider from ever receiving them. The handler has
+    // to sit on the wrapper because Slider takes no key handler of its own.
+    // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions
+    <div
+      className={styles.volumeRow}
+      data-testid="sound_effect_volume"
+      role="group"
+      aria-label={label}
+      onPointerMove={onPointerMove}
+      onKeyDown={(e) => {
+        if (SLIDER_KEYS.has(e.key)) e.stopPropagation();
+        else keepTabInsideMenu(e);
+      }}
+    >
+      <span className={styles.volumeLabel}>{label}</span>
+      <div className={styles.volumeControl}>
+        <VolumeOnIcon
+          width={24}
+          height={24}
+          className={styles.itemIcon}
+          aria-hidden
+        />
+        <Slider
+          className={styles.volumeSlider}
+          label={label}
+          value={raw}
+          onValueChange={setRaw}
+          onValueCommit={onCommit}
+          min={0}
+          max={1}
+          step={0.01}
+          // Slider names its thumb after the tooltip, so the tooltip has to
+          // carry what the control is, not just its value.
+          tooltipFormatter={(v) => `${label}: ${Math.round(v * 100)}%`}
+        />
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Lets Tab move focus between the device rows, the level meter and the
+ * sound-effect slider. The menu swallows Tab so that its items are walked
+ * with the arrow keys; kept from it, the browser's own focus order takes over,
+ * and the menu's focus trap keeps that order inside the menu.
+ */
+function keepTabInsideMenu(e: KeyboardEvent<HTMLElement>): void {
+  if (e.key === "Tab") e.stopPropagation();
+}

src/components/useMicrophoneLevel.test.tsx

@@ -0,0 +1,371 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { act, render, renderHook, waitFor } from "@testing-library/react";
+import { useEffect } from "react";
+
+import {
+  useMicrophoneLevel,
+  type MicrophoneLevelState,
+} from "./useMicrophoneLevel";
+
+/** However many levels a caller says it can draw; the meter asks for 18. */
+const STEPS = 18;
+
+describe("useMicrophoneLevel", () => {
+  test("level indicator follows the microphone signal level", async () => {
+    const { stream } = fakeStream();
+    const getUserMedia = vi.fn().mockResolvedValue(stream);
+    vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
+
+    const { result } = renderHook(() =>
+      useMicrophoneLevel("mic-1", true, STEPS),
+    );
+    await waitFor(() => expect(result.current.type).toBe("active"));
+    expect(result.current).toEqual({ type: "active", level: 0 });
+
+    // Speech arrives.
+    amplitude = 0.2;
+    tick(4);
+    expect(result.current.type).toBe("active");
+    const loud = result.current as { type: "active"; level: number };
+    expect(loud.level).toBeGreaterThan(0.3);
+
+    // ...and stops. The level eases back down rather than snapping to zero.
+    amplitude = 0;
+    tick(30);
+    const quiet = result.current as { type: "active"; level: number };
+    expect(quiet.level).toBeLessThan(loud.level);
+  });
+
+  test("metering resumes a capture the browser starts suspended", async () => {
+    const { stream } = fakeStream();
+    vi.stubGlobal("navigator", {
+      mediaDevices: { getUserMedia: vi.fn().mockResolvedValue(stream) },
+    });
+
+    const { result } = renderHook(() =>
+      useMicrophoneLevel("mic-1", true, STEPS),
+    );
+    await waitFor(() => expect(result.current.type).toBe("active"));
+
+    // A suspended context reports silence however loud the microphone is,
+    // which is what Firefox hands us when the page has no user activation.
+    expect(resumed).toBe(1);
+  });
+
+  test("a silent microphone re-renders nothing", async () => {
+    const { stream } = fakeStream();
+    vi.stubGlobal("navigator", {
+      mediaDevices: { getUserMedia: vi.fn().mockResolvedValue(stream) },
+    });
+    const probe = renderProbe();
+    await waitFor(() => expect(probe.state().type).toBe("active"));
+
+    // The capture keeps sampling, but a frame that would draw the same bars
+    // must not re-render the menu the meter sits in.
+    const before = probe.renders();
+    tick(30);
+    expect(probe.renders() - before).toBeLessThanOrEqual(1);
+  });
+
+  test("a steady tone re-renders only until the level settles", async () => {
+    const { stream } = fakeStream();
+    vi.stubGlobal("navigator", {
+      mediaDevices: { getUserMedia: vi.fn().mockResolvedValue(stream) },
+    });
+    const probe = renderProbe();
+    await waitFor(() => expect(probe.state().type).toBe("active"));
+
+    amplitude = 0.2;
+    tick(20);
+    expect(probe.state()).toEqual({
+      type: "active",
+      level: expect.any(Number),
+    });
+
+    const before = probe.renders();
+    tick(20);
+    expect(probe.renders() - before).toBeLessThanOrEqual(1);
+  });
+
+  test("the reported level is one the meter can draw", async () => {
+    const { stream } = fakeStream();
+    vi.stubGlobal("navigator", {
+      mediaDevices: { getUserMedia: vi.fn().mockResolvedValue(stream) },
+    });
+    const { result } = renderHook(() =>
+      useMicrophoneLevel("mic-1", true, STEPS),
+    );
+    await waitFor(() => expect(result.current.type).toBe("active"));
+
+    amplitude = 0.2;
+    tick(6);
+    const { level } = result.current as { level: number };
+    expect(level * STEPS).toBeCloseTo(Math.round(level * STEPS), 9);
+  });
+
+  test("level indicator stays idle for a silent microphone", async () => {
+    const { stream } = fakeStream();
+    vi.stubGlobal("navigator", {
+      mediaDevices: { getUserMedia: vi.fn().mockResolvedValue(stream) },
+    });
+
+    const { result } = renderHook(() =>
+      useMicrophoneLevel("mic-1", true, STEPS),
+    );
+    await waitFor(() => expect(result.current.type).toBe("active"));
+    tick(10);
+    expect(result.current).toEqual({ type: "active", level: 0 });
+  });
+
+  test("capture is re-pointed when the microphone changes", async () => {
+    const first = fakeStream();
+    const second = fakeStream();
+    const getUserMedia = vi
+      .fn()
+      .mockResolvedValueOnce(first.stream)
+      .mockResolvedValueOnce(second.stream);
+    vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
+
+    const { result, rerender } = renderHook(
+      ({ id }: { id: string }) => useMicrophoneLevel(id, true, STEPS),
+      { initialProps: { id: "mic-1" } },
+    );
+    await waitFor(() => expect(result.current.type).toBe("active"));
+    expect(getUserMedia).toHaveBeenLastCalledWith({
+      audio: { deviceId: { exact: "mic-1" } },
+    });
+
+    rerender({ id: "mic-2" });
+    await waitFor(() =>
+      expect(getUserMedia).toHaveBeenLastCalledWith({
+        audio: { deviceId: { exact: "mic-2" } },
+      }),
+    );
+    // The capture of the microphone we left must not survive the switch.
+    expect(first.stop).toHaveBeenCalled();
+    expect(second.stop).not.toHaveBeenCalled();
+  });
+
+  test("menu capture is released when closed during a device switch", async () => {
+    const { stream, stop } = fakeStream();
+    let resolveCapture: (s: MediaStream) => void = () => {};
+    const capture = new Promise<MediaStream>((resolve) => {
+      resolveCapture = resolve;
+    });
+    const getUserMedia = vi.fn().mockReturnValue(capture);
+    vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
+
+    const { result, rerender } = renderHook(
+      ({ on }: { on: boolean }) => useMicrophoneLevel("mic-1", on, STEPS),
+      { initialProps: { on: true } },
+    );
+
+    // The menu closes before the microphone finishes opening.
+    rerender({ on: false });
+    await act(async () => {
+      resolveCapture(stream);
+      await capture;
+    });
+
+    expect(stop).toHaveBeenCalled();
+    expect(result.current).toEqual({ type: "inactive" });
+    expect(frames).toHaveLength(0);
+  });
+
+  test("microphone capture is closed when metering stops", async () => {
+    const { stream, stop } = fakeStream();
+    vi.stubGlobal("navigator", {
+      mediaDevices: { getUserMedia: vi.fn().mockResolvedValue(stream) },
+    });
+
+    const { result, rerender } = renderHook(
+      ({ on }: { on: boolean }) => useMicrophoneLevel("mic-1", on, STEPS),
+      { initialProps: { on: true } },
+    );
+    await waitFor(() => expect(result.current.type).toBe("active"));
+
+    rerender({ on: false });
+    expect(stop).toHaveBeenCalled();
+    expect(closed).toBe(1);
+    expect(result.current).toEqual({ type: "inactive" });
+  });
+
+  test("a denied microphone is distinguished from one that cannot be opened", async () => {
+    const denied = Object.assign(new Error("no"), { name: "NotAllowedError" });
+    const busy = Object.assign(new Error("busy"), { name: "NotReadableError" });
+    const getUserMedia = vi
+      .fn()
+      .mockRejectedValueOnce(denied)
+      .mockRejectedValueOnce(busy);
+    vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
+
+    const { result, rerender } = renderHook(
+      ({ id }: { id: string }) => useMicrophoneLevel(id, true, STEPS),
+      { initialProps: { id: "mic-1" } },
+    );
+    await waitFor(() => expect(result.current).toEqual({ type: "denied" }));
+
+    rerender({ id: "mic-2" });
+    await waitFor(() =>
+      expect(result.current).toEqual({ type: "unavailable" }),
+    );
+  });
+
+  test("level indicator is unavailable where the page has no media devices", () => {
+    vi.stubGlobal("navigator", {});
+
+    const { result } = renderHook(() =>
+      useMicrophoneLevel("mic-1", true, STEPS),
+    );
+    expect(result.current).toEqual({ type: "unavailable" });
+  });
+
+  test("a capture is released when the audio graph fails to build", async () => {
+    const { stream, stop } = fakeStream();
+    vi.stubGlobal("navigator", {
+      mediaDevices: { getUserMedia: vi.fn().mockResolvedValue(stream) },
+    });
+    // Whatever the browser does after the microphone is already open.
+    vi.stubGlobal(
+      "AudioContext",
+      class {
+        public constructor() {
+          throw new Error("no audio backend");
+        }
+      },
+    );
+
+    const { result } = renderHook(() =>
+      useMicrophoneLevel("mic-1", true, STEPS),
+    );
+    await waitFor(() =>
+      expect(result.current).toEqual({ type: "unavailable" }),
+    );
+
+    // Otherwise the microphone stays open, and its in-use light on, behind a
+    // meter that says it is unavailable.
+    expect(stop).toHaveBeenCalled();
+  });
+
+  test("a missing microphone is reported as absent, not as silence", () => {
+    const getUserMedia = vi.fn();
+    vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
+
+    const { result } = renderHook(() =>
+      useMicrophoneLevel(undefined, true, STEPS),
+    );
+    expect(result.current).toEqual({ type: "absent" });
+    expect(getUserMedia).not.toHaveBeenCalled();
+  });
+
+  test("no capture is taken while metering is disabled", () => {
+    const getUserMedia = vi.fn();
+    vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
+
+    const { result } = renderHook(() =>
+      useMicrophoneLevel("mic-1", false, STEPS),
+    );
+    expect(getUserMedia).not.toHaveBeenCalled();
+    expect(result.current).toEqual({ type: "inactive" });
+  });
+
+  let amplitude = 0;
+  let frames: (() => void)[] = [];
+  let closed = 0;
+  let resumed = 0;
+
+  beforeEach(() => {
+    amplitude = 0;
+    frames = [];
+    closed = 0;
+    resumed = 0;
+
+    vi.stubGlobal("requestAnimationFrame", (cb: () => void) => {
+      frames.push(cb);
+      return frames.length;
+    });
+    vi.stubGlobal("cancelAnimationFrame", () => {
+      frames = [];
+    });
+    vi.stubGlobal(
+      "AudioContext",
+      class {
+        public createAnalyser(): unknown {
+          return {
+            fftSize: 1024,
+            getFloatTimeDomainData: (out: Float32Array): void => {
+              out.fill(amplitude);
+            },
+          };
+        }
+        public createMediaStreamSource(): { connect: () => void } {
+          return { connect: (): void => {} };
+        }
+        public async resume(): Promise<void> {
+          resumed++;
+          await Promise.resolve();
+        }
+        public async close(): Promise<void> {
+          closed++;
+          await Promise.resolve();
+        }
+      },
+    );
+  });
+
+  afterEach(() => vi.unstubAllGlobals());
+
+  /** A microphone that reports a constant amplitude on every sample. */
+  function fakeStream(): {
+    stream: MediaStream;
+    stop: ReturnType<typeof vi.fn>;
+  } {
+    const stop = vi.fn();
+    const stream = {
+      getTracks: () => [{ stop }],
+    } as unknown as MediaStream;
+    return { stream, stop };
+  }
+
+  /**
+   * Renders a component around the hook and counts how often it renders, which
+   * is what the menu around the meter would pay on every animation frame.
+   */
+  function renderProbe(): {
+    renders: () => number;
+    state: () => MicrophoneLevelState;
+  } {
+    let renders = 0;
+    let state: MicrophoneLevelState = { type: "inactive" };
+    function Probe(): null {
+      const current = useMicrophoneLevel("mic-1", true, STEPS);
+      // An effect with no dependencies runs once per commit, so a frame
+      // React bails out of is not counted.
+      useEffect(() => {
+        renders++;
+        state = current;
+      });
+      return null;
+    }
+    render(<Probe />);
+    return { renders: () => renders, state: () => state };
+  }
+
+  /** Runs one animation frame, if the hook has asked for one. */
+  function tick(times = 1): void {
+    for (let i = 0; i < times; i++) {
+      const pending = frames;
+      frames = [];
+      act(() => {
+        pending.forEach((f) => f());
+      });
+    }
+  }
+});

src/components/useMicrophoneLevel.ts

@@ -0,0 +1,184 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { useEffect, useState } from "react";
+import { logger as rootLogger } from "matrix-js-sdk/lib/logger";
+
+/**
+ * The state of the microphone level indicator.
+ *
+ * `inactive` is the resting state: nothing is being captured, because nothing
+ * has asked for a level yet. `absent` means there is no microphone to capture
+ * from, which is not the same as one that hears nothing. `active` means we
+ * hold a capture and `level` is the current signal level in the range 0..1.
+ * `denied` and `unavailable` are the two failure modes we distinguish, because
+ * they need different UI: the first is recoverable by the user, the second is
+ * not.
+ */
+export type MicrophoneLevelState =
+  | { type: "inactive" }
+  | { type: "absent" }
+  | { type: "active"; level: number }
+  | { type: "denied" }
+  | { type: "unavailable" };
+
+/** Signal at or below this many dBFS reads as silence. */
+const FLOOR_DB = -60;
+
+/**
+ * Smoothing applied to the displayed level. Rises are followed almost
+ * immediately so speech registers at once; falls are eased so the bars do not
+ * flicker between syllables.
+ */
+const ATTACK = 0.5;
+const RELEASE = 0.12;
+
+/**
+ * Observes the signal level of a microphone, for as long as `enabled` holds.
+ *
+ * The capture is owned by this hook and is torn down whenever `enabled` goes
+ * false, the device changes, or the component unmounts, including when any of
+ * those happen while the capture is still being acquired. Nothing outlives the
+ * caller.
+ *
+ * @param deviceId - The microphone to observe, or undefined if none is selected.
+ * @param enabled - Whether to hold a capture at all.
+ * @param steps - How many levels the caller can tell apart. The level is
+ *   rounded to one of them, and movement within a step reports nothing new.
+ */
+export function useMicrophoneLevel(
+  deviceId: string | undefined,
+  enabled: boolean,
+  steps: number,
+): MicrophoneLevelState {
+  const [state, setState] = useState<MicrophoneLevelState>({
+    type: "inactive",
+  });
+
+  useEffect(() => {
+    if (!enabled) {
+      setState({ type: "inactive" });
+      return;
+    }
+    if (deviceId === undefined) {
+      setState({ type: "absent" });
+      return;
+    }
+    // Insecure contexts have no media devices at all; nothing can be metered.
+    if (!("mediaDevices" in navigator)) {
+      setState({ type: "unavailable" });
+      return;
+    }
+
+    // Guards every asynchronous continuation below: the effect can be cleaned
+    // up while getUserMedia is still in flight, and the stream it eventually
+    // resolves with must be stopped rather than left running.
+    let disposed = false;
+    let stream: MediaStream | undefined;
+    let context: AudioContext | undefined;
+    let frame: number | undefined;
+
+    /** Gives back whatever has been acquired so far. */
+    const release = (): void => {
+      if (frame !== undefined) cancelAnimationFrame(frame);
+      stream?.getTracks().forEach((t) => t.stop());
+      // close() rejects if the context is already closed, which is possible if
+      // the browser tore it down with the page.
+      context?.close().catch(() => {});
+      stream = undefined;
+      context = undefined;
+      frame = undefined;
+    };
+
+    const dispose = (): void => {
+      disposed = true;
+      release();
+    };
+
+    navigator.mediaDevices
+      .getUserMedia({ audio: { deviceId: { exact: deviceId } } })
+      .then((acquired) => {
+        if (disposed) {
+          acquired.getTracks().forEach((t) => t.stop());
+          return;
+        }
+        stream = acquired;
+        context = new AudioContext();
+        // Firefox starts a context suspended unless the page has user
+        // activation, and a suspended context feeds the analyser silence
+        // rather than the microphone. Resuming one that already runs is a
+        // no-op.
+        void context.resume().catch(() => {});
+        const analyser = context.createAnalyser();
+        analyser.fftSize = 1024;
+        context.createMediaStreamSource(acquired).connect(analyser);
+        const samples = new Float32Array(analyser.fftSize);
+
+        let smoothed = 0;
+        const tick = (): void => {
+          if (disposed) return;
+          analyser.getFloatTimeDomainData(samples);
+          const level = amplitudeToLevel(rms(samples));
+          smoothed +=
+            (level - smoothed) * (level > smoothed ? ATTACK : RELEASE);
+          // Keep the last value when the level has not moved a whole step:
+          // a frame that would redraw the same picture must not re-render
+          // anything. Silence therefore costs nothing at all, since the level
+          // rests at zero.
+          const stepped = Math.round(smoothed * steps) / steps;
+          setState((previous) =>
+            previous.type === "active" && previous.level === stepped
+              ? previous
+              : { type: "active", level: stepped },
+          );
+          frame = requestAnimationFrame(tick);
+        };
+        setState({ type: "active", level: 0 });
+        frame = requestAnimationFrame(tick);
+      })
+      .catch((e: unknown) => {
+        if (disposed) return;
+        // The microphone may already be open: building the audio graph can
+        // fail after getUserMedia has resolved, and the capture would then
+        // outlive its own failure, holding the microphone-in-use indicator on
+        // behind a meter that says the microphone is unavailable.
+        release();
+        rootLogger
+          .getChild("[useMicrophoneLevel]")
+          .warn("Could not open microphone for level metering", e);
+        setState(classifyError(e));
+      });
+
+    return dispose;
+  }, [deviceId, enabled, steps]);
+
+  return state;
+}
+
+/** Root mean square of a block of samples, as a linear amplitude. */
+function rms(samples: Float32Array): number {
+  let sum = 0;
+  for (const s of samples) sum += s * s;
+  return Math.sqrt(sum / samples.length);
+}
+
+/** Maps a linear amplitude onto 0..1 over a fixed dBFS window. */
+function amplitudeToLevel(amplitude: number): number {
+  if (amplitude <= 0) return 0;
+  const db = 20 * Math.log10(amplitude);
+  if (db <= FLOOR_DB) return 0;
+  return Math.min(1, db / -FLOOR_DB + 1);
+}
+
+function classifyError(e: unknown): MicrophoneLevelState {
+  const name = e instanceof Error ? e.name : "";
+  // NotAllowedError is the modern name; SecurityError is what older WebKit
+  // raises for the same situation.
+  if (name === "NotAllowedError" || name === "SecurityError")
+    return { type: "denied" };
+  return { type: "unavailable" };
+}

src/config/Config.test.ts

@@ -8,8 +8,8 @@ Please see LICENSE in the repository root for full details.
 import { describe, expect, it, vi, afterEach } from "vitest";
 import { logger } from "matrix-js-sdk/lib/logger";
 
-import { validateConfig } from "./Config";
-import { MatrixRTCMode } from "./ConfigOptions";
+import { Config, validateConfig } from "./Config";
+import { DEFAULT_CONFIG, MatrixRTCMode } from "./ConfigOptions";
 
 describe("validateConfig", () => {
   afterEach(() => {
@@ -52,3 +52,52 @@ describe("validateConfig", () => {
     expect(result.ssla).toBe("https://example.invalid/ssla");
   });
 });
+
+describe("Config.initWith", () => {
+  // vitest.setup.ts has already called initDefault(), so every test here is
+  // free to re-initialize; the last call wins.
+  afterEach(() => {
+    vi.restoreAllMocks();
+    Config.initDefault();
+  });
+
+  it("makes the supplied config readable", () => {
+    Config.initWith({ ssla: "https://example.invalid/ssla" });
+    expect(Config.get().ssla).toBe("https://example.invalid/ssla");
+  });
+
+  it("fills in defaults for keys the embedder did not supply", () => {
+    Config.initWith({ ssla: "https://example.invalid/ssla" });
+    expect(Config.get().media_quality).toEqual(DEFAULT_CONFIG.media_quality);
+  });
+
+  it("validates the supplied config just as a fetched one would be", () => {
+    const warnSpy = vi.spyOn(logger, "warn").mockImplementation(() => {});
+    Config.initWith({
+      matrix_rtc_mode: "nonsense" as unknown as MatrixRTCMode,
+    });
+    expect(Config.get().matrix_rtc_mode).toBeUndefined();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not share nested state with DEFAULT_CONFIG", () => {
+    Config.initWith({});
+    expect(Config.get().media_quality).not.toBe(DEFAULT_CONFIG.media_quality);
+  });
+
+  it("stops a later init() from fetching over the top of it", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch");
+    Config.initWith({ ssla: "https://example.invalid/ssla" });
+
+    await Config.init();
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(Config.get().ssla).toBe("https://example.invalid/ssla");
+  });
+
+  it("replaces a config initialized earlier", () => {
+    Config.initWith({ ssla: "https://first.invalid/ssla" });
+    Config.initWith({ ssla: "https://second.invalid/ssla" });
+    expect(Config.get().ssla).toBe("https://second.invalid/ssla");
+  });
+});

src/config/Config.ts

@@ -30,6 +30,14 @@ export class Config {
     return this.internalInstance.config;
   }
 
+  /**
+   * Initializes the config by fetching `config.json`, locating it relative to
+   * the current page.
+   *
+   * Does nothing if the config has already been initialized, including by
+   * {@link Config.initWith}, so that the regular startup path can run unchanged
+   * when a component host has already supplied the config.
+   */
   public static async init(): Promise<void> {
     if (!Config.internalInstance?.initPromise) {
       const internalInstance = new Config();
@@ -50,17 +58,35 @@ export class Config {
 
       Config.internalInstance.initPromise = downloadConfig(fetchTarget).then(
         (config) => {
-          internalInstance.config = merge(
-            {},
-            DEFAULT_CONFIG,
-            validateConfig(config),
-          );
+          internalInstance.config = resolveConfig(config);
         },
       );
     }
     return Config.internalInstance.initPromise;
   }
 
+  /**
+   * Initializes the config from an object supplied by the application hosting
+   * the component, instead of fetching `config.json`.
+   *
+   * {@link Config.init} derives the location of `config.json` from
+   * `window.location`, which only makes sense while Element Call owns the page.
+   * As a component, the host owns the configuration and passes it in here.
+   *
+   * The config goes through the same validation and defaulting as a fetched
+   * one, so that a supplied config behaves identically to a fetched one.
+   *
+   * Replaces any config initialized earlier.
+   */
+  public static initWith(config: ConfigOptions): void {
+    const internalInstance = new Config();
+    internalInstance.config = resolveConfig(config);
+    // Mark initialization as already done, so that a later init() resolves
+    // immediately rather than fetching config.json over the top of this.
+    internalInstance.initPromise = Promise.resolve();
+    Config.internalInstance = internalInstance;
+  }
+
   /**
    * This is a alternative initializer that does not load anything
    * from a hosted config file but instead just initializes the config using the
@@ -69,8 +95,7 @@ export class Config {
    * It is supposed to only be used in tests. (It is executed in `vite.setup.js`)
    */
   public static initDefault(): void {
-    Config.internalInstance = new Config();
-    Config.internalInstance.config = { ...DEFAULT_CONFIG };
+    Config.initWith({});
   }
 
   // Convenience accessors
@@ -94,6 +119,15 @@ export class Config {
   private initPromise?: Promise<void>;
 }
 
+/**
+ * Applies validation and the built-in defaults to a config, however it was
+ * obtained. Deep-merges onto a fresh object so that the result never shares
+ * nested state with {@link DEFAULT_CONFIG}.
+ */
+function resolveConfig(config: ConfigOptions): ResolvedConfigOptions {
+  return merge({}, DEFAULT_CONFIG, validateConfig(config));
+}
+
 export function validateConfig(config: ConfigOptions): ConfigOptions {
   const mode = config.matrix_rtc_mode;
   if (mode !== undefined && !VALID_MATRIX_RTC_MODES.has(mode)) {