Offer no effects for the session where the pipeline cannot be built

- A segmenter that can't be built, with the model unreachable or a GPU
  its delegate refuses, took the camera down with the pipeline: the SDK
  fails the track it was attaching to, and the lobby muted camera and
  microphone, on every load while the choice was kept.
- One is now built on trial when an effect is first wanted, before the
  pipeline is attached to anything, on the CPU where the GPU refuses.
  Where it can't be built, the options are disabled with the existing
  notice for the rest of the session. The choice is kept: a browser
  update may fix what failed.
- The view model takes that verdict from the pipeline's state rather than
  asking the SDK, so both say the same, and it no longer builds a WebGL
  context of its own to ask.
- Until the trial is over, the lobby opens no camera and the call makes no
  camera track, so neither starts without the effect.

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

.github/workflows/build-element-call.yaml

@@ -44,7 +44,9 @@ jobs:
           node-version-file: ".node-version"
       - name: Install dependencies
         # ignore-pnpmfile should never be commited. Make CI crash if it happened (`pnpmfileChecksum` is present)
-        run: "pnpm install --frozen-lockfile --ignore-pnpmfile"
+        run: "scripts/layered.sh --ignore-pnpmfile"
+        env:
+          PR_HEAD_REPO_OWNER: ${{ github.event.pull_request.head.repo.owner.login }}
       - name: Build Element Call
         run: pnpm run build:"$PACKAGE":"$BUILD_MODE"
         env:

.github/workflows/lint.yaml

@@ -1,6 +1,12 @@
 name: Lint, format & type check
 on:
   pull_request: {}
+  workflow_call:
+    inputs:
+      matrix-js-sdk-sha:
+        type: string
+        required: false
+        description: The matrix-js-sdk commit to build against instead of the locked one
 jobs:
   lint:
     name: Lint, format & type check
@@ -9,6 +15,8 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
+          # Inside a called workflow, github.repository is the caller so we need to make sure to still check out the EC repo here.
+          repository: ${{ inputs.matrix-js-sdk-sha && 'element-hq/element-call' || github.repository }}
           persist-credentials: false
       - name: Enable Corepack
         run: corepack enable
@@ -19,7 +27,10 @@ jobs:
           node-version-file: ".node-version"
       - name: Install dependencies
         # ignore-pnpmfile should never be commited. Make CI crash if it happened (`pnpmfileChecksum` is present)
-        run: "pnpm install --frozen-lockfile --ignore-pnpmfile"
+        run: "scripts/layered.sh --ignore-pnpmfile"
+        env:
+          PR_HEAD_REPO_OWNER: ${{ github.event.pull_request.head.repo.owner.login }}
+          JS_SDK_GITHUB_BASE_REF: ${{ inputs.matrix-js-sdk-sha }}
       - name: Formatting
         run: "pnpm run format:check"
       - name: i18n

.github/workflows/test.yaml

@@ -3,6 +3,25 @@ on:
   pull_request: {}
   push:
     branches: [main]
+  workflow_call:
+    inputs:
+      matrix-js-sdk-sha:
+        type: string
+        required: false
+        description: The matrix-js-sdk commit to build against instead of the locked one
+      disable_coverage:
+        type: boolean
+        required: false
+        default: false
+        description: Skip generating and uploading coverage reports
+      disable_e2e_tests:
+        type: boolean
+        required: false
+        default: false
+        description: Skip the end-to-end tests
+    secrets:
+      CODECOV_TOKEN:
+        required: false
 jobs:
   vitest:
     name: Run unit tests
@@ -11,6 +30,8 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
+          # Inside a called workflow, github.repository is the caller so we need to make sure to still check out the EC repo here.
+          repository: ${{ inputs.matrix-js-sdk-sha && 'element-hq/element-call' || github.repository }}
           persist-credentials: false
       - name: Enable Corepack
         run: corepack enable
@@ -21,7 +42,10 @@ jobs:
           node-version-file: ".node-version"
       - name: Install dependencies
         # ignore-pnpmfile should never be commited. Make CI crash if it happened (`pnpmfileChecksum` is present)
-        run: "pnpm install --frozen-lockfile --ignore-pnpmfile"
+        run: "scripts/layered.sh --ignore-pnpmfile"
+        env:
+          PR_HEAD_REPO_OWNER: ${{ github.event.pull_request.head.repo.owner.login }}
+          JS_SDK_GITHUB_BASE_REF: ${{ inputs.matrix-js-sdk-sha }}
       - name: Get Playwright version
         run: echo "PLAYWRIGHT_VERSION=$(pnpm list @playwright/test --depth=0 --json | jq -r '.[0].devDependencies["@playwright/test"].version')" >> $GITHUB_ENV
       - name: Cache Playwright binaries
@@ -35,8 +59,11 @@ jobs:
         if: steps.playwright-cache.outputs.cache-hit != 'true'
         run: pnpm playwright install --with-deps
       - name: Vitest
-        run: "pnpm run test:coverage"
+        run: pnpm vitest --coverage.enabled="$ENABLE_COVERAGE"
+        env:
+          ENABLE_COVERAGE: ${{ !inputs.disable_coverage }}
       - name: Upload to codecov
+        if: ${{ !inputs.disable_coverage }}
         uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
@@ -45,11 +72,14 @@ jobs:
           fail_ci_if_error: true
   playwright:
     name: Run end-to-end tests
+    if: ${{ !inputs.disable_e2e_tests }}
     timeout-minutes: 60
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
+          # Inside a called workflow, github.repository is the caller so we need to make sure to still check out the EC repo here.
+          repository: ${{ inputs.matrix-js-sdk-sha && 'element-hq/element-call' || github.repository }}
           persist-credentials: false
       - name: Enable Corepack
         run: corepack enable
@@ -59,7 +89,10 @@ jobs:
           node-version-file: ".node-version"
       - name: Install dependencies
         # ignore-pnpmfile should never be commited. Make CI crash if it happened (`pnpmfileChecksum` is present)
-        run: pnpm install --frozen-lockfile --ignore-pnpmfile
+        run: scripts/layered.sh --ignore-pnpmfile
+        env:
+          PR_HEAD_REPO_OWNER: ${{ github.event.pull_request.head.repo.owner.login }}
+          JS_SDK_GITHUB_BASE_REF: ${{ inputs.matrix-js-sdk-sha }}
       - name: Get Playwright version
         run: echo "PLAYWRIGHT_VERSION=$(pnpm list @playwright/test --depth=0 --json | jq -r '.[0].devDependencies["@playwright/test"].version')" >> $GITHUB_ENV
       - name: Cache Playwright binaries

.gitignore

@@ -41,3 +41,6 @@ yarn-error.log
 
 *storybook.log
 storybook-static
+
+# Nested checkout made by scripts/layered.sh
+/matrix-js-sdk/

AGENTS.md

@@ -48,6 +48,8 @@ pnpm i18n:check
 - 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.
+- Comments only where the code can't give the reason — see
+  [code-style.md](docs/agents/code-style.md#comments).
 - Anything that redraws continuously — an animation frame, a stream — says what it
   costs, or better, counts the redraws in a test.
 - Branch `<handle>/<topic>`. Plain imperative commit subjects, no prefixes.

README.md

@@ -34,16 +34,16 @@ You can find the latest development version continuously deployed to
 ## ✨ Key Features
 
 ✅ **Decentralized & Federated** – No central authority; works across Matrix
-homeservers.  
-✅ **End-to-End Encrypted** – Secure and private calls.  
+homeservers.
+✅ **End-to-End Encrypted** – Secure and private calls.
 ✅ **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.  
+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)).  
+([MSC4195: MatrixRTC using LiveKit backend](https://github.com/hughns/matrix-spec-proposals/blob/hughns/matrixrtc-livekit/proposals/4195-matrixrtc-livekit.md)).
 ✅ **Raise Hand** – Participants can signal when they want to speak, helping to
-organize the flow of the meeting.  
+organize the flow of the meeting.
 ✅ **Emoji Reactions** – Users can react with emojis 👍️ 🎉 👏 🤘, adding
 engagement and interactivity to the conversation.
 
@@ -297,8 +297,8 @@ The package is not published yet. A host installs it as a git dependency on the
 ```
 
 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
+Corepack) on the host's machine, runs a full `pnpm install` of this repository,
+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
@@ -306,8 +306,27 @@ 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.
+`react-dom`, `matrix-js-sdk`, `livekit-client`, `@vector-im/compound-web` and
+`@vector-im/compound-design-tokens` itself, since the bundle leaves them
+external. Compound's stylesheet are the host's to load too: the component shares
+the host's copy of Compound, (required for example for tooltips)
+
+The component is large, and a host will usually load it lazily, only once a
+call is shown. Everything a host needs in order to talk about a call before
+then is also exported
+from `@element-hq/element-call-component/api` (a small entry point that does not
+load the component).
+
+- props and the types they are made of
+- the handle
+- the host bridge
+- `UserIntent`
+- `HeaderStyle`
+- `BackgroundStyle` enums
+- `configurationForIntent`, the defaults each intent implies
+  Import from it wherever a value such as
+  `BackgroundStyle.Solid` is needed on a path that must stay light; the main
+  entry point re-exports all of it too.
 
 ### Backend
 

component/ElementCall.module.css

@@ -34,10 +34,18 @@ component rather than a page makes. */
   -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;
+/* The call itself. It is a stacking context of its own, as the standalone
+page's `#root` is, so that the layers the call view uses for its header, footer
+and overlays stay below the modals and toasts, which are portalled into the
+root and carry no layer of their own.
+
+What Compound floats — tooltips, menus — is not in here at all: it goes into
+the host's body, as it would for any other component on the host's page, and is
+styled and layered by the host's copy of Compound. */
+.content {
+  display: flex;
+  flex-direction: column;
   block-size: 100%;
+  position: relative;
+  isolation: isolate;
 }

component/api.ts

@@ -0,0 +1,124 @@
+/*
+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
+ *
+ * What a host needs in order to talk about Element Call, without Element Call:
+ * the component's props and the types they are made of, the handle and the
+ * host bridge, the intents a call can be started with and the configuration
+ * each implies.
+ *
+ * This is an entry point of its own, `@element-hq/element-call-component/api`,
+ * so that a host can import it on a path that must stay light — a call model
+ * that needs `BackgroundStyle.Solid` as a value, say — and load the component
+ * itself, and everything it brings, only when a call is shown. The main entry
+ * point re-exports all of it, so a host that does not care may import
+ * everything from there.
+ *
+ * Nothing in here may reach anything that is not a type or a constant: the
+ * point of this module is what it does not import.
+ */
+
+import type { Ref } from "react";
+import type { MatrixClient } from "matrix-js-sdk";
+
+import type { UrlProperties } from "../src/UrlParams";
+import type { ElementCallHandle, ElementCallHostBridge } from "./host";
+import {
+  BackgroundStyle,
+  configurationForIntent,
+  HeaderStyle,
+  type UrlConfiguration,
+  UserIntent,
+} from "../src/UrlConfiguration";
+
+// How the host and Element Call talk to each other, and what they say
+export type { ElementCallHandle, ElementCallHostBridge } from "./host";
+export type { DeviceMuteRequest, DeviceMuteState } from "../src/HostBridge";
+export type { JoinCallData } from "../src/widget";
+// The deployment-wide configuration, as distinct from ElementCallConfiguration
+// below, which is per call
+export type { ConfigOptions } from "../src/config/ConfigOptions";
+// The values that appear in ElementCallConfiguration and in the intent, and
+// what each intent means by default
+export {
+  BackgroundStyle,
+  configurationForIntent,
+  HeaderStyle,
+  type UrlConfiguration,
+  UserIntent,
+};
+
+/**
+ * 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 the
+   * `supportedLanguages` the main entry point exports, 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;
+}

component/build/scopeStylesToRoot.test.ts

@@ -109,4 +109,12 @@ describe("scopeStylesToRoot", () => {
       ".a .b_abc12:hover { border: 0 }",
     );
   });
+
+  it("leaves an excluded stylesheet as it is", async () => {
+    const css = "body { margin: 0 } .menu { color: red }";
+    const result = await postcss([
+      scopeStylesToRoot({ exclude: [/host\.css$/] }),
+    ]).process(css, { from: "/app/host.css" });
+    expect(result.css).toBe(css);
+  });
 });

component/build/scopeStylesToRoot.ts

@@ -40,10 +40,10 @@ const IS_ROOT = `:where(${ROOT_SELECTOR})`;
  * 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:
+ * its own base styles speak of `html`, `body` and bare elements, and its custom
+ * properties 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.
@@ -55,16 +55,23 @@ const IS_ROOT = `:where(${ROOT_SELECTOR})`;
  * 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.
+ * The root's custom properties are still inherited by everything inside it,
+ * the way they were from `:root`. Compound's own stylesheet — the design
+ * tokens, the component styles, the fonts — is not in this build at all: the
+ * host supplies it, unscoped, along with its copy of Compound.
  */
-export function scopeStylesToRoot(): Plugin {
+interface Options {
+  /** Stylesheets left as they are: a host's own, which it doesn't scope. */
+  exclude?: RegExp[];
+}
+
+export function scopeStylesToRoot({ exclude = [] }: Options = {}): Plugin {
   return {
     postcssPlugin: "element-call-scope-styles-to-root",
     Once(root) {
-      const isModule =
-        root.source?.input.file?.endsWith(".module.css") ?? false;
+      const file = root.source?.input.file ?? "";
+      if (exclude.some((pattern) => pattern.test(file))) return;
+      const isModule = file.endsWith(".module.css");
       root.walkRules((rule) => {
         if (isRelative(rule)) return;
         rule.selector = (isModule ? scopeBare : scopeAll).processSync(

component/dev/main.tsx

@@ -9,6 +9,16 @@ import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { logger } from "matrix-js-sdk/lib/logger";
 
+// What a host provides along with its copy of Compound: its stylesheet, the
+// design tokens and the fonts they name. The component does not bundle them.
+import "@fontsource/inter/400.css";
+import "@fontsource/inter/500.css";
+import "@fontsource/inter/600.css";
+import "@fontsource/inter/700.css";
+import "@fontsource/inconsolata/400.css";
+import "@fontsource/inconsolata/700.css";
+import "@vector-im/compound-design-tokens/assets/web/css/compound-design-tokens.css";
+import "@vector-im/compound-web/dist/style.css";
 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

component/index.tsx

@@ -17,33 +17,37 @@ Please see LICENSE in the repository root for full details.
  * host instead, or is confined to the container it is mounted in.
  */
 
-// The design tokens, fonts and element defaults every Element Call stylesheet
+// The element defaults and custom properties 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.
 //
+// Compound is not in here. The component uses the host's copy of it (a peer
+// dependency, left external by the build), and the host loads Compound's
+// stylesheet, design tokens and fonts along with it: what Compound floats into
+// the host's body — tooltips, menus — is then styled by the same stylesheet as
+// everything else there, and Element Call's root takes the tokens and fonts of
+// the theme class it carries, as any element on the host's page would.
+//
 // 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.
+// components inherit rather than compete with.
 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";
@@ -62,119 +66,31 @@ 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 { AppViewModel } from "../src/state/AppViewModel";
 import { ObservableScope } from "../src/state/ObservableScope";
-import { ProcessorProvider } from "../src/livekit/TrackProcessorContext";
+import { BackgroundEffectsProvider } from "../src/livekit/BackgroundEffectsContext";
 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 { useComponentHostBridge } from "./host";
+import { type ElementCallProps } from "./api";
 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;
-}
+// Everything a host needs to talk about Element Call — the props, the handle,
+// the host bridge, the intents and what each means — also available without
+// the component itself from `@element-hq/element-call-component/api`
+export * from "./api";
 
 /**
  * Prepares the things Element Call needs before it can be shown: translations,
@@ -276,14 +192,12 @@ export const ElementCall: FC<ElementCallProps> = ({
   // 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);
+  const [vm, setVm] = useState<AppViewModel | null>(null);
   useEffect(() => {
     const scope = new ObservableScope();
-    setMediaDevices(
-      new MediaDevices(scope, { controlledAudioDevices, callIntent }),
-    );
+    setVm(new AppViewModel(scope, { controlledAudioDevices, callIntent }));
     return (): void => {
-      setMediaDevices(null);
+      setVm(null);
       scope.end();
     };
   }, [controlledAudioDevices, callIntent]);
@@ -304,8 +218,7 @@ export const ElementCall: FC<ElementCallProps> = ({
   // 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 ready = container !== null && rtcSession !== null && vm !== null;
   const announcedLoaded = useRef(false);
   useEffect(() => {
     if (!ready || announcedLoaded.current) return;
@@ -321,34 +234,40 @@ export const ElementCall: FC<ElementCallProps> = ({
         <UrlParamsProvider value={params}>
           <div ref={setContainer} className={styles.root}>
             {ready && (
-              <RootElementProvider value={container}>
-                {/* Whatever goes wrong in here is shown in here. Left to
+              // Stands in for the standalone page's `#root`: see `.content`
+              // in ElementCall.module.css
+              <div className={styles.content}>
+                <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>
+                  <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={vm.mediaDevices}>
+                            <BackgroundEffectsProvider
+                              effects={vm.backgroundEffects}
+                            >
+                              <CallView
+                                client={client}
+                                rtcSession={rtcSession}
+                                isPasswordlessUser={false}
+                                confineToRoom={params.confineToRoom}
+                                preload={params.preload}
+                                skipLobby={params.skipLobby}
+                              />
+                            </BackgroundEffectsProvider>
+                          </MediaDevicesContext>
+                        </ClientProvider>
+                      </TooltipProvider>
+                    </Decoration>
+                  </ErrorBoundary>
+                </RootElementProvider>
+              </div>
             )}
           </div>
         </UrlParamsProvider>

component/package.json

@@ -25,6 +25,10 @@
       "types": "./dist/types/component/index.d.ts",
       "default": "./dist/element-call.js"
     },
+    "./api": {
+      "types": "./dist/types/component/api.d.ts",
+      "default": "./dist/api.js"
+    },
     "./style.css": "./dist/element-call.css"
   },
   "sideEffects": [
@@ -34,6 +38,8 @@
     "prepare": "cd .. && pnpm install --frozen-lockfile && pnpm build:component"
   },
   "peerDependencies": {
+    "@vector-im/compound-design-tokens": "^11.0.0",
+    "@vector-im/compound-web": "^10.0.0",
     "livekit-client": "^2.18.1",
     "matrix-js-sdk": "*",
     "react": "^19",

component/tsconfig.build.json

@@ -13,8 +13,8 @@
     "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"],
+  // The entry points, plus the ambient declarations (CSS modules, `?react` SVGs,
+  // `import.meta.env`, …) that the sources they reach rely on.
+  "include": ["./index.tsx", "./api.ts", "../src/@types/*.d.ts"],
   "exclude": []
 }

config/config.devenv.json

@@ -7,7 +7,6 @@
   },
   "ssla": "https://static.element.io/legal/element-software-and-services-license-agreement-uk-1.pdf",
   "matrix_rtc_session": {
-    "wait_for_key_rotation_ms": 3000,
     "membership_event_expiry_ms": 180000000,
     "network_error_retry_ms": 100
   }

config/config.sample.json

@@ -11,7 +11,6 @@
   "ssla": "https://static.element.io/legal/element-software-and-services-license-agreement-uk-1.pdf",
   "matrix_rtc_mode": "compatibility",
   "matrix_rtc_session": {
-    "wait_for_key_rotation_ms": 3000,
     "membership_event_expiry_ms": 180000000,
     "network_error_retry_ms": 100
   }

config/config_netlify_preview.json

@@ -7,7 +7,6 @@
   },
   "ssla": "https://static.element.io/legal/element-software-and-services-license-agreement-uk-1.pdf",
   "matrix_rtc_session": {
-    "wait_for_key_rotation_ms": 3000,
     "membership_event_expiry_ms": 180000000,
     "network_error_retry_ms": 100
   },

config/config_netlify_preview_sdk.json

@@ -7,7 +7,6 @@
   },
   "ssla": "https://static.element.io/legal/element-software-and-services-license-agreement-uk-1.pdf",
   "matrix_rtc_session": {
-    "wait_for_key_rotation_ms": 3000,
     "membership_event_expiry_ms": 180000000,
     "network_error_retry_ms": 100
   }

docker-compose-playwright.yml

@@ -19,7 +19,7 @@ services:
       - ./backend/playwright_homeserver-othersite.yaml:/data/cfg/homeserver.yaml:Z
   element-web:
     # Pin to a SHA so that upstream cannot break our tests. Renovate handles regular updates.
-    image: ghcr.io/element-hq/element-web:develop@sha256:3993d53bc2c784c0376b86e00230aef0ee2c9a705b2166e9229555117e8db167
+    image: ghcr.io/element-hq/element-web:develop@sha256:589c4909fd5844a9db7dd730f9796186eabbb981580cdf9bfa597186a2fb81f3
   element-web-1:
     # Pin to a SHA so that upstream cannot break our tests. Renovate handles regular updates.
-    image: ghcr.io/element-hq/element-web:develop@sha256:3993d53bc2c784c0376b86e00230aef0ee2c9a705b2166e9229555117e8db167
+    image: ghcr.io/element-hq/element-web:develop@sha256:589c4909fd5844a9db7dd730f9796186eabbb981580cdf9bfa597186a2fb81f3

docs/agents/architecture.md

@@ -76,4 +76,10 @@ Code that builds in only one is a bug.
 - `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.
+  `matrix-js-sdk` / `livekit-client` / `@vector-im/compound-web` /
+  `@vector-im/compound-design-tokens` subpath the externals list omits.
+  Compound's stylesheets are loaded by `src/index.css` for the page and by the
+  host for the component, never by `src/base.css`. Two entry
+  points: `index.tsx` (the component) and `api.ts` (types, enums and
+  `configurationForIntent`, for a host that must not load the component). `api.ts`
+  may only reach types and constants — `src/UrlConfiguration.ts`, not `UrlParams`.

docs/agents/code-style.md

@@ -31,7 +31,28 @@ copy, the PR says so.
 - **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.
+  `computedLayout$`.
+
+## Comments
+
+No comment is the default. One earns its place by giving a reason the code
+cannot: a platform quirk, an outside constraint, a trap that looks like a
+simplification.
+
+- Say the reason, then stop. Test each sentence: does the reason still stand
+  without it? If so, cut it. Most reasons fit on a line, so a long comment is
+  worth a second look — it is usually carrying something that isn't one.
+- Write about the line the comment sits on, in terms of what the code does
+  there — leave layout to the stylesheet and measurements to the design.
+- Name the condition ("where the platform can't route audio"), not the browser
+  or the spec entry.
+- Put history — what was tried, removed or rejected, the dev journal — in the
+  commit or the PR description.
+- In tests, comment only structure that looks wrong but isn't: batching, timers,
+  why this scroll position.
+
+Before keeping one: would it still be true after a CSS change or a refactor of
+its caller? If not, cut it.
 
 ## TypeScript, React and RxJS idiom win on a clash
 

docs/linking.md

@@ -60,6 +60,21 @@ git config --local core.hooksPath .githooks
 
 This will add the hook path for this repository only to .gihooks. which is a tracked (by git) folder containing the pre-commit hook.
 
+## Testing against a matrix-js-sdk branch in CI
+
+Linking covers local development. In CI, `scripts/layered.sh` plays the same
+role for `matrix-js-sdk`: after the usual frozen install, `scripts/fetchdep.sh`
+looks for a matrix-js-sdk branch with the same name as the pull request's head
+branch (in the fork first, when the pull request comes from one). If there is
+one, it is cloned, packed and installed over the locked version. If there is
+none, the install stays as `pnpm-lock.yaml` pins it.
+
+This means a change that needs a not yet merged matrix-js-sdk change can be tested
+by giving both branches the same name. This mirrors how element-web tests against
+matrix-js-sdk. Once the matrix-js-sdk branch is merged and deleted, the pull
+request falls back to the lockfile and needs a lockfile bump to stay green,
+which is also what keeps `main` consistent after the merge.
+
 ## Background
 
 Information, why this approach is used can be found in the [linking concept reasoning](./linking_concept_reasoning.md) document.

docs/matrix_rtc_modes.md

@@ -24,7 +24,7 @@ homeserver does not support sticky events. This is the default.
 MSC4354 and all clients on v0.17.0 or later. The local membership requests its
 token from the Matrix 2.0 JWT endpoint of the
 [MatrixRTC Authorization Service](https://github.com/element-hq/lk-jwt-service)
-and identifies the room by a hashed identity instead of a `livekit_alias`.
+and identifies the room by a hashed identity instead of the Matrix `room_id`.
 (Remote memberships always try the new endpoint first and fall back to the
 legacy one, so remote participants can be on either.)
 

locales/en/app.json

@@ -3,7 +3,7 @@
     "user_menu": "User menu"
   },
   "action": {
-    "blur_background": "Blur background",
+    "add_background_image": "Add image",
     "close": "Close",
     "copy_link": "Copy link",
     "edit": "Edit",
@@ -23,6 +23,13 @@
     "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>.",
+  "background_effects": {
+    "blur": "Blur",
+    "none": "None",
+    "numbered": "Background {{n}}",
+    "slow": "Background effects run slowly on this platform, which may cause your video to stutter.",
+    "unavailable": "Background effects are not supported on this platform."
+  },
   "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>",
@@ -92,6 +99,10 @@
   },
   "disconnected_banner": "Connectivity to the server has been lost.",
   "error": {
+    "background_animated": "Animated images cannot be used as a background",
+    "background_not_an_image": "That file is not a supported image",
+    "background_not_kept": "That background could not be saved",
+    "background_undecodable": "That image could not be opened",
     "call_is_not_supported": "Call is not supported",
     "call_not_found": "Call not found",
     "call_not_found_description": "<0>That link doesn't appear to belong to any existing call. Check that you have the right link, or <2>create a new one</2>.</0>",
@@ -163,6 +174,12 @@
   "login_auth_links_prompt": "Not registered yet?",
   "login_subheading": "To continue to Element",
   "login_title": "Login",
+  "microphone_level": {
+    "label": "Microphone level",
+    "no_device": "No microphone found. Connect one, then try again.",
+    "permission_denied": "Microphone access is blocked. Allow it, then try again.",
+    "value": "{{level}} of {{max}}"
+  },
   "microphone_off": "Microphone off",
   "microphone_on": "Microphone on",
   "mute_microphone_button_label": "Mute microphone",
@@ -206,6 +223,7 @@
     "auto_gain_control_label": "Automatic gain control",
     "background_blur_header": "Background",
     "background_blur_label": "Blur the background of the video",
+    "background_effects_header": "Background effects",
     "bitrate_label": "Bitrate",
     "blur_not_supported_by_browser": "(Background blur is not supported by this device.)",
     "camera_header": "Camera quality",
@@ -215,11 +233,14 @@
       "activating": "Activating…",
       "camera": "Camera",
       "camera_numbered": "Camera {{n}}",
+      "camera_source": "Camera Source",
       "change_device_button": "Change audio device",
       "default": "Default",
       "default_named": "Default <2>({{name}})</2>",
+      "default_named_plain": "Default ({{name}})",
       "handset": "Handset",
       "loudspeaker": "Loudspeaker",
+      "mic_source": "Mic Source",
       "microphone": "Microphone",
       "microphone_numbered": "Microphone {{n}}",
       "speaker": "Speaker",

package.json

@@ -8,7 +8,7 @@
     "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": "node --max-old-space-size=16384 node_modules/vite/bin/vite.js build",
     "build:full:production": "pnpm build:full",
     "build:full:development": "pnpm build:full --mode development",
     "build:embedded": "pnpm build:full --config vite-embedded.config.js",
@@ -83,8 +83,8 @@
     "@types/sdp-transform": "^2.4.5",
     "@typescript-eslint/utils": "^8.61.0",
     "@use-gesture/react": "^10.2.11",
-    "@vector-im/compound-design-tokens": "^11.0.0",
-    "@vector-im/compound-web": "^10.0.0",
+    "@vector-im/compound-design-tokens": "^11.1.0",
+    "@vector-im/compound-web": "^10.3.0",
     "@vitejs/plugin-react": "^6.0.2",
     "@vitest/browser-playwright": "^4.1.5",
     "@vitest/coverage-v8": "^4.0.18",
@@ -94,6 +94,7 @@
     "copy-to-clipboard": "^3.3.3",
     "eslint-plugin-element-call": "link:eslint",
     "eslint-plugin-storybook": "^10.3.6",
+    "fake-indexeddb": "^6.2.5",
     "fetch-mock": "11.1.5",
     "i18next": "^26.0.0",
     "i18next-browser-languagedetector": "^8.0.0",
@@ -107,7 +108,6 @@
     "matrix-widget-api": "^1.18.0",
     "node-stdlib-browser": "^1.3.1",
     "normalize.css": "^8.0.1",
-    "observable-hooks": "^4.2.3",
     "oxfmt": "^0.66.0",
     "oxlint": "^1.70.0",
     "oxlint-tsgolint": "^0.25.0",
@@ -130,7 +130,6 @@
     "uuid": "^14.0.0",
     "vaul": "^1.0.0",
     "vite": "^8.0.0",
-    "vite-plugin-generate-file": "^0.3.0",
     "vite-plugin-html": "^3.2.2",
     "vite-plugin-node-polyfills": "^0.28.0",
     "vite-plugin-node-stdlib-browser": "^0.2.1",

playwright/audio-menu.spec.ts

@@ -0,0 +1,229 @@
+/*
+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, type Locator, type Page } from "@playwright/test";
+
+import { SpaHelpers } from "./spa-helpers.ts";
+import { installFakeDevices } from "./utils/fake-devices.ts";
+
+test.describe("the quick audio menu", () => {
+  test("lists speakers and microphones with a live level meter", async ({
+    page,
+  }) => {
+    await installFakeDevices(page, { microphones: 3, speakers: 3 });
+    await joinACall(page, "Menu user", "Audio menu");
+    await openAudioMenu(page);
+
+    await expect(page.getByRole("group", { name: "Speaker" })).toBeVisible();
+    await expect(page.getByRole("group", { name: "Microphone" })).toBeVisible();
+    // By name, not count: the browser adds its own fake output and a Default.
+    for (const n of [1, 2, 3])
+      await expect(
+        page
+          .getByRole("group", { name: "Speaker" })
+          .getByRole("menuitemradio", { name: `Fake Speaker ${n}` }),
+      ).toBeVisible();
+
+    await expect(
+      page.getByRole("menuitemradio", { checked: true }),
+    ).toHaveCount(2);
+    const meter = page.getByRole("meter", { name: "Microphone level" });
+    await expect(meter).toBeVisible();
+    await expect(meter).toHaveAttribute("aria-valuenow", /\d+/);
+    await expect(meter).toHaveAttribute("aria-valuetext", /\d+ of \d+/);
+
+    // Both browsers here can route audio; the platform that can't is a unit check.
+    await expect(
+      page
+        .getByRole("group", { name: "Speaker" })
+        .getByRole("menuitemradio")
+        .first(),
+    ).toHaveAttribute("aria-disabled", "false");
+  });
+
+  test("moves the microphone and the speaker without disturbing the call", async ({
+    browser,
+  }) => {
+    // Two browsers and a real call.
+    test.slow();
+    const hostContext = await browser.newContext({ reducedMotion: "reduce" });
+    const host = await hostContext.newPage();
+    await installFakeDevices(host, { microphones: 3, speakers: 3 });
+    await joinACall(host, "Host", "Device switch");
+
+    const inviteLink = await SpaHelpers.getCallInviteLink(host);
+    const guestContext = await browser.newContext({ reducedMotion: "reduce" });
+    const guest = await guestContext.newPage();
+    await SpaHelpers.joinCallFromInviteLink(guest, inviteLink, "Guest");
+    await SpaHelpers.expectVideoTilesCount(guest, 2);
+
+    await openAudioMenu(host);
+    await selectDevice(host, "Microphone", "Fake Microphone 2");
+    await openAudioMenu(host);
+    await selectDevice(host, "Speaker", "Fake Speaker 2");
+
+    // Not a rejoin: neither side drops, and the guest still has both tiles.
+    await expect(
+      host.getByRole("dialog", { name: "Reconnecting…" }),
+    ).not.toBeVisible();
+    await expect(
+      guest.getByRole("dialog", { name: "Reconnecting…" }),
+    ).not.toBeVisible();
+    await SpaHelpers.expectVideoTilesCount(guest, 2);
+    await expect(guest.getByText("Waiting for media...")).not.toBeVisible();
+
+    await hostContext.close();
+    await guestContext.close();
+  });
+
+  test("keeps the meter moving while muted, and sends nothing", async ({
+    browser,
+  }) => {
+    // Two browsers and a real call.
+    test.slow();
+    const hostContext = await browser.newContext({ reducedMotion: "reduce" });
+    const host = await hostContext.newPage();
+    await installFakeDevices(host);
+    await joinACall(host, "Muted host", "Muted meter");
+
+    const inviteLink = await SpaHelpers.getCallInviteLink(host);
+    const guestContext = await browser.newContext({ reducedMotion: "reduce" });
+    const guest = await guestContext.newPage();
+    await SpaHelpers.joinCallFromInviteLink(guest, inviteLink, "Listener");
+    await SpaHelpers.expectVideoTilesCount(guest, 2);
+
+    const mute = host.getByTestId("incall_mute");
+    await mute.click();
+    await expect(mute).toHaveAttribute("aria-checked", "false");
+    await openAudioMenu(host);
+
+    const meter = host.getByRole("meter", { name: "Microphone level" });
+    await expect(meter).toBeVisible();
+    // By test id: the modal menu hides the rest of the call from the a11y tree.
+    await expect(mute).toHaveAttribute("aria-checked", "false");
+    await expect(mute).toBeVisible();
+    // And the guest is shown the mute.
+    await expect(
+      guest.getByTestId("videoTile").filter({ hasText: "Muted host" }),
+    ).toBeVisible();
+
+    await hostContext.close();
+    await guestContext.close();
+  });
+
+  test("keeps the meter at the foot of the list while it scrolls", async ({
+    page,
+  }) => {
+    await installFakeDevices(page, { microphones: 20, speakers: 4 });
+    await joinACall(page, "Scroller", "Long device list");
+    await openAudioMenu(page);
+
+    const meter = page.getByRole("meter", { name: "Microphone level" });
+    await expect(meter).toBeVisible();
+
+    // Scrolled so the microphones start at the top: only there does a pinned
+    // meter differ from one that is simply last.
+    const list = page.locator("[role='menu'] div[role='none']").first();
+    await list.evaluate((element) => {
+      const group = element.querySelector("[role='group'][aria-label*='icro']");
+      element.scrollTop +=
+        group!.getBoundingClientRect().top -
+        element.getBoundingClientRect().top;
+    });
+
+    await expect(meter).toBeInViewport();
+    await expectPinnedInside(meter, list);
+    await expect(
+      page.getByRole("menuitemradio", { name: "Fake Microphone 20" }),
+    ).toBeVisible();
+  });
+
+  test("shows the focus ring only when the keyboard moved the focus", async ({
+    page,
+    browserName,
+  }) => {
+    test.skip(
+      browserName === "firefox",
+      "Headless Firefox does not deliver synthetic key presses reliably; see reconnect.spec.ts",
+    );
+    await installFakeDevices(page);
+    await joinACall(page, "Keyboard user", "Focus ring");
+    await openAudioMenu(page);
+
+    const first = page.getByRole("menuitemradio").first();
+    // Opened by pointer: no ring, though Radix has moved focus into the menu.
+    await expect.poll(async () => outlineWidth(first)).toBe(0);
+
+    await page.keyboard.press("ArrowDown");
+    const focused = page.locator("[role='menuitemradio']:focus");
+    await expect.poll(async () => outlineWidth(focused)).toBeGreaterThan(0);
+
+    // And the pointer takes it away again.
+    await first.hover();
+    await expect.poll(async () => outlineWidth(focused)).toBe(0);
+  });
+});
+
+/** Creates a call and joins it, leaving the page in the call. */
+async function joinACall(
+  page: Page,
+  userName: string,
+  callName: string,
+): Promise<void> {
+  await page.goto("/");
+  await SpaHelpers.createCall(page, userName, callName, true);
+  await expect(page.getByTestId("name_tag")).toContainText(userName);
+  // The media controls stay disabled until devices have enumerated.
+  await expect(page.getByTestId("incall_mute")).toBeEnabled({
+    timeout: 10_000,
+  });
+}
+
+async function openAudioMenu(page: Page): Promise<void> {
+  await page.getByRole("button", { name: "Microphone" }).click();
+  await expect(page.getByRole("menu")).toBeVisible();
+}
+
+async function selectDevice(
+  page: Page,
+  section: "Speaker" | "Microphone",
+  name: string,
+): Promise<void> {
+  const item = page
+    .getByRole("group", { name: section })
+    .getByRole("menuitemradio", { name });
+  await item.click();
+  // Selecting doesn't close the menu, so dismiss it.
+  await page.keyboard.press("Escape");
+  await expect(page.getByRole("menu")).not.toBeVisible();
+}
+
+/** Asserts the meter sits within the scrollport and inside the menu's frame. */
+async function expectPinnedInside(
+  meter: Locator,
+  list: Locator,
+): Promise<void> {
+  const meterBox = (await meter.boundingBox())!;
+  const listBox = (await list.boundingBox())!;
+  const frame = (await meter.page().getByRole("menu").boundingBox())!;
+
+  expect(meterBox.y + meterBox.height).toBeLessThanOrEqual(
+    listBox.y + listBox.height + 1,
+  );
+  expect(meterBox.y).toBeGreaterThanOrEqual(listBox.y - 1);
+  expect(meterBox.x).toBeGreaterThan(frame.x);
+  expect(meterBox.x + meterBox.width).toBeLessThan(frame.x + frame.width);
+}
+
+/** Painted outline width, in px. */
+async function outlineWidth(item: Locator): Promise<number> {
+  if ((await item.count()) === 0) return 0;
+  return item.first().evaluate((element) => {
+    const { outlineStyle, outlineWidth } = getComputedStyle(element);
+    return outlineStyle === "none" ? 0 : Number.parseFloat(outlineWidth) || 0;
+  });
+}

playwright/background-effects.spec.ts

@@ -0,0 +1,919 @@
+/*
+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, type Browser, type Page } from "@playwright/test";
+
+import { SpaHelpers } from "./spa-helpers.ts";
+import {
+  averageColour,
+  cameraColour,
+  type Colour,
+  distance,
+} from "./utils/colour.ts";
+
+// Background effects need WebGL2, and headless Firefox on a CI runner has none,
+// so it rightly offers none of them.
+test.skip(
+  ({ browserName }) => browserName === "firefox",
+  "Background effects need WebGL2, which headless Firefox on CI does not have",
+);
+
+test.describe("background effects", () => {
+  test("pre-join preview shows the chosen effect", async ({ page }) => {
+    test.slow();
+    await page.goto("/");
+    await SpaHelpers.createCall(page, "Effect user", "Background effects");
+    const preview = page.locator("video").first();
+    const camera = await cameraColour(preview);
+
+    await page.getByRole("button", { name: "Camera", exact: true }).click();
+    const tile = page
+      .getByRole("group", { name: "Background effects" })
+      .getByRole("menuitemradio", { name: "Background 1" });
+    await tile.click();
+    await expect(tile).toHaveAttribute("aria-checked", "true");
+
+    // The fake camera shows no person, so the whole frame is background: the
+    // preview takes on the picture's colours and leaves the camera's.
+    const picture = await averageColour(tile.locator("img"));
+    // Long enough for the first effect of a session to be built.
+    await expect
+      .poll(async () => distance(await averageColour(preview), picture), {
+        timeout: 60_000,
+      })
+      .toBeLessThan(distance(camera, picture) / 2);
+  });
+});
+
+test.describe("no effect", () => {
+  test("draws nothing, even after blurring", async ({ page }) => {
+    test.setTimeout(120_000);
+    await countDraws(page);
+    await page.goto("/");
+    await SpaHelpers.createCall(page, "Idle user", "No effect after blur");
+
+    await page.getByRole("button", { name: "Camera", exact: true }).click();
+    const effects = page.getByRole("group", { name: "Background effects" });
+    await effects.getByRole("menuitemradio", { name: "Blur" }).click();
+    // Long enough for the first effect of a session to be built.
+    await expect
+      .poll(async () => drawsPerSecond(page), { timeout: 60_000 })
+      .toBeGreaterThan(0);
+    const blurred = await drawsPerSecond(page);
+
+    await effects.getByRole("menuitemradio", { name: "None" }).click();
+    // A frame already on its way may still be drawn.
+    await expect.poll(async () => drawsPerSecond(page)).toBe(0);
+    test.info().annotations.push({
+      type: "WebGL draws per second",
+      description: `blurred ${blurred}, none 0`,
+    });
+  });
+});
+
+/** Counts every WebGL draw on the page, the segmenter's and the effect's. */
+async function countDraws(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    const counter = { draws: 0 };
+    (window as unknown as { webglDraws: typeof counter }).webglDraws = counter;
+    for (const name of ["drawArrays", "drawElements"] as const) {
+      const draw = WebGL2RenderingContext.prototype[name] as (
+        ...args: unknown[]
+      ) => void;
+      WebGL2RenderingContext.prototype[name] = function (
+        this: WebGL2RenderingContext,
+        ...args: unknown[]
+      ): void {
+        counter.draws += 1;
+        draw.apply(this, args);
+      } as never;
+    }
+  });
+}
+
+/** WebGL draws over the next second. */
+async function drawsPerSecond(page: Page): Promise<number> {
+  return page.evaluate(async () => {
+    const counter = (window as unknown as { webglDraws: { draws: number } })
+      .webglDraws;
+    const before = counter.draws;
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    return counter.draws - before;
+  });
+}
+
+test.describe("the camera menu's preview", () => {
+  test("shows the camera with the effect in force", async ({ page }) => {
+    test.setTimeout(120_000);
+    await page.goto("/");
+    await SpaHelpers.createCall(page, "Preview user", "Preview in the menu");
+    const camera = await cameraColour(page.locator("video").first());
+
+    await page.getByRole("button", { name: "Camera", exact: true }).click();
+    const preview = page.getByRole("menu").locator("video");
+    await expect(preview).toBeVisible();
+    await expect
+      .poll(async () => distance(await averageColour(preview), camera), {
+        timeout: 20_000,
+      })
+      .toBeLessThan(30);
+
+    const tile = page.getByRole("menuitemradio", { name: "Background 1" });
+    await tile.click();
+    const picture = await averageColour(tile.locator("img"));
+    await expect
+      .poll(async () => distance(await averageColour(preview), picture), {
+        timeout: 60_000,
+      })
+      .toBeLessThan(distance(camera, picture) / 2);
+  });
+});
+
+test.describe("background effects section", () => {
+  test("section stays within the call area at every size", async ({ page }) => {
+    test.setTimeout(120_000);
+    await page.goto("/");
+    await SpaHelpers.createCall(page, "Sizes user", "Background effect sizes");
+
+    for (const size of [
+      { width: 1280, height: 800 },
+      { width: 800, height: 600 },
+      { width: 600, height: 420 },
+      { width: 480, height: 360 },
+      { width: 360, height: 640 },
+    ]) {
+      await page.setViewportSize(size);
+      await page.getByRole("button", { name: "Camera", exact: true }).click();
+      const menu = page.getByRole("menu");
+      await expect(menu).toBeVisible();
+
+      const box = (await menu.boundingBox())!;
+      const where = `at ${size.width}x${size.height}`;
+      expect(box.x, where).toBeGreaterThanOrEqual(0);
+      expect(box.y, where).toBeGreaterThanOrEqual(0);
+      expect(box.x + box.width, where).toBeLessThanOrEqual(size.width);
+      expect(box.y + box.height, where).toBeLessThanOrEqual(size.height);
+
+      const last = page
+        .getByRole("group", { name: "Background effects" })
+        .getByRole("menuitemradio")
+        .last();
+      await last.scrollIntoViewIfNeeded();
+      await expect(last, where).toBeInViewport({ ratio: 1 });
+      await last.click();
+      await expect(last, where).toHaveAttribute("aria-checked", "true");
+
+      // Back to no effect for the next size, and close.
+      await page
+        .getByRole("group", { name: "Background effects" })
+        .getByRole("menuitemradio", { name: "None" })
+        .click();
+      await page.keyboard.press("Escape");
+      await expect(menu).toBeHidden();
+    }
+  });
+});
+
+test.describe("a pipeline that fails to build", () => {
+  test("offers no effects for the session, and keeps the choice", async ({
+    page,
+  }) => {
+    test.setTimeout(120_000);
+    await page.goto("/");
+    await SpaHelpers.createCall(page, "Failing user", "Pipeline fails");
+    const preview = page.locator("video").first();
+    const camera = await cameraColour(preview);
+    await page.route("**/*.tflite*", async (route) => route.abort());
+
+    await page.getByRole("button", { name: "Camera", exact: true }).click();
+    const tile = page.getByRole("menuitemradio", { name: "Background 1" });
+    await tile.click();
+    await expect(
+      page.getByText("Background effects are not supported on this platform."),
+    ).toBeVisible({ timeout: 30_000 });
+    await expect(tile).toBeDisabled();
+    await page.keyboard.press("Escape");
+    // The camera and microphone carry on without it.
+    expect(distance(await cameraColour(preview), camera)).toBeLessThan(30);
+    await expect(page.getByTestId("incall_mute")).toHaveAttribute(
+      "aria-checked",
+      "true",
+    );
+
+    await page.unroute("**/*.tflite*");
+    await page.reload();
+    await expect(page.getByTestId("lobby_joinCall")).toBeVisible();
+    await page.getByRole("button", { name: "Camera", exact: true }).click();
+    await expect(tile).toHaveAttribute("aria-checked", "true");
+    const picture = await averageColour(tile.locator("img"));
+    await expect
+      .poll(async () => distance(await averageColour(preview), picture), {
+        timeout: 60_000,
+      })
+      .toBeLessThan(distance(camera, picture) / 2);
+  });
+});
+
+test.describe("the chosen effect", () => {
+  test("chosen effect survives leaving and rejoining", async ({ page }) => {
+    test.setTimeout(120_000);
+    await page.goto("/");
+    await SpaHelpers.createCall(page, "Returning user", "Effect remembered");
+    const { camera, picture } = await chooseAndWear(page, "Background 1");
+    await page.getByTestId("lobby_joinCall").click();
+    await page.getByTestId("incall_leave").click();
+    await expect(page.getByRole("heading")).toContainText(
+      "your call has ended",
+    );
+
+    await page.goto("/");
+    await page.getByTestId("home_callName").fill("Effect remembered again");
+    await page.getByTestId("home_go").click();
+    await expect(page.getByTestId("lobby_joinCall")).toBeVisible();
+    await page.getByRole("button", { name: "Camera", exact: true }).click();
+    const tile = page
+      .getByRole("group", { name: "Background effects" })
+      .getByRole("menuitemradio", { name: "Background 1" });
+    await expect(tile).toHaveAttribute("aria-checked", "true");
+    const preview = page.locator("video").first();
+    await expect
+      .poll(async () => distance(await averageColour(preview), picture), {
+        timeout: 60_000,
+      })
+      .toBeLessThan(distance(camera, picture) / 2);
+  });
+
+  test("second session still shows the existing error", async ({ page }) => {
+    test.setTimeout(120_000);
+    await page.goto("/");
+    await SpaHelpers.createCall(page, "Two tabs", "Effect in two tabs");
+    await chooseAndWear(page, "Background 1");
+
+    const second = await page.context().newPage();
+    await second.goto("/");
+    await expect(
+      page.getByRole("heading", { name: "Opened in another tab" }),
+    ).toBeVisible();
+  });
+});
+
+/** Chooses an effect in the lobby, and waits until the preview wears it. */
+async function chooseAndWear(
+  page: Page,
+  name: string,
+): Promise<{ camera: Colour; picture: Colour }> {
+  const preview = page.locator("video").first();
+  const camera = await cameraColour(preview);
+  await page.getByRole("button", { name: "Camera", exact: true }).click();
+  const tile = page.getByRole("menuitemradio", { name });
+  await tile.click();
+  const picture = await averageColour(tile.locator("img"));
+  await expect
+    .poll(async () => distance(await averageColour(preview), picture), {
+      timeout: 60_000,
+    })
+    .toBeLessThan(distance(camera, picture) / 2);
+  await page.keyboard.press("Escape");
+  return { camera, picture };
+}
+
+test.describe("a background of one's own", () => {
+  test("adds an image from the device", async ({ page }) => {
+    test.setTimeout(120_000);
+    await page.goto("/");
+    await SpaHelpers.createCall(page, "Adding user", "Own background");
+    const preview = page.locator("video").first();
+    const camera = await cameraColour(preview);
+    const red = await redImage(page);
+
+    await addImage(page, red);
+    const mine = page
+      .getByRole("group", { name: "Background effects" })
+      .getByRole("menuitemradio", { name: "Background 3" });
+    await expect(mine).toBeVisible();
+    await expect(mine).toHaveAttribute("aria-checked", "false");
+
+    await mine.click();
+    await expect
+      .poll(async () => distance(await averageColour(preview), RED), {
+        timeout: 60_000,
+      })
+      .toBeLessThan(distance(camera, RED) / 2);
+  });
+
+  test("adding an image makes no upload", async ({ page }) => {
+    test.setTimeout(120_000);
+    await page.goto("/");
+    await SpaHelpers.createCall(page, "Private user", "Own background kept");
+    const preview = page.locator("video").first();
+    const camera = await cameraColour(preview);
+    const red = await redImage(page);
+    const sent: { request: string; body: Buffer | null }[] = [];
+    page.on("request", (request) =>
+      sent.push({
+        request: `${request.method()} ${request.url()}`,
+        body: request.postDataBuffer(),
+      }),
+    );
+
+    await addImage(page, red);
+    await page
+      .getByRole("group", { name: "Background effects" })
+      .getByRole("menuitemradio", { name: "Background 3" })
+      .click();
+    // Kept, chosen and in force: anything that would send it has had its turn.
+    await expect
+      .poll(async () => distance(await averageColour(preview), RED), {
+        timeout: 60_000,
+      })
+      .toBeLessThan(distance(camera, RED) / 2);
+    // The file as given, and the copy kept, which is encoded anew.
+    const samples = [red, await keptBytes(page)].map((bytes) =>
+      bytes.subarray(bytes.length - 64),
+    );
+    const carriesIt = sent.filter(
+      ({ request, body }) =>
+        request.includes("/_matrix/media/") ||
+        samples.some((sample) => body?.includes(sample)),
+    );
+    expect(carriesIt.map(({ request }) => request)).toEqual([]);
+  });
+
+  test("added image survives rejoining and is gone after storage is cleared", async ({
+    page,
+  }) => {
+    test.setTimeout(120_000);
+    await page.goto("/");
+    await SpaHelpers.createCall(page, "Keeping user", "Own background again");
+    const preview = page.locator("video").first();
+    const camera = await cameraColour(preview);
+    const red = await redImage(page);
+    await addImage(page, red);
+    const mine = page
+      .getByRole("group", { name: "Background effects" })
+      .getByRole("menuitemradio", { name: "Background 3" });
+    await mine.click();
+    await page.keyboard.press("Escape");
+
+    await page.reload();
+    await expect(page.getByTestId("lobby_joinCall")).toBeVisible();
+    await page.getByRole("button", { name: "Camera", exact: true }).click();
+    await expect(mine).toHaveAttribute("aria-checked", "true");
+    await page.keyboard.press("Escape");
+    await expect
+      .poll(async () => distance(await averageColour(preview), RED), {
+        timeout: 60_000,
+      })
+      .toBeLessThan(distance(camera, RED) / 2);
+
+    await page.evaluate(
+      async () =>
+        new Promise<void>((resolve, reject) => {
+          const request = indexedDB.deleteDatabase(
+            "element-call-background-images",
+          );
+          request.onsuccess = (): void => resolve();
+          request.onerror = (): void => reject(request.error);
+          request.onblocked = (): void => resolve();
+        }),
+    );
+    await page.reload();
+    await expect(page.getByTestId("lobby_joinCall")).toBeVisible();
+    await page.getByRole("button", { name: "Camera", exact: true }).click();
+    await expect(
+      page.getByRole("group", { name: "Background effects" }),
+    ).toBeVisible();
+    await expect(mine).toHaveCount(0);
+    await page.keyboard.press("Escape");
+
+    await addImage(page, red);
+    await expect(mine).toBeVisible();
+  });
+
+  test("a removed image stays removed", async ({ page }) => {
+    test.setTimeout(120_000);
+    await page.goto("/");
+    await SpaHelpers.createCall(
+      page,
+      "Removing user",
+      "Own background removed",
+    );
+    await addImage(page, await redImage(page));
+    const mine = page
+      .getByRole("group", { name: "Background effects" })
+      .getByRole("menuitemradio", { name: "Background 3" });
+    await expect(mine).toHaveAttribute("aria-keyshortcuts", "Delete");
+    await mine.focus();
+    await page.keyboard.press("Delete");
+    await expect(mine).toHaveCount(0);
+
+    await page.reload();
+    await expect(page.getByTestId("lobby_joinCall")).toBeVisible();
+    await page.getByRole("button", { name: "Camera", exact: true }).click();
+    await expect(
+      page.getByRole("group", { name: "Background effects" }),
+    ).toBeVisible();
+    await expect(mine).toHaveCount(0);
+    expect(await keptImages(page)).toEqual([]);
+  });
+});
+
+test.describe("what can be added", () => {
+  test("refuses an animated image", async ({ page }) => {
+    test.setTimeout(120_000);
+    await page.goto("/");
+    await SpaHelpers.createCall(page, "Refused user", "Animated refused");
+    await addImage(page, ANIMATED_GIF, {
+      name: "moving.gif",
+      type: "image/gif",
+    });
+
+    await expect(
+      page.getByText("Animated images cannot be used as a background"),
+    ).toBeVisible();
+    const section = page.getByRole("group", { name: "Background effects" });
+    await expect(
+      section.getByRole("menuitemradio", { name: "Background 3" }),
+    ).toHaveCount(0);
+    await expect(
+      section.getByRole("menuitemradio", { name: "None" }),
+    ).toHaveAttribute("aria-checked", "true");
+    expect(await keptImages(page)).toEqual([]);
+  });
+
+  test("reduces an oversized image", async ({ page }) => {
+    test.setTimeout(120_000);
+    await page.goto("/");
+    await SpaHelpers.createCall(page, "Large user", "Oversized reduced");
+    await addImage(page, await pngImage(page, { width: 4000, height: 3000 }));
+
+    await expect(
+      page
+        .getByRole("group", { name: "Background effects" })
+        .getByRole("menuitemradio", { name: "Background 3" }),
+    ).toBeVisible();
+    await expect(page.getByRole("alert")).toHaveCount(0);
+    const [kept] = await keptImages(page);
+    expect(kept).toMatchObject({ width: 1920, height: 1440 });
+  });
+
+  test("lays every image on an opaque ground", async ({ page }) => {
+    test.setTimeout(120_000);
+    await page.goto("/");
+    await SpaHelpers.createCall(page, "Logo user", "Transparent made opaque");
+    await addImage(
+      page,
+      await pngImage(page, { width: 320, height: 180, transparent: true }),
+    );
+
+    await expect(
+      page
+        .getByRole("group", { name: "Background effects" })
+        .getByRole("menuitemradio", { name: "Background 3" }),
+    ).toBeVisible();
+    const [kept] = await keptImages(page);
+    expect(kept.minAlpha).toBe(255);
+  });
+});
+
+/** Two frames of one pixel, red then blue. */
+const ANIMATED_GIF = Buffer.from(
+  "R0lGODlhAQABAPEAAP8AAAAA/wAAAAAAACH/C05FVFNDQVBFMi4wAwEAAAAh+QQACgAAACwAAAAAAQABAAACAkQBACH5BAAKAAAALAAAAAABAAEAAAICTAEAOw==",
+  "base64",
+);
+
+/** A red PNG of the given size; transparent leaves its right half empty. */
+async function pngImage(
+  page: Page,
+  size: { width: number; height: number; transparent?: boolean },
+): Promise<Buffer> {
+  const dataUrl = await page.evaluate(({ width, height, transparent }) => {
+    const canvas = document.createElement("canvas");
+    canvas.width = width;
+    canvas.height = height;
+    const context = canvas.getContext("2d")!;
+    context.fillStyle = "rgb(255, 0, 0)";
+    context.fillRect(0, 0, transparent ? width / 2 : width, height);
+    return canvas.toDataURL("image/png");
+  }, size);
+  return Buffer.from(dataUrl.split(",")[1], "base64");
+}
+
+/** The images the device keeps, as it keeps them. */
+async function keptImages(
+  page: Page,
+): Promise<{ width: number; height: number; minAlpha: number }[]> {
+  return page.evaluate(async () => {
+    const db = await new Promise<IDBDatabase>((resolve, reject) => {
+      const request = indexedDB.open("element-call-background-images");
+      request.onsuccess = (): void => resolve(request.result);
+      request.onerror = (): void => reject(request.error);
+    });
+    if (!db.objectStoreNames.contains("backgrounds")) return [];
+    const kept = await new Promise<{ image: Blob }[]>((resolve, reject) => {
+      const request = db
+        .transaction("backgrounds")
+        .objectStore("backgrounds")
+        .getAll();
+      request.onsuccess = (): void => resolve(request.result);
+      request.onerror = (): void => reject(request.error);
+    });
+    db.close();
+    return Promise.all(
+      kept.map(async ({ image }) => {
+        const bitmap = await createImageBitmap(image);
+        const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+        const context = canvas.getContext("2d")!;
+        context.drawImage(bitmap, 0, 0);
+        const { data } = context.getImageData(
+          0,
+          0,
+          bitmap.width,
+          bitmap.height,
+        );
+        let minAlpha = 255;
+        for (let i = 3; i < data.length; i += 4)
+          minAlpha = Math.min(minAlpha, data[i]);
+        return { width: bitmap.width, height: bitmap.height, minAlpha };
+      }),
+    );
+  });
+}
+
+/** The bytes of the one image the device keeps. */
+async function keptBytes(page: Page): Promise<Buffer> {
+  const base64 = await page.evaluate(
+    async () =>
+      new Promise<string>((resolve, reject) => {
+        const open = indexedDB.open("element-call-background-images");
+        open.onerror = (): void => reject(open.error);
+        open.onsuccess = (): void => {
+          const all = open.result
+            .transaction("backgrounds")
+            .objectStore("backgrounds")
+            .getAll();
+          all.onerror = (): void => reject(all.error);
+          all.onsuccess = (): void => {
+            const reader = new FileReader();
+            reader.onload = (): void =>
+              resolve((reader.result as string).split(",")[1]);
+            reader.readAsDataURL((all.result[0] as { image: Blob }).image);
+          };
+        };
+      }),
+  );
+  return Buffer.from(base64, "base64");
+}
+
+const RED: Colour = [255, 0, 0];
+
+/** A solid red PNG, unlike the camera and the shipped pictures. */
+async function redImage(page: Page): Promise<Buffer> {
+  const dataUrl = await page.evaluate(() => {
+    const canvas = document.createElement("canvas");
+    canvas.width = 320;
+    canvas.height = 180;
+    const context = canvas.getContext("2d")!;
+    context.fillStyle = "rgb(255, 0, 0)";
+    context.fillRect(0, 0, canvas.width, canvas.height);
+    return canvas.toDataURL("image/png");
+  });
+  return Buffer.from(dataUrl.split(",")[1], "base64");
+}
+
+/** Adds an image from the camera menu's add tile, leaving the menu open. */
+async function addImage(
+  page: Page,
+  image: Buffer,
+  { name, type } = { name: "mine.png", type: "image/png" },
+): Promise<void> {
+  if (!(await page.getByRole("menu").isVisible()))
+    await page.getByRole("button", { name: "Camera", exact: true }).click();
+  const chooser = page.waitForEvent("filechooser");
+  await page.getByRole("menuitem", { name: "Add image" }).click();
+  await (await chooser).setFiles({ name, mimeType: type, buffer: image });
+}
+
+test.describe("joining with a background chosen", () => {
+  test("publishes no frame of the room", async ({ browser }) => {
+    // Two first builds of the pipeline, one of them held back.
+    test.setTimeout(180_000);
+    const hostContext = await browser.newContext();
+    const host = await hostContext.newPage();
+    await recordIncomingFrames(host);
+    await host.goto("/");
+    await SpaHelpers.createCall(host, "Host", "Join with a background", true);
+    await expect(host.getByTestId("incall_videomute")).toBeEnabled({
+      timeout: 10_000,
+    });
+    const inviteLink = await SpaHelpers.getCallInviteLink(host);
+    await host.keyboard.press("Escape");
+
+    const guestContext = await browser.newContext();
+    const guest = await guestContext.newPage();
+    await guest.goto(inviteLink);
+    await guest.getByTestId("joincall_displayName").fill("Guest");
+    await guest.getByTestId("joincall_joincall").click();
+    const preview = guest.locator("video").first();
+    await expect(preview).toBeVisible();
+    const camera = await cameraColour(preview);
+    await guest.getByRole("button", { name: "Camera", exact: true }).click();
+    const tile = guest.getByRole("menuitemradio", { name: "Background 1" });
+    await tile.click();
+    const picture = await averageColour(tile.locator("img"));
+    await expect
+      .poll(async () => distance(await averageColour(preview), picture), {
+        timeout: 60_000,
+      })
+      .toBeLessThan(distance(camera, picture) / 2);
+    // A pipeline built again for the call's track now takes as long as it
+    // does on the slower route. Routing bypasses the cache, so it waits.
+    let heldBack = 0;
+    await guest.route("**/*.tflite*", async (route) => {
+      heldBack += 1;
+      await new Promise((resolve) => setTimeout(resolve, 15_000));
+      await route.continue();
+    });
+    await guest.keyboard.press("Escape");
+    await guest.getByTestId("lobby_joinCall").click();
+
+    const guestTile = host
+      .getByTestId("videoTile")
+      .filter({ has: host.getByTestId("name_tag").getByText("Guest") });
+    await expect(guestTile.locator("video")).toBeVisible({ timeout: 60_000 });
+    // Visible can come before the stream is attached.
+    let trackId: string | undefined;
+    await expect
+      .poll(async () => {
+        trackId = await guestTile
+          .locator("video")
+          .evaluate(
+            (video: HTMLVideoElement) =>
+              (video.srcObject as MediaStream | null)?.getVideoTracks()[0]?.id,
+          );
+        return trackId;
+      })
+      .toBeDefined();
+    await expectNoFrameOfTheRoom(host, trackId!, 0, camera, picture);
+    // Otherwise nothing was waited for.
+    expect(heldBack).toBeGreaterThan(0);
+
+    await hostContext.close();
+    await guestContext.close();
+  });
+});
+
+test.describe("the first build", () => {
+  test("survives the camera turned off and on while it runs", async ({
+    page,
+  }) => {
+    test.setTimeout(120_000);
+    const failures: string[] = [];
+    page.on("console", (m) => {
+      if (m.text().includes("Failed to attach video processor"))
+        failures.push(m.text());
+    });
+    await page.goto("/");
+    await SpaHelpers.createCall(page, "Toggling user", "Toggle while building");
+    const preview = page.locator("video").first();
+    const camera = await cameraColour(preview);
+
+    const held = await holdBackTheModel(page);
+    await page.getByRole("button", { name: "Camera", exact: true }).click();
+    const tile = page.getByRole("menuitemradio", { name: "Background 1" });
+    await tile.click();
+    const picture = await averageColour(tile.locator("img"));
+    await page.keyboard.press("Escape");
+    // New preview tracks, each attached while the first is still building.
+    for (let i = 0; i < 2; i++) {
+      await page.getByTestId("incall_videomute").click();
+      await page.getByTestId("incall_videomute").click();
+    }
+
+    await expect
+      .poll(async () => distance(await averageColour(preview), picture), {
+        timeout: 60_000,
+      })
+      .toBeLessThan(distance(camera, picture) / 2);
+    expect(failures).toEqual([]);
+    expect(held()).toBeGreaterThan(0);
+  });
+});
+
+test.describe("turning the camera on with a background chosen", () => {
+  test("publishes no frame of the room when the camera started off", async ({
+    browser,
+  }) => {
+    test.setTimeout(120_000);
+    const { host, guest, close } = await hostAndGuest(browser);
+    const camera = await cameraColour(guest.locator("video").first());
+    await guest.getByTestId("incall_videomute").click();
+    await guest.getByTestId("lobby_joinCall").click();
+
+    const picture = await chooseBackground(guest);
+    const held = await holdBackTheModel(guest);
+    await guest.getByTestId("incall_videomute").click();
+
+    const trackId = await incomingTrackId(host);
+    await expectNoFrameOfTheRoom(host, trackId, 0, camera, picture);
+    expect(held()).toBeGreaterThan(0);
+    await close();
+  });
+
+  test("publishes no frame of the room when the camera was turned off", async ({
+    browser,
+  }) => {
+    test.setTimeout(120_000);
+    const { host, guest, close } = await hostAndGuest(browser);
+    const camera = await cameraColour(guest.locator("video").first());
+    await guest.getByTestId("lobby_joinCall").click();
+    const trackId = await incomingTrackId(host);
+    await expect
+      .poll(async () => (await framesOf(host, trackId)).length, {
+        timeout: 20_000,
+      })
+      .toBeGreaterThan(0);
+    await guest.getByTestId("incall_videomute").click();
+
+    const picture = await chooseBackground(guest);
+    const held = await holdBackTheModel(guest);
+    const before = (await framesOf(host, trackId)).length;
+    await guest.getByTestId("incall_videomute").click();
+
+    await expectNoFrameOfTheRoom(host, trackId, before, camera, picture);
+    expect(held()).toBeGreaterThan(0);
+    await close();
+  });
+});
+
+/** A host in a call, recording what it receives, and a guest in its lobby. */
+async function hostAndGuest(browser: Browser): Promise<{
+  host: Page;
+  guest: Page;
+  close: () => Promise<void>;
+}> {
+  const hostContext = await browser.newContext();
+  const host = await hostContext.newPage();
+  await recordIncomingFrames(host);
+  await host.goto("/");
+  await SpaHelpers.createCall(host, "Host", "Camera with a background", true);
+  await expect(host.getByTestId("incall_videomute")).toBeEnabled({
+    timeout: 10_000,
+  });
+  const inviteLink = await SpaHelpers.getCallInviteLink(host);
+  await host.keyboard.press("Escape");
+
+  const guestContext = await browser.newContext();
+  const guest = await guestContext.newPage();
+  await guest.goto(inviteLink);
+  await guest.getByTestId("joincall_displayName").fill("Guest");
+  await guest.getByTestId("joincall_joincall").click();
+  await expect(guest.locator("video").first()).toBeVisible();
+  return {
+    host,
+    guest,
+    close: async (): Promise<void> => {
+      await hostContext.close();
+      await guestContext.close();
+    },
+  };
+}
+
+/** Chooses the first shipped picture in the call, and answers its colour. */
+async function chooseBackground(guest: Page): Promise<Colour> {
+  // The lobby has a camera button of its own, so wait for the call's.
+  await expect(guest.getByTestId("incall_leave")).toBeVisible({
+    timeout: 30_000,
+  });
+  await expect(guest.getByTestId("incall_videomute")).toBeEnabled({
+    timeout: 10_000,
+  });
+  await guest.getByRole("button", { name: "Camera", exact: true }).click();
+  const tile = guest.getByRole("menuitemradio", { name: "Background 1" });
+  await tile.click();
+  await expect(tile).toHaveAttribute("aria-checked", "true");
+  const picture = await averageColour(tile.locator("img"));
+  await guest.keyboard.press("Escape");
+  return picture;
+}
+
+/** Makes the pipeline's first build as slow as on the slower route. */
+/** Answers how often it held the model back, which a check should see. */
+async function holdBackTheModel(page: Page): Promise<() => number> {
+  let held = 0;
+  // Routing bypasses the cache, so it waits.
+  await page.route("**/*.tflite*", async (route) => {
+    held += 1;
+    await new Promise((resolve) => setTimeout(resolve, 5_000));
+    await route.continue();
+  });
+  return () => held;
+}
+
+/** The id of the guest's camera track, as the host receives it. */
+async function incomingTrackId(host: Page): Promise<string> {
+  const guestTile = host
+    .getByTestId("videoTile")
+    .filter({ has: host.getByTestId("name_tag").getByText("Guest") });
+  await expect(guestTile.locator("video")).toBeVisible({ timeout: 60_000 });
+  // Visible can come before the stream is attached.
+  let trackId: string | undefined;
+  await expect
+    .poll(async () => {
+      trackId = await guestTile
+        .locator("video")
+        .evaluate(
+          (video: HTMLVideoElement) =>
+            (video.srcObject as MediaStream | null)?.getVideoTracks()[0]?.id,
+        );
+      return trackId;
+    })
+    .toBeDefined();
+  return trackId!;
+}
+
+/** Waits for the picture to arrive, then finds no frame of the room since. */
+async function expectNoFrameOfTheRoom(
+  host: Page,
+  trackId: string,
+  since: number,
+  camera: Colour,
+  picture: Colour,
+): Promise<void> {
+  await expect
+    .poll(
+      async () => {
+        const frames = (await framesOf(host, trackId)).slice(since);
+        // A black frame, as a track starts, is nearer the picture than the
+        // camera, but shows neither.
+        return frames.some(
+          (f) =>
+            distance(f, picture) <
+            Math.min(distance(f, camera), distance(f, [0, 0, 0])),
+        );
+      },
+      { timeout: 60_000 },
+    )
+    .toBe(true);
+  const frames = (await framesOf(host, trackId)).slice(since);
+  expect(
+    frames.filter((f) => distance(f, camera) < distance(f, picture)),
+  ).toEqual([]);
+}
+
+/**
+ * Records the mean colour of every frame of every video track the page
+ * receives, from the moment it arrives: a tile may attach it later than its
+ * first frame.
+ */
+async function recordIncomingFrames(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    const frames: Record<string, [number, number, number][]> = {};
+    (window as unknown as { receivedFrames: typeof frames }).receivedFrames =
+      frames;
+    const record = (track: MediaStreamTrack): void => {
+      if (track.kind !== "video" || frames[track.id]) return;
+      const seen: [number, number, number][] = (frames[track.id] = []);
+      const video = document.createElement("video");
+      video.muted = true;
+      video.srcObject = new MediaStream([track]);
+      const canvas = document.createElement("canvas");
+      canvas.width = canvas.height = 16;
+      const context = canvas.getContext("2d", { willReadFrequently: true })!;
+      const step = (): void => {
+        context.drawImage(video, 0, 0, 16, 16);
+        const { data } = context.getImageData(0, 0, 16, 16);
+        const sum = [0, 0, 0];
+        for (let i = 0; i < data.length; i += 4)
+          for (let c = 0; c < 3; c++) sum[c] += data[i + c];
+        seen.push(sum.map((v) => v / (data.length / 4)) as Colour);
+        video.requestVideoFrameCallback(step);
+      };
+      video.requestVideoFrameCallback(step);
+      void video.play();
+    };
+    const Connection = window.RTCPeerConnection;
+    window.RTCPeerConnection = class extends Connection {
+      public constructor(...args: ConstructorParameters<typeof Connection>) {
+        super(...args);
+        this.addEventListener("track", (e) => record(e.track));
+      }
+    };
+  });
+}
+
+async function framesOf(page: Page, trackId: string): Promise<Colour[]> {
+  return page.evaluate(
+    (id) =>
+      (
+        window as unknown as {
+          receivedFrames: Record<string, [number, number, number][]>;
+        }
+      ).receivedFrames[id] ?? [],
+    trackId,
+  );
+}

playwright/component/audio-menu.spec.ts

@@ -0,0 +1,138 @@
+/*
+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, resizeContainer, startHarness } from "./harness.ts";
+import { installFakeDevices } from "../utils/fake-devices.ts";
+
+/**
+ * The device menu with Element Call as a component in a host page, where the
+ * portalled menu must be sized against the call, not the window. Driven from
+ * the lobby: it builds the same menu, without two connections' worth of flake.
+ */
+
+// Sign-in, crypto setup and sync happen twice before anything shows.
+test.describe.configure({ timeout: 180_000 });
+
+test("sizes the device list against the call, not the window", async ({
+  page,
+}) => {
+  await installFakeDevices(page, { microphones: 20, speakers: 4 });
+  const { username, roomId } = await createUserAndRoom("menusize");
+  const panes = await startHarness(page, username, roomId);
+  const pane = panes.first();
+
+  // A short call in a much taller page.
+  const container = pane.getByTestId("call-container");
+  await resizeContainer(container, { width: 900, height: 400 });
+  await expect(pane.getByTestId("lobby_joinCall")).toBeVisible({
+    timeout: 60_000,
+  });
+
+  const list = await openDeviceList(page, pane);
+  const callHeight = (await container.boundingBox())!.height;
+  const windowHeight = page.viewportSize()!.height;
+  const listHeight = (await list.boundingBox())!.height;
+
+  expect(callHeight).toBeLessThan(windowHeight * 0.75);
+  expect(listHeight).toBeLessThanOrEqual(callHeight);
+  expect(listHeight).toBeLessThan(windowHeight * 0.6);
+});
+
+test("follows the call area when the host resizes it", async ({ page }) => {
+  await installFakeDevices(page, { microphones: 20, speakers: 4 });
+  const { username, roomId } = await createUserAndRoom("menuresize");
+  const panes = await startHarness(page, username, roomId);
+  const pane = panes.first();
+
+  const container = pane.getByTestId("call-container");
+  await resizeContainer(container, { width: 900, height: 360 });
+  await expect(pane.getByTestId("lobby_joinCall")).toBeVisible({
+    timeout: 60_000,
+  });
+
+  const list = await openDeviceList(page, pane);
+  const whenShort = (await list.boundingBox())!.height;
+
+  // The host grows the call while the menu is open.
+  await resizeContainer(container, { width: 900, height: 700 });
+  await expect
+    .poll(async () => (await list.boundingBox())!.height)
+    .toBeGreaterThan(whenShort);
+});
+
+test("keeps every device reachable in a small container", async ({ page }) => {
+  await installFakeDevices(page, { microphones: 20, speakers: 4 });
+  const { username, roomId } = await createUserAndRoom("menureach");
+  const panes = await startHarness(page, username, roomId);
+  const pane = panes.first();
+
+  const container = pane.getByTestId("call-container");
+  await resizeContainer(container, { width: 400, height: 360 });
+  await expect(pane.getByTestId("lobby_joinCall")).toBeVisible({
+    timeout: 60_000,
+  });
+
+  const list = await openDeviceList(page, pane);
+  // More devices than fit, so the list must scroll.
+  expect(await list.evaluate((el) => el.scrollHeight > el.clientHeight)).toBe(
+    true,
+  );
+
+  const last = page.getByRole("menuitemradio", { name: "Fake Microphone 20" });
+  await last.scrollIntoViewIfNeeded();
+  await expect(last).toBeInViewport();
+  // Reachable means clickable: the menu may be drawn outside the call area.
+  await last.click();
+  await expect(last).toHaveAttribute("aria-checked", "true");
+});
+
+test("tracks the focus source of its own call, not the page", async ({
+  page,
+}) => {
+  await installFakeDevices(page);
+  const { username, roomId } = await createUserAndRoom("menufocus");
+  const panes = await startHarness(page, username, roomId);
+  const pane = panes.first();
+  const other = panes.nth(1);
+
+  await expect(pane.getByTestId("lobby_joinCall")).toBeVisible({
+    timeout: 60_000,
+  });
+  await openDeviceList(page, pane);
+  const menu = page.getByRole("menu");
+
+  // Asserted on the attribute: the component build's scoped stylesheet doesn't
+  // reach the portalled menu, so its ring can't be read here.
+  await expect(menu).toHaveAttribute("data-focus-source", "pointer");
+
+  // A key pressed in the other call says nothing about this menu.
+  await other.evaluate((element) =>
+    element.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "ArrowDown", bubbles: true }),
+    ),
+  );
+  await expect(menu).toHaveAttribute("data-focus-source", "pointer");
+
+  await page.keyboard.press("ArrowDown");
+  await expect(menu).toHaveAttribute("data-focus-source", "keyboard");
+});
+
+/** Opens a component's microphone menu and returns its device list. */
+async function openDeviceList(page: Page, pane: Locator): Promise<Locator> {
+  await pane
+    .getByRole("button", { name: "Microphone" })
+    .click({ timeout: 60_000 });
+  await expect(page.getByRole("menu")).toBeVisible();
+  // The area of the menu holding the device groups, not the menu's own.
+  const list = page.locator(
+    "[role='menu'] div[role='none']:has(> [role='group'])",
+  );
+  await expect(list).toBeVisible();
+  return list;
+}

playwright/component/background-effects.spec.ts

@@ -0,0 +1,85 @@
+/*
+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, resizeContainer, startHarness } from "./harness.ts";
+import { averageColour, cameraColour, expectWearing } from "../utils/colour.ts";
+
+// Background effects need WebGL2, and headless Firefox on a CI runner has none,
+// so it rightly offers none of them.
+test.skip(
+  ({ browserName }) => browserName === "firefox",
+  "Background effects need WebGL2, which headless Firefox on CI does not have",
+);
+
+/**
+ * Background effects with Element Call as a component in a host page: the
+ * pipeline's model and WebAssembly have to load from the component's bundle,
+ * and the portalled menu has to be sized against the call, not the window.
+ * Driven from the lobby, which builds the same menu and pipeline.
+ */
+
+// Sign-in, crypto setup and sync happen twice before anything shows.
+test.describe.configure({ timeout: 180_000 });
+
+test("puts a picture on the call's preview", async ({ page }) => {
+  const { username, roomId } = await createUserAndRoom("effects");
+  const panes = await startHarness(page, username, roomId);
+  const pane = panes.first();
+  await resizeContainer(pane.getByTestId("call-container"), {
+    width: 900,
+    height: 480,
+  });
+  await expect(pane.getByTestId("lobby_joinCall")).toBeVisible({
+    timeout: 60_000,
+  });
+  const preview = pane.locator("video").first();
+  const camera = await cameraColour(preview);
+
+  const tile = await openEffect(page, pane, "Background 1");
+  const picture = await averageColour(tile.locator("img"));
+  await tile.click();
+  await expect(tile).toHaveAttribute("aria-checked", "true");
+  await expectWearing(preview, picture, camera);
+});
+
+test("keeps every effect reachable in a small container", async ({ page }) => {
+  const { username, roomId } = await createUserAndRoom("effectsreach");
+  const panes = await startHarness(page, username, roomId);
+  const pane = panes.first();
+  const container = pane.getByTestId("call-container");
+  await resizeContainer(container, { width: 400, height: 360 });
+  await expect(pane.getByTestId("lobby_joinCall")).toBeVisible({
+    timeout: 60_000,
+  });
+
+  const last = await openEffect(page, pane, "Background 2");
+  const list = page.locator("[role='menu'] div[role='none']").first();
+  expect((await list.boundingBox())!.height).toBeLessThanOrEqual(
+    (await container.boundingBox())!.height,
+  );
+  await last.scrollIntoViewIfNeeded();
+  await expect(last).toBeInViewport({ ratio: 1 });
+  await last.click();
+  await expect(last).toHaveAttribute("aria-checked", "true");
+});
+
+/** Opens a component's camera menu and returns one of its effects. */
+async function openEffect(
+  page: Page,
+  pane: Locator,
+  name: string,
+): Promise<Locator> {
+  await pane
+    .getByRole("button", { name: "Camera", exact: true })
+    .click({ timeout: 60_000 });
+  // Portalled out of the pane, so found on the page.
+  return page
+    .getByRole("group", { name: "Background effects" })
+    .getByRole("menuitemradio", { name });
+}

playwright/component/component-call.spec.ts

@@ -125,25 +125,19 @@ test("leaves the host's own page unstyled", async ({ page }) => {
     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.
+  // Compound's document styles reach the host, but it loads them itself.
   const host = await page.evaluate(() => {
-    const html = getComputedStyle(document.documentElement);
-    const body = getComputedStyle(document.body);
+    const sub = document.body.appendChild(document.createElement("sub"));
+    const verticalAlign = getComputedStyle(sub).verticalAlign;
+    sub.remove();
     return {
-      lineHeight: html.lineHeight,
-      fontFeatureSettings: body.fontFeatureSettings,
-      token: html.getPropertyValue("--cpd-color-text-primary"),
+      verticalAlign,
+      token: getComputedStyle(document.documentElement).getPropertyValue(
+        "--font-scale",
+      ),
     };
   });
-  expect(host).toEqual({
-    lineHeight: "normal",
-    fontFeatureSettings: "normal",
-    token: "",
-  });
+  expect(host).toEqual({ verticalAlign: "sub", token: "" });
 
   // While inside the container, the same rules do apply
   const root = panes.first().locator("[data-element-call-root]");

playwright/component/harness.ts

@@ -92,6 +92,12 @@ export async function expectWithin(
   outer: Locator,
 ): Promise<void> {
   await expect(inner).toBeVisible();
+  // Wait for animations to settle.
+  await inner.evaluate(async (element) => {
+    for (const animation of element.getAnimations({ subtree: true }))
+      await animation.finished;
+  });
+
   const innerBox = await inner.boundingBox();
   const outerBox = await outer.boundingBox();
   if (innerBox === null || outerBox === null)

playwright/fixtures/widget-user.ts

@@ -132,7 +132,7 @@ export const widgetTest = test.extend<MyFixtures>({
 
       await ewPage1
         .getByRole("navigation", { name: "Room list" })
-        .getByRole("button", { name: "New conversation" })
+        .getByRole("button", { name: "New", exact: true })
         .click();
 
       await ewPage1.getByRole("menuitem", { name: "Start chat" }).click();

playwright/utils/colour.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.
+*/
+
+import { expect, type Locator } from "@playwright/test";
+
+export type Colour = [number, number, number];
+
+/** The camera's colour, once the preview is showing it rather than nothing. */
+export async function cameraColour(preview: Locator): Promise<Colour> {
+  await expect
+    .poll(async () => Math.max(...(await averageColour(preview))))
+    .toBeGreaterThan(40);
+  return averageColour(preview);
+}
+
+/** The mean colour of a video's current frame or an image, drawn small. */
+export async function averageColour(element: Locator): Promise<Colour> {
+  return element.evaluate(
+    async (source: HTMLVideoElement | HTMLImageElement) => {
+      if (source instanceof HTMLImageElement) await source.decode();
+      const canvas = document.createElement("canvas");
+      canvas.width = canvas.height = 32;
+      const context = canvas.getContext("2d")!;
+      context.drawImage(source, 0, 0, 32, 32);
+      const { data } = context.getImageData(0, 0, 32, 32);
+      const sum = [0, 0, 0];
+      for (let i = 0; i < data.length; i += 4)
+        for (let c = 0; c < 3; c++) sum[c] += data[i + c];
+      const pixels = data.length / 4;
+      return sum.map((s) => s / pixels) as Colour;
+    },
+  );
+}
+
+export function distance(a: Colour, b: Colour): number {
+  return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+}
+
+/** Waits until a preview shows a picture rather than the camera. */
+export async function expectWearing(
+  preview: Locator,
+  picture: Colour,
+  camera: Colour,
+): Promise<void> {
+  // Long enough for the first effect of a session to be built.
+  await expect
+    .poll(async () => distance(await averageColour(preview), picture), {
+      timeout: 60_000,
+    })
+    .toBeLessThan(distance(camera, picture) / 2);
+}

playwright/utils/fake-devices.ts

@@ -0,0 +1,85 @@
+/*
+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 Page } from "@playwright/test";
+
+/**
+ * Adds synthetic devices beside the browser's one fake microphone and speaker,
+ * so the menu has a choice to show. They share one capture and `setSinkId` is
+ * accepted but not honoured: routing still needs hardware and a manual check.
+ * Call before the page navigates.
+ */
+export async function installFakeDevices(
+  page: Page,
+  { microphones = 2, speakers = 2 } = {},
+): Promise<void> {
+  await page.addInitScript(
+    ({ microphones, speakers }) => {
+      const synthetic = (
+        kind: MediaDeviceKind,
+        count: number,
+        name: string,
+      ): MediaDeviceInfo[] =>
+        Array.from({ length: count }, (_, i) => {
+          const info = {
+            deviceId: `${kind}-${i + 1}`,
+            groupId: `${kind}-group-${i + 1}`,
+            kind,
+            label: `${name} ${i + 1}`,
+          };
+          return { ...info, toJSON: () => info } as MediaDeviceInfo;
+        });
+      const ids = new Set(
+        [
+          ...synthetic("audioinput", microphones, ""),
+          ...synthetic("audiooutput", speakers, ""),
+        ].map((d) => d.deviceId),
+      );
+
+      const devices = navigator.mediaDevices;
+      const enumerate = devices.enumerateDevices.bind(devices);
+      devices.enumerateDevices = async (): Promise<MediaDeviceInfo[]> => [
+        ...(await enumerate()),
+        ...synthetic("audioinput", microphones, "Fake Microphone"),
+        ...synthetic("audiooutput", speakers, "Fake Speaker"),
+      ];
+
+      // Our ids name no hardware, so drop the exact-device constraint.
+      const getUserMedia = devices.getUserMedia.bind(devices);
+      devices.getUserMedia = async (
+        constraints?: MediaStreamConstraints,
+      ): Promise<MediaStream> => {
+        const audio = constraints?.audio;
+        if (typeof audio === "object") {
+          const requested = audio.deviceId;
+          const id =
+            typeof requested === "object" && requested !== null
+              ? ((requested as ConstrainDOMStringParameters).exact as string)
+              : (requested as string | undefined);
+          if (id !== undefined && ids.has(id))
+            return getUserMedia({ ...constraints, audio: true });
+        }
+        return getUserMedia(constraints);
+      };
+
+      // Accept routing to our ids on both media elements and the AudioContext,
+      // which the app also routes.
+      for (const proto of [
+        HTMLMediaElement.prototype,
+        AudioContext.prototype,
+      ]) {
+        const sink = proto as { setSinkId?: (id: string) => Promise<void> };
+        const setSinkId = sink.setSinkId;
+        if (setSinkId === undefined) continue;
+        sink.setSinkId = async function (id: string): Promise<void> {
+          if (!ids.has(id)) await setSinkId.call(this, id);
+        };
+      }
+    },
+    { microphones, speakers },
+  );
+}

playwright/widget/background-effects.spec.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 { expect, test } from "@playwright/test";
+
+import { widgetTest } from "../fixtures/widget-user.ts";
+import { TestHelpers } from "./test-helpers.ts";
+import { averageColour, cameraColour, expectWearing } from "../utils/colour.ts";
+
+// Background effects need WebGL2, and headless Firefox on a CI runner has none,
+// so it rightly offers none of them.
+test.skip(
+  ({ browserName }) => browserName === "firefox",
+  "Background effects need WebGL2, which headless Firefox on CI does not have",
+);
+
+widgetTest(
+  "puts a picture on the preview inside Element Web",
+  async ({ asWidget }) => {
+    test.slow();
+    const { brooks } = asWidget;
+    await TestHelpers.startCallInCurrentRoom(brooks.page, false);
+    const frame = brooks.page
+      .locator('iframe[title="Element Call"]')
+      .contentFrame();
+    await expect(frame.getByTestId("lobby_joinCall")).toBeVisible();
+    const preview = frame.locator("video").first();
+    const camera = await cameraColour(preview);
+
+    await frame.getByRole("button", { name: "Camera", exact: true }).click();
+    const tile = frame
+      .getByRole("group", { name: "Background effects" })
+      .getByRole("menuitemradio", { name: "Background 1" });
+    const picture = await averageColour(tile.locator("img"));
+    await tile.click();
+    await expect(tile).toHaveAttribute("aria-checked", "true");
+    await expectWearing(preview, picture, camera);
+  },
+);

playwright/widget/test-helpers.ts

@@ -223,7 +223,7 @@ export class TestHelpers {
 
     await page
       .getByRole("navigation", { name: "Room list" })
-      .getByRole("button", { name: "New conversation" })
+      .getByRole("button", { name: "New", exact: true })
       .click();
 
     await page.getByRole("menuitem", { name: "New Room" }).click({

pnpm-lock.yaml

@@ -131,11 +131,11 @@ importers:
         specifier: ^10.2.11
         version: 10.3.1(react@19.2.8)
       '@vector-im/compound-design-tokens':
-        specifier: ^11.0.0
-        version: 11.0.0(@types/react@19.2.18)(react@19.2.8)
+        specifier: ^11.1.0
+        version: 11.1.0(@types/react@19.2.18)(react@19.2.8)
       '@vector-im/compound-web':
-        specifier: ^10.0.0
-        version: 10.0.1(@fontsource/inconsolata@5.3.0)(@fontsource/inter@5.3.0)(@types/react-dom@19.2.5(@types/react@19.2.18))(@types/react@19.2.18)(@vector-im/compound-design-tokens@11.0.0(@types/react@19.2.18)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+        specifier: ^10.3.0
+        version: 10.3.0(@fontsource/inconsolata@5.3.0)(@fontsource/inter@5.3.0)(@types/react-dom@19.2.5(@types/react@19.2.18))(@types/react@19.2.18)(@vector-im/compound-design-tokens@11.1.0(@types/react@19.2.18)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
       '@vitejs/plugin-react':
         specifier: ^6.0.2
         version: 6.1.1(@rolldown/plugin-babel@0.2.3(@babel/core@7.29.7(supports-color@7.2.0))(@babel/runtime@8.0.0)(rolldown@1.2.7)(vite@8.2.2(@types/node@24.13.3)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.103.1)(terser@5.46.1)(yaml@2.9.0)))(babel-plugin-react-compiler@1.0.0)(vite@8.2.2(@types/node@24.13.3)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.103.1)(terser@5.46.1)(yaml@2.9.0))
@@ -163,6 +163,9 @@ importers:
       eslint-plugin-storybook:
         specifier: ^10.3.6
         version: 10.6.0(eslint@8.57.1(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.9.3)
+      fake-indexeddb:
+        specifier: ^6.2.5
+        version: 6.2.5
       fetch-mock:
         specifier: 11.1.5
         version: 11.1.5(node-fetch@2.7.0)
@@ -192,7 +195,7 @@ importers:
         version: 1.9.2
       matrix-js-sdk:
         specifier: github:matrix-org/matrix-js-sdk#develop
-        version: https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/24929be0e741be6a5d0a7226f1c682e245263b8a
+        version: https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/fa4772a4ddd335a5a8bfbf8bb21df49b70f7a999
       matrix-widget-api:
         specifier: ^1.18.0
         version: 1.19.0
@@ -202,9 +205,6 @@ importers:
       normalize.css:
         specifier: ^8.0.1
         version: 8.0.1
-      observable-hooks:
-        specifier: ^4.2.3
-        version: 4.2.4(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(rxjs@7.8.2)
       oxfmt:
         specifier: ^0.66.0
         version: 0.66.0
@@ -271,9 +271,6 @@ importers:
       vite:
         specifier: ^8.0.0
         version: 8.2.2(@types/node@24.13.3)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.103.1)(terser@5.46.1)(yaml@2.9.0)
-      vite-plugin-generate-file:
-        specifier: ^0.3.0
-        version: 0.3.1
       vite-plugin-html:
         specifier: ^3.2.2
         version: 3.2.2(vite@8.2.2(@types/node@24.13.3)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.103.1)(terser@5.46.1)(yaml@2.9.0))
@@ -1197,8 +1194,8 @@ packages:
       '@types/dom-mediacapture-transform': ^0.1.9
       livekit-client: ^1.12.0 || ^2.1.0
 
-  '@matrix-org/matrix-sdk-crypto-wasm@18.5.0':
-    resolution: {integrity: sha512-E826Hy1rG26LanPjtSsOiVRcVoHfSgPgj2r2Xsb5RPScpaKi9XJADQ0u3dNjRCitZPX4oyLNl1FDd5AfDlmIwQ==}
+  '@matrix-org/matrix-sdk-crypto-wasm@18.9.0':
+    resolution: {integrity: sha512-NtLzNDTEfNASBjNCTGZHuk7N0jrQhS6Zx2CM857rCHZYYh/rpbKGQNrJ7azktm4S1P5Jy3WU3nwJTGohGw26qQ==}
     engines: {node: '>= 18'}
 
   '@mdx-js/react@3.1.1':
@@ -3229,8 +3226,8 @@ packages:
     peerDependencies:
       react: '>= 16.8.0'
 
-  '@vector-im/compound-design-tokens@11.0.0':
-    resolution: {integrity: sha512-pWz0Q67Xbo8gwzaTeFbTTcM6i29ju6PR7SqyuExr2nIV3j9K785cOInft8FA2CM7PEapkr6TRtJKR/4xtWh2RA==}
+  '@vector-im/compound-design-tokens@11.1.0':
+    resolution: {integrity: sha512-vkMcy/G5VBlVle8umQNpctKHqZITS8XOQprsgcbSGRmwW080Z+TXV/vPsEXhgq8JKdxURkLhua0zQUufCeo46A==}
     peerDependencies:
       '@adobe/leonardo-contrast-colors': ^1.0.0
       '@types/react': '*'
@@ -3246,13 +3243,13 @@ packages:
       react:
         optional: true
 
-  '@vector-im/compound-web@10.0.1':
-    resolution: {integrity: sha512-CT3aGMalPSf53o3JUbBF7EA10Rfp+auftIuBwOUSna+hfZ/zPxGLTFcuCuOJ7L8hrzijM+V4I8L0PUkfyOczpg==}
+  '@vector-im/compound-web@10.3.0':
+    resolution: {integrity: sha512-tce5hsNpdvYXfB5nYQgTK7WjTDqjdxpV1BeGsw67gYAWSFKJr9p6X5gzE79o+Tp/q5uykLuO4ozTBdjLsmUWMw==}
     peerDependencies:
       '@fontsource/inconsolata': ^5
       '@fontsource/inter': ^5
       '@types/react': '*'
-      '@vector-im/compound-design-tokens': '>=1.6.1 <11.0.0'
+      '@vector-im/compound-design-tokens': '>=1.6.1 <12.0.0'
       react: ^18 || ^19.0.0
     peerDependenciesMeta:
       '@types/react':
@@ -3662,8 +3659,8 @@ packages:
   constants-browserify@1.0.0:
     resolution: {integrity: sha512-xFxOwqIzR/e1k1gLiWEophSCMqXcwVHIH7akf7b/vxcUeGunlj3hvZaaqxwHsTgn+IndtkQJgSztIDWeumWJDQ==}
 
-  content-type@3.0.0:
-    resolution: {integrity: sha512-AIi5H6p0xk5uknXcN3/rmhP8jgp69OfSe/JuKiQAFprJ7UGw7mwj7m4XcmDzlrnJDG+cGpphAINGdU3g3g7kDw==}
+  content-type@3.1.1:
+    resolution: {integrity: sha512-GW4qUsfFo59d0HbUibDlWv5wPz+vAAcaTWbKIuKCf0JkC7wWkSyf8f13IpXn5JkeMlB2P8iTSSIjwXljorg2vA==}
     engines: {node: '>=22'}
 
   convert-source-map@2.0.0:
@@ -4004,6 +4001,10 @@ packages:
     resolution: {integrity: sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==}
     engines: {node: '>=12.0.0'}
 
+  fake-indexeddb@6.2.5:
+    resolution: {integrity: sha512-CGnyrvbhPlWYMngksqrSSUT1BAVP49dZocrHuK0SvtR0D5TMs5wP0o3j7jexDJW01KSadjBp1M/71o/KR3nD1w==}
+    engines: {node: '>=18'}
+
   fast-deep-equal@3.1.3:
     resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
 
@@ -4468,10 +4469,6 @@ packages:
   js-tokens@4.0.0:
     resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
 
-  js-yaml@4.3.0:
-    resolution: {integrity: sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==}
-    hasBin: true
-
   js-yaml@4.3.1:
     resolution: {integrity: sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==}
     hasBin: true
@@ -4683,9 +4680,9 @@ packages:
   matrix-events-sdk@0.0.1:
     resolution: {integrity: sha512-1QEOsXO+bhyCroIe2/A5OwaxHvBm7EsSQ46DEDn8RBIfQwN5HWBpFvyWWR4QY0KHPPnnJdI99wgRiAl7Ad5qaA==}
 
-  matrix-js-sdk@https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/24929be0e741be6a5d0a7226f1c682e245263b8a:
-    resolution: {gitHosted: true, integrity: sha512-0EGwbXzvG88sBOxq4ZlCRwT4VpQj2xkizfyy0A3bTSK0ysb6/gXJ/o1WPFoqCjRGMDgPq4gAsk92xGtHA7EhPg==, tarball: https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/24929be0e741be6a5d0a7226f1c682e245263b8a}
-    version: 42.2.0
+  matrix-js-sdk@https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/fa4772a4ddd335a5a8bfbf8bb21df49b70f7a999:
+    resolution: {gitHosted: true, integrity: sha512-qF8++74MX36KS1KEw6Lc8HHXgZ6nHD1oUU4yBZUj5vVPvZTIspk1lOGztkFmizE5vmLAHd5tdadL9Xu1Asy4bA==, tarball: https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/fa4772a4ddd335a5a8bfbf8bb21df49b70f7a999}
+    version: 42.3.0
     engines: {node: '>=22.0.0'}
 
   matrix-widget-api@1.19.0:
@@ -4706,14 +4703,6 @@ packages:
     resolution: {integrity: sha512-115fLhvZVqWwHPbClyntxEVfVDfl9DLLTuJvq3g2O/Oxi8AiNouAHvDSzHS0viUJc+V5vm3eq91Xwqn9dp4jRA==}
     hasBin: true
 
-  mime-db@1.52.0:
-    resolution: {integrity: sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==}
-    engines: {node: '>= 0.6'}
-
-  mime-types@2.1.35:
-    resolution: {integrity: sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==}
-    engines: {node: '>= 0.6'}
-
   mimic-function@5.0.1:
     resolution: {integrity: sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==}
     engines: {node: '>=18'}
@@ -4816,13 +4805,6 @@ packages:
     resolution: {integrity: sha512-nK28WOo+QIjBkDduTINE4JkF/UJJKyf2EJxvJKfblDpyg0Q+pkOHNTL0Qwy6NP6FhE/EnzV73BxxqcJaXY9anw==}
     engines: {node: '>= 0.4'}
 
-  observable-hooks@4.2.4:
-    resolution: {integrity: sha512-FdTQgyw1h5bG/QHCBIqctdBSnv9VARJCEilgpV6L2qlw1yeLqFIwPm4U15dMtl5kDmNN0hSt+Nl6iYbLFwEcQA==}
-    peerDependencies:
-      react: '>=16.8.0'
-      react-dom: '>=16.8.0'
-      rxjs: '>=6.0.0'
-
   obug@2.1.4:
     resolution: {integrity: sha512-4a+OsYv9UktOJKE+l1A4OufDgdRF9PifWj+tJnHURo/P+WOxpG4GzUFL9qCalmWauao6ogiG+QvnCovwPoyAWA==}
     engines: {node: '>=12.20.0'}
@@ -4905,8 +4887,8 @@ packages:
     resolution: {integrity: sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==}
     engines: {node: '>=10'}
 
-  p-retry@8.0.0:
-    resolution: {integrity: sha512-kFVqH1HxOHp8LupNsOys7bSV09VYTRLxarH/mokO4Rqhk6wGi70E0jh4VzvVGXfEVNggHoHLAMWsQqHyU1Ey9A==}
+  p-retry@8.0.1:
+    resolution: {integrity: sha512-NAigyu8hfvJe7MsS18mnc4is0MZtau3QMdBklaJKK23oBQb6occO3UPM3vHmTckW8KhfyjMZaUOqdTFEYliHgg==}
     engines: {node: '>=22'}
 
   p-try@2.2.0:
@@ -5914,9 +5896,6 @@ packages:
       react: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
       react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
 
-  vite-plugin-generate-file@0.3.1:
-    resolution: {integrity: sha512-tiA3gkPM21MS2+RyqsBMT33GSlM9LM1TJjf6vGvV/e/ml3e3vTKfuH3l2N0NpUgcayvj1fXnmlo5YBuahA6bsg==}
-
   vite-plugin-html@3.2.2:
     resolution: {integrity: sha512-vb9C9kcdzcIo/Oc3CLZVS03dL5pDlOFuhGlZYDCJ840BhWl/0nGeZWf3Qy7NlOayscY4Cm/QRgULCQkEZige5Q==}
     peerDependencies:
@@ -7111,7 +7090,7 @@ snapshots:
       '@types/dom-mediacapture-transform': 0.1.11
       livekit-client: 2.22.3(@types/dom-mediacapture-record@1.0.22)
 
-  '@matrix-org/matrix-sdk-crypto-wasm@18.5.0': {}
+  '@matrix-org/matrix-sdk-crypto-wasm@18.9.0': {}
 
   '@mdx-js/react@3.1.1(@types/react@19.2.18)(react@19.2.8)':
     dependencies:
@@ -8695,12 +8674,12 @@ snapshots:
       '@use-gesture/core': 10.3.1
       react: 19.2.8
 
-  '@vector-im/compound-design-tokens@11.0.0(@types/react@19.2.18)(react@19.2.8)':
+  '@vector-im/compound-design-tokens@11.1.0(@types/react@19.2.18)(react@19.2.8)':
     optionalDependencies:
       '@types/react': 19.2.18
       react: 19.2.8
 
-  '@vector-im/compound-web@10.0.1(@fontsource/inconsolata@5.3.0)(@fontsource/inter@5.3.0)(@types/react-dom@19.2.5(@types/react@19.2.18))(@types/react@19.2.18)(@vector-im/compound-design-tokens@11.0.0(@types/react@19.2.18)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)':
+  '@vector-im/compound-web@10.3.0(@fontsource/inconsolata@5.3.0)(@fontsource/inter@5.3.0)(@types/react-dom@19.2.5(@types/react@19.2.18))(@types/react@19.2.18)(@vector-im/compound-design-tokens@11.1.0(@types/react@19.2.18)(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)':
     dependencies:
       '@floating-ui/react': 0.27.20(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
       '@floating-ui/react-dom': 2.1.9(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
@@ -8712,7 +8691,7 @@ snapshots:
       '@radix-ui/react-progress': 1.1.16(@types/react-dom@19.2.5(@types/react@19.2.18))(@types/react@19.2.18)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
       '@radix-ui/react-separator': 1.1.15(@types/react-dom@19.2.5(@types/react@19.2.18))(@types/react@19.2.18)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
       '@radix-ui/react-slot': 1.3.3(@types/react@19.2.18)(react@19.2.8)
-      '@vector-im/compound-design-tokens': 11.0.0(@types/react@19.2.18)(react@19.2.8)
+      '@vector-im/compound-design-tokens': 11.1.0(@types/react@19.2.18)(react@19.2.8)
       classnames: 2.5.1
       react: 19.2.8
       vaul: 1.1.2(@types/react-dom@19.2.5(@types/react@19.2.18))(@types/react@19.2.18)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
@@ -9173,7 +9152,7 @@ snapshots:
 
   constants-browserify@1.0.0: {}
 
-  content-type@3.0.0: {}
+  content-type@3.1.1: {}
 
   convert-source-map@2.0.0: {}
 
@@ -9576,6 +9555,8 @@ snapshots:
 
   expect-type@1.4.0: {}
 
+  fake-indexeddb@6.2.5: {}
+
   fast-deep-equal@3.1.3: {}
 
   fast-glob@3.3.3:
@@ -10044,10 +10025,6 @@ snapshots:
 
   js-tokens@4.0.0: {}
 
-  js-yaml@4.3.0:
-    dependencies:
-      argparse: 2.0.1
-
   js-yaml@4.3.1:
     dependencies:
       argparse: 2.0.1
@@ -10259,17 +10236,17 @@ snapshots:
 
   matrix-events-sdk@0.0.1: {}
 
-  matrix-js-sdk@https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/24929be0e741be6a5d0a7226f1c682e245263b8a:
+  matrix-js-sdk@https://codeload.github.com/matrix-org/matrix-js-sdk/tar.gz/fa4772a4ddd335a5a8bfbf8bb21df49b70f7a999:
     dependencies:
       '@babel/runtime': 8.0.0
-      '@matrix-org/matrix-sdk-crypto-wasm': 18.5.0
+      '@matrix-org/matrix-sdk-crypto-wasm': 18.9.0
       another-json: 0.2.0
       bs58: 6.0.0
-      content-type: 3.0.0
+      content-type: 3.1.1
       loglevel: 1.9.2
       matrix-events-sdk: 0.0.1
       matrix-widget-api: 1.19.0
-      p-retry: 8.0.0
+      p-retry: 8.0.1
       sdp-transform: 3.0.0
       unhomoglyph: 1.0.6
 
@@ -10296,12 +10273,6 @@ snapshots:
       bn.js: 4.12.3
       brorand: 1.1.0
 
-  mime-db@1.52.0: {}
-
-  mime-types@2.1.35:
-    dependencies:
-      mime-db: 1.52.0
-
   mimic-function@5.0.1: {}
 
   min-indent@1.0.1: {}
@@ -10410,12 +10381,6 @@ snapshots:
       has-symbols: 1.1.0
       object-keys: 1.1.1
 
-  observable-hooks@4.2.4(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(rxjs@7.8.2):
-    dependencies:
-      react: 19.2.8
-      react-dom: 19.2.8(react@19.2.8)
-      rxjs: 7.8.2
-
   obug@2.1.4: {}
 
   once@1.4.0:
@@ -10600,7 +10565,7 @@ snapshots:
     dependencies:
       p-limit: 3.1.0
 
-  p-retry@8.0.0:
+  p-retry@8.0.1:
     dependencies:
       is-network-error: 1.3.2
 
@@ -11668,13 +11633,6 @@ snapshots:
       - '@types/react'
       - '@types/react-dom'
 
-  vite-plugin-generate-file@0.3.1:
-    dependencies:
-      ejs: 3.1.10
-      js-yaml: 4.3.0
-      mime-types: 2.1.35
-      picocolors: 1.1.1
-
   vite-plugin-html@3.2.2(vite@8.2.2(@types/node@24.13.3)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.103.1)(terser@5.46.1)(yaml@2.9.0)):
     dependencies:
       '@rollup/pluginutils': 4.2.1

scripts/check-component-externals.mjs

@@ -9,9 +9,11 @@ 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
+ * A host application already has React, the Matrix SDK, LiveKit and Compound,
+ * and a second copy of any of them is worse than dead weight: React would hold
+ * two sets of hooks, the Matrix client would run two sync loops, and a second
+ * Compound would style the tooltips it floats into the host's body with class
+ * names the host's stylesheet does not know. 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
@@ -33,6 +35,9 @@ import { loadConfigFromFile } from "vite";
 
 const CONFIG = "vite-component.config.ts";
 const SOURCES = ["src", "component"];
+// The development harness is a host, not part of the component: it is the
+// one that imports what a host supplies (Compound's stylesheets, say).
+const EXCLUDED = ["component/dev"];
 
 /** The packages whose duplication would break a host, rather than merely enlarge it. */
 const MUST_BE_EXTERNAL = [
@@ -40,6 +45,8 @@ const MUST_BE_EXTERNAL = [
   "react-dom",
   "matrix-js-sdk",
   "livekit-client",
+  "@vector-im/compound-web",
+  "@vector-im/compound-design-tokens",
 ];
 
 const isTestFile = (name) =>
@@ -49,6 +56,7 @@ const isTestFile = (name) =>
 async function* sourceFiles(dir) {
   for (const entry of await readdir(dir, { withFileTypes: true })) {
     const path = join(dir, entry.name);
+    if (EXCLUDED.includes(path)) continue;
     if (entry.isDirectory()) yield* sourceFiles(path);
     else if (/\.(ts|tsx)$/.test(entry.name) && !isTestFile(entry.name))
       yield path;

scripts/fetchdep.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+
+# Clones the branch of a dependency's repository that has the same name as
+# the pull request branch under test, so a change spanning both repositories
+# can be tested before either side is merged. Inspired by scripts/fetchdep.sh 
+# element-web.
+#
+# Usage: scripts/fetchdep.sh <org> <repo> [ref]
+#
+# The clone lands in ./<repo>. When the pull request comes from a fork and
+# PR_HEAD_REPO_OWNER was set, the fork's own copy of the repository is tried
+# before <org>'s. Exits 0 when a branch was cloned and 1 when there is none,
+# so the caller can keep the locked version in that case. Without a ref,
+# nothing is closed outside a pull request.
+
+set -eu
+
+org=$1
+repo=$2
+ref=${3:-}
+
+rm -rf "$repo"
+
+# If a ref was passed, try to clone it or die.
+if [ -n "$ref" ]; then
+    echo "fetchdep.sh: Using $org/$repo at $ref"
+    git clone --depth 1 "https://github.com/$org/$repo.git" "$repo"
+    git -C "$repo" fetch --depth 1 origin "$ref"
+    git -C "$repo" -c advice.detachedHead=false checkout FETCH_HEAD
+    git -C "$repo" log -1
+    exit 0
+fi
+
+# Otherwise ensure that we're on a pull request.
+head_ref=${GITHUB_HEAD_REF:-}
+if [ -z "$head_ref" ]; then
+    echo "fetchdep.sh: Not a pull request, nothing to match"
+    exit 1
+fi
+
+# Bots name their branches the same way in every repository, so a match on
+# one of theirs would be a coincidence rather than a paired change.
+case "$head_ref" in
+    renovate/* | dependabot/*)
+        echo "fetchdep.sh: Not matching bot branch $head_ref"
+        exit 1
+        ;;
+esac
+
+# Clones a branch if it exists and ends the script on success.
+clone() {
+    local try_org=$1
+    local branch=$2
+    echo "fetchdep.sh: Trying to use $try_org/$repo#$branch"
+    # Disable auth prompts: https://serverfault.com/a/665959
+    if GIT_TERMINAL_PROMPT=0 git clone "https://github.com/$try_org/$repo.git" "$repo" --branch "$branch" --depth 1; then
+        git -C "$repo" log -1
+        # Surface the match on the workflow run summary.
+        echo "::notice title=Matched $repo branch::Using $try_org/$repo#$branch at $(git -C "$repo" rev-parse HEAD)"
+        exit 0
+    fi
+}
+
+# Try cloning from the fork, then from the org.
+head_owner=${PR_HEAD_REPO_OWNER:-}
+if [ -n "$head_owner" ] && [ "$head_owner" != "${GITHUB_REPOSITORY_OWNER:-}" ]; then
+    clone "$head_owner" "$head_ref"
+fi
+clone "$org" "$head_ref"
+
+# Nothing worked. Die.
+echo "fetchdep.sh: No branch named $head_ref in $org/$repo"
+exit 1

scripts/layered.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+
+# Installs dependencies, then swaps matrix-js-sdk for a branch of the same
+# name as the pull request branch under test if one exists. This is what
+# lets CI test an Element Call branch together with a matrix-js-sdk branch
+# before either is merged. Inspired by scripts/layered.sh in element-web.
+#
+# Usage: scripts/layered.sh [pnpm install flags]
+#
+# The layering is only performed when package.json uses the develop branch of
+# matrix-js-sdk and the run is for a pull request whose branch has a matrix-js-sdk
+# counterpart. Otherwise the dependency is left as pnpm-lock.yaml pins it.
+#
+# The matrix-js-sdk checkout is nested inside this directory because some CI
+# systems do not allow moving above the primary checkout. It is git-ignored.
+#
+# Set JS_SDK_GITHUB_BASE_REF to a ref to use that exact ref of matrix-js-sdk
+# instead of looking for a matching branch.
+#
+# This script is only meant to be used in CI. For local development use
+# see docs/linking.md.
+
+set -ex
+
+# Paths below are relative to the repository root.
+cd "$(dirname "$0")/.."
+
+pnpm install --frozen-lockfile "$@"
+
+js_sdk_dep=$(jq -r '.devDependencies["matrix-js-sdk"]' < package.json)
+
+# Only layer when package.json follows the branch head rather than pinning a
+# release, so a release build keeps its pinned version.
+if [ "$js_sdk_dep" != "github:matrix-org/matrix-js-sdk#develop" ]; then
+    echo "layered.sh: Skipping matrix-js-sdk fetch and install as package.json pins $js_sdk_dep"
+    exit 0
+fi
+
+if ! scripts/fetchdep.sh matrix-org matrix-js-sdk "${JS_SDK_GITHUB_BASE_REF:-}"; then
+    echo "layered.sh: No matching matrix-js-sdk branch, keeping the locked version"
+    exit 0
+fi
+
+# matrix-js-sdk pins its pnpm version in `devEngines` only. Under corepack,
+# pnpm does not switch versions on its own and corepack, finding no
+# `packageManager` field there, would walk up to this project's and use
+# ours. Pinning it in the clone makes every pnpm invocation inside that
+# directory, including the `prepare` script run by pack, use the right one.
+js_sdk_pnpm="pnpm@$(jq -r '.devEngines.packageManager.version' < matrix-js-sdk/package.json)"
+jq --arg pm "$js_sdk_pnpm" '.packageManager = $pm' matrix-js-sdk/package.json > matrix-js-sdk/package.json.tmp
+mv matrix-js-sdk/package.json.tmp matrix-js-sdk/package.json
+export COREPACK_ENABLE_DOWNLOAD_PROMPT=0
+
+# Install matrix-js-sdk's build dependencies. `prepare` runs on pack below,
+# so it is skipped here.
+(cd matrix-js-sdk && pnpm install --frozen-lockfile --ignore-scripts)
+
+# Rather than `pnpm link`, build matrix-js-sdk into a tarball and install
+# that. This better reflects a clean install: dependencies may be hoisted
+# and shared, and there is no tsconfig.json to pick up sources from.
+(cd matrix-js-sdk && pnpm pack --out matrix-js-sdk.tgz)
+pnpm install "$(pwd)/matrix-js-sdk/matrix-js-sdk.tgz" "$@"

src/App.tsx

@@ -35,7 +35,7 @@ import { ErrorPage, LoadingPage } from "./FullScreenView";
 import { Initializer } from "./initializer";
 import { type WidgetHelpers } from "./widget";
 import { useTheme } from "./useTheme";
-import { ProcessorProvider } from "./livekit/TrackProcessorContext";
+import { BackgroundEffectsProvider } from "./livekit/BackgroundEffectsContext";
 import { type AppViewModel } from "./state/AppViewModel";
 import { MediaDevicesContext } from "./MediaDevicesContext";
 import {
@@ -148,7 +148,7 @@ export const App: FC<Props> = ({ vm, widget }) => {
     loaded && clientReady ? (
       <ClientProvider client={widgetClient}>
         <MediaDevicesContext value={vm.mediaDevices}>
-          <ProcessorProvider>
+          <BackgroundEffectsProvider effects={vm.backgroundEffects}>
             <Sentry.ErrorBoundary
               fallback={(error) => <ErrorPage error={error} />}
             >
@@ -159,7 +159,7 @@ export const App: FC<Props> = ({ vm, widget }) => {
                 <SentryRoute path="*" element={<RoomPage />} />
               </Routes>
             </Sentry.ErrorBoundary>
-          </ProcessorProvider>
+          </BackgroundEffectsProvider>
         </MediaDevicesContext>
       </ClientProvider>
     ) : (

src/MediaDevicesContext.ts

@@ -6,9 +6,9 @@ Please see LICENSE in the repository root for full details.
 */
 
 import { createContext, use, useMemo } from "react";
-import { useObservableEagerState } from "observable-hooks";
 
 import { type MediaDevices } from "./state/MediaDevices";
+import { useBehavior } from "./useBehavior";
 
 export const MediaDevicesContext = createContext<MediaDevices | undefined>(
   undefined,
@@ -35,7 +35,7 @@ export const useEarpieceAudioConfig = (): {
   volume: number;
 } => {
   const devices = useMediaDevices();
-  const audioOutput = useObservableEagerState(devices.audioOutput.selected$);
+  const audioOutput = useBehavior(devices.audioOutput.selected$);
   const isVirtualEarpiece = audioOutput?.virtualEarpiece ?? false;
   return {
     // We use only the right speaker (pan = 1) for the earpiece.

src/UrlConfiguration.ts

@@ -0,0 +1,242 @@
+/*
+Copyright 2022-2024 New Vector Ltd.
+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 Element Call can be told to behave, and what each intent means.
+ *
+ * Kept apart from {@link UrlParams} on purpose: everything here is constants,
+ * types and one function of them, so that a host of the component can import
+ * these — the enums it needs as values, the defaults an intent implies — without
+ * loading Element Call itself. UrlParams, which reads them from a URL, needs
+ * the router, the config and the rest of the app; this module must not.
+ * `component/api.ts` is built from it as an entry point of its own.
+ */
+
+import {
+  type RTCCallIntent,
+  type RTCNotificationType,
+} from "matrix-js-sdk/lib/matrixrtc";
+
+import { platform } from "./Platform";
+
+export enum UserIntent {
+  StartNewCall = "start_call",
+  JoinExistingCall = "join_existing",
+  StartNewCallVoice = "start_call_voice",
+  JoinExistingCallVoice = "join_existing_voice",
+  StartNewCallDM = "start_call_dm",
+  StartNewCallDMVoice = "start_call_dm_voice",
+  JoinExistingCallDM = "join_existing_dm",
+  JoinExistingCallDMVoice = "join_existing_dm_voice",
+  Unknown = "unknown",
+}
+
+export enum HeaderStyle {
+  None = "none",
+  Standard = "standard",
+  AppBar = "app_bar",
+}
+
+export enum BackgroundStyle {
+  Solid = "solid",
+  Gradient = "gradient",
+}
+
+/**
+ * The configuration for the app, which can be set via URL parameters.
+ * Those property are different to the UrlProperties, since they are all optional
+ * and configure the behavior of the app. Their value is the same if EC is used in
+ * the same context but with different accounts/users.
+ *
+ * Their defaults can be controlled by the `intent` property.
+ */
+export interface UrlConfiguration {
+  /**
+   * Whether the app should keep the user confined to the current call/room.
+   */
+  confineToRoom: boolean;
+  /**
+   * Whether the app should pause before joining the call until it sees an
+   * io.element.join widget action, allowing it to be preloaded.
+   */
+  preload: boolean;
+  /**
+   * The style of headers to show. "standard" is the default arrangement, "none"
+   * hides the header entirely, and "app_bar" produces a header with a back
+   * button like you might see in mobile apps. The callback for the back button
+   * is window.controls.onBackButtonPressed.
+   */
+  header: HeaderStyle;
+  /**
+   * Whether the controls should be shown. For screen recording no controls can be desired.
+   */
+  showControls: boolean;
+  /**
+   * Whether to hide the screen-sharing button.
+   */
+  hideScreensharing: boolean;
+
+  /**
+   * Whether the app is allowed to use fallback STUN servers for ICE in case the
+   * user's homeserver doesn't provide any.
+   */
+  allowIceFallback: boolean;
+
+  /**
+   * Whether the app should use per participant keys for E2EE.
+   */
+  perParticipantE2EE: boolean;
+  /**
+   * Whether the global JS controls for audio output devices should be enabled,
+   * allowing the list of output devices to be controlled by the app hosting
+   * Element Call.
+   */
+  controlledAudioDevices: boolean;
+  /**
+   * Setting this flag skips the lobby and brings you in the call directly.
+   * In the widget this can be combined with preload to pass the device settings
+   * with the join widget action.
+   */
+  skipLobby: boolean;
+  /**
+   * Setting this flag makes element call show the lobby after leaving a call.
+   * This is useful for video rooms.
+   */
+  returnToLobby: boolean;
+  /**
+   * Whether and what type of notification EC should send, when the user joins the call.
+   */
+  sendNotificationType?: RTCNotificationType;
+  /**
+   * Whether the app should automatically leave the call when there
+   * is no one left in the call.
+   * This is one part to make the call matrixRTC session behave like a telephone call.
+   */
+  autoLeaveWhenOthersLeft: boolean;
+
+  /**
+   * If the client should behave like it is awaiting an answer if a notification was sent (wait for call pick up).
+   * This is a no-op if not combined with sendNotificationType.
+   *
+   * This entails:
+   *  - show ui that it is awaiting an answer
+   *  - play a sound that indicates that it is awaiting an answer
+   *  - auto-dismiss the call widget once the notification lifetime expires on the receivers side.
+   */
+  waitForCallPickup: boolean;
+
+  /**
+   * Whether to enable echo cancellation for audio capture.
+   * Defaults to true.
+   */
+  echoCancellation?: boolean;
+  /**
+   * Whether to enable noise suppression for audio capture.
+   * Defaults to true.
+   */
+  noiseSuppression?: boolean;
+
+  callIntent?: RTCCallIntent;
+}
+
+// If you need to add a new flag to this interface, prefer a name that describes
+// a specific behavior (such as 'confineToRoom'), rather than one that describes
+// the situations that call for this behavior ('isEmbedded'). This makes it
+// clearer what each flag means, and helps us avoid coupling Element Call's
+// behavior to the needs of specific consumers.
+
+/**
+ * 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;
+}

src/UrlParams.ts

@@ -9,47 +9,36 @@ Please see LICENSE in the repository root for full details.
 import { createContext, use, useMemo } from "react";
 import { useLocation } from "react-router-dom";
 import { logger } from "matrix-js-sdk/lib/logger";
-import {
-  type RTCCallIntent,
-  type RTCNotificationType,
-} from "matrix-js-sdk/lib/matrixrtc";
 import { pickBy } from "lodash-es";
 
 import { Config } from "./config/Config";
 import { type EncryptionSystem } from "./e2ee/sharedKeyManagement";
 import { E2eeType } from "./e2ee/e2eeType";
-import { platform } from "./Platform";
+import {
+  BackgroundStyle,
+  configurationForIntent,
+  HeaderStyle,
+  type UrlConfiguration,
+  UserIntent,
+} from "./UrlConfiguration";
 import { redact } from "./utils/redact";
 
+// Moved to their own module, so that a host can import them without the rest
+// of this one; re-exported here as they always were
+export {
+  BackgroundStyle,
+  configurationForIntent,
+  HeaderStyle,
+  type UrlConfiguration,
+  UserIntent,
+} from "./UrlConfiguration";
+
 interface RoomIdentifier {
   roomAlias: string | null;
   roomId: string | null;
   viaServers: string[];
 }
 
-export enum UserIntent {
-  StartNewCall = "start_call",
-  JoinExistingCall = "join_existing",
-  StartNewCallVoice = "start_call_voice",
-  JoinExistingCallVoice = "join_existing_voice",
-  StartNewCallDM = "start_call_dm",
-  StartNewCallDMVoice = "start_call_dm_voice",
-  JoinExistingCallDM = "join_existing_dm",
-  JoinExistingCallDMVoice = "join_existing_dm_voice",
-  Unknown = "unknown",
-}
-
-export enum HeaderStyle {
-  None = "none",
-  Standard = "standard",
-  AppBar = "app_bar",
-}
-
-export enum BackgroundStyle {
-  Solid = "solid",
-  Gradient = "gradient",
-}
-
 /**
  * The UrlProperties are used to pass required data to the widget.
  * Those are different in different rooms, users, devices. They do not configure the behavior of the
@@ -166,109 +155,6 @@ export interface UrlProperties {
    */
   background: BackgroundStyle;
 }
-
-/**
- * The configuration for the app, which can be set via URL parameters.
- * Those property are different to the UrlProperties, since they are all optional
- * and configure the behavior of the app. Their value is the same if EC is used in
- * the same context but with different accounts/users.
- *
- * Their defaults can be controlled by the `intent` property.
- */
-export interface UrlConfiguration {
-  /**
-   * Whether the app should keep the user confined to the current call/room.
-   */
-  confineToRoom: boolean;
-  /**
-   * Whether the app should pause before joining the call until it sees an
-   * io.element.join widget action, allowing it to be preloaded.
-   */
-  preload: boolean;
-  /**
-   * The style of headers to show. "standard" is the default arrangement, "none"
-   * hides the header entirely, and "app_bar" produces a header with a back
-   * button like you might see in mobile apps. The callback for the back button
-   * is window.controls.onBackButtonPressed.
-   */
-  header: HeaderStyle;
-  /**
-   * Whether the controls should be shown. For screen recording no controls can be desired.
-   */
-  showControls: boolean;
-  /**
-   * Whether to hide the screen-sharing button.
-   */
-  hideScreensharing: boolean;
-
-  /**
-   * Whether the app is allowed to use fallback STUN servers for ICE in case the
-   * user's homeserver doesn't provide any.
-   */
-  allowIceFallback: boolean;
-
-  /**
-   * Whether the app should use per participant keys for E2EE.
-   */
-  perParticipantE2EE: boolean;
-  /**
-   * Whether the global JS controls for audio output devices should be enabled,
-   * allowing the list of output devices to be controlled by the app hosting
-   * Element Call.
-   */
-  controlledAudioDevices: boolean;
-  /**
-   * Setting this flag skips the lobby and brings you in the call directly.
-   * In the widget this can be combined with preload to pass the device settings
-   * with the join widget action.
-   */
-  skipLobby: boolean;
-  /**
-   * Setting this flag makes element call show the lobby after leaving a call.
-   * This is useful for video rooms.
-   */
-  returnToLobby: boolean;
-  /**
-   * Whether and what type of notification EC should send, when the user joins the call.
-   */
-  sendNotificationType?: RTCNotificationType;
-  /**
-   * Whether the app should automatically leave the call when there
-   * is no one left in the call.
-   * This is one part to make the call matrixRTC session behave like a telephone call.
-   */
-  autoLeaveWhenOthersLeft: boolean;
-
-  /**
-   * If the client should behave like it is awaiting an answer if a notification was sent (wait for call pick up).
-   * This is a no-op if not combined with sendNotificationType.
-   *
-   * This entails:
-   *  - show ui that it is awaiting an answer
-   *  - play a sound that indicates that it is awaiting an answer
-   *  - auto-dismiss the call widget once the notification lifetime expires on the receivers side.
-   */
-  waitForCallPickup: boolean;
-
-  /**
-   * Whether to enable echo cancellation for audio capture.
-   * Defaults to true.
-   */
-  echoCancellation?: boolean;
-  /**
-   * Whether to enable noise suppression for audio capture.
-   * Defaults to true.
-   */
-  noiseSuppression?: boolean;
-
-  callIntent?: RTCCallIntent;
-}
-
-// If you need to add a new flag to this interface, prefer a name that describes
-// a specific behavior (such as 'confineToRoom'), rather than one that describes
-// the situations that call for this behavior ('isEmbedded'). This makes it
-// clearer what each flag means, and helps us avoid coupling Element Call's
-// behavior to the needs of specific consumers.
 export interface UrlParams extends UrlProperties, UrlConfiguration {}
 
 class ParamParser {
@@ -354,97 +240,6 @@ 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.
@@ -578,7 +373,7 @@ export const computeUrlParams = (search = "", hash = ""): UrlParams => {
     "intent:",
     intent,
     "\nproperties:",
-    redact(properties, "password"),
+    redact(properties, "password", "posthogUserId"),
     "configuration:",
     configuration,
   );

src/__snapshots__/AppBar.test.tsx.snap

@@ -15,7 +15,7 @@ exports[`AppBar > renders 1`] = `
         tabindex="0"
       >
         <div
-          class="_indicator-icon_147l5_17"
+          class="_indicator-icon_j097f_17"
           style="--cpd-icon-button-size: 100%;"
         >
           <svg
@@ -58,7 +58,7 @@ exports[`AppBar > renders with title and subtitle 1`] = `
         tabindex="0"
       >
         <div
-          class="_indicator-icon_147l5_17"
+          class="_indicator-icon_j097f_17"
           style="--cpd-icon-button-size: 100%;"
         >
           <svg

src/base.css

@@ -5,19 +5,24 @@ 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.
+/* The styles Element Call needs wherever it is shown: the element defaults and
+custom properties 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.
+host's own document. Compound's stylesheets — the design tokens, the component
+styles and the fonts they use — are not here either: as a component, Element
+Call shares the host's copy of Compound (it is a peer dependency, so that what
+Compound floats into the host's body, tooltips and menus, is styled by the
+host's stylesheet), and index.css loads it for the page.
+
+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
@@ -25,16 +30,7 @@ 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;

src/button/ReactionToggleButton.module.css

@@ -83,7 +83,7 @@ div.reactionPopupMenuRoot.reactionPopupMenuModal > div > div {
   flex: 0 0 auto;
 }
 
-.reactionButton {
+.reactionPopupMenu .reactionsMenu .reactionButton {
   padding: var(--reaction-button-padding);
   border-radius: var(--cpd-radius-pill-effect);
   font-size: var(--reaction-button-fontsize);

src/button/__snapshots__/ReactionToggleButton.test.tsx.snap

@@ -9,7 +9,7 @@ exports[`Can close reaction dialog 1`] = `
     aria-disabled="false"
     aria-expanded="true"
     aria-haspopup="true"
-    aria-labelledby="_r_bb_"
+    aria-labelledby="_r_bh_"
     class="_button_1nw83_8 _has-icon_1nw83_60 _icon-only_1nw83_53"
     data-kind="primary"
     data-size="lg"

src/components/BackgroundEffectGrid.module.css

@@ -0,0 +1,131 @@
+/*
+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.
+*/
+
+.grid {
+  display: grid;
+  /* A zero floor, so a long label wraps inside its tile rather than widening
+     the grid past the menu. */
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  grid-auto-rows: 1fr;
+  gap: var(--cpd-space-3x);
+  padding: var(--cpd-space-2x) var(--cpd-space-4x) 0;
+}
+
+/* Within the grid, to outweigh the menu item styles the tiles are built on. */
+.grid .tile {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--cpd-space-1x);
+  min-inline-size: 0;
+  padding: var(--cpd-space-3x) var(--cpd-space-2x);
+  /* Not hidden: that makes the tile a scroll container, which focus scrolls
+     into view without its border, and so without the focus ring. */
+  overflow: clip;
+  border: var(--cpd-border-width-2) solid
+    var(--cpd-color-border-interactive-secondary);
+  border-radius: var(--cpd-space-2x);
+  background: none;
+  color: var(--cpd-color-icon-secondary);
+  font: inherit;
+  cursor: pointer;
+}
+
+/* As the menu items highlight on hover. */
+.grid .tile[data-highlighted] {
+  background: var(--cpd-color-bg-action-secondary-hovered);
+}
+
+.grid .tile[aria-checked="true"] {
+  border-color: var(--cpd-color-border-accent);
+}
+
+.grid .tile[data-disabled] {
+  cursor: default;
+  opacity: 0.55;
+}
+
+.tile[data-disabled] .picture {
+  filter: grayscale(1);
+}
+
+.swatch {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.picture {
+  position: absolute;
+  inset: 0;
+  inline-size: 100%;
+  block-size: 100%;
+  object-fit: cover;
+}
+
+/* Positioned, or the picture, positioned itself, would cover it. */
+.mark {
+  position: relative;
+  display: inline-flex;
+  color: var(--cpd-color-icon-accent-primary);
+}
+
+/* On a picture the mark needs a ground of its own to be seen. */
+.picture ~ .mark {
+  border-radius: 50%;
+  background: var(--cpd-color-bg-canvas-default);
+  box-shadow: 0 0 0 var(--cpd-border-width-2) var(--cpd-color-bg-canvas-default);
+}
+
+.label {
+  max-inline-size: 100%;
+  font: var(--cpd-font-body-sm-medium);
+  color: var(--cpd-color-text-primary);
+  text-align: center;
+  overflow-wrap: anywhere;
+}
+
+.removable {
+  position: relative;
+  display: flex;
+  min-inline-size: 0;
+}
+
+.removable > .tile {
+  flex: 1;
+}
+
+/* Clear of the target for choosing the tile. */
+.remove {
+  position: absolute;
+  inset-block-start: 0;
+  inset-inline-end: 0;
+  translate: 20% -20%;
+  display: none;
+  align-items: center;
+  justify-content: center;
+  inline-size: 28px;
+  block-size: 28px;
+  border-radius: 50%;
+  background: var(--cpd-color-bg-canvas-default);
+  color: var(--cpd-color-icon-critical-primary);
+  box-shadow: 0 1.2px 2.4px 0 rgb(0 0 0 / 15%);
+  cursor: pointer;
+}
+
+.remove:hover {
+  background: var(--cpd-color-bg-critical-subtle-hovered);
+  box-shadow: 0 0 0 var(--cpd-border-width-1)
+    var(--cpd-color-border-critical-subtle);
+}
+
+.removable:hover .remove,
+.removable:focus-within .remove {
+  display: flex;
+}

src/components/BackgroundEffectGrid.tsx

@@ -0,0 +1,220 @@
+/*
+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 KeyboardEvent,
+  type ReactNode,
+  type ReactElement,
+} from "react";
+import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
+import { InlineSpinner, MenuItem, Tooltip } from "@vector-im/compound-web";
+import {
+  BlockIcon,
+  BlurIcon,
+  CheckCircleSolidIcon,
+  CloseIcon,
+  PlusIcon,
+} from "@vector-im/compound-design-tokens/assets/web/icons";
+
+import styles from "./BackgroundEffectGrid.module.css";
+
+/** One choice in the camera menu's Background effects section. */
+export interface BackgroundEffectOption {
+  id: string;
+  /** The tile's accessible name; drawn only where the tile has no picture. */
+  label: string;
+  kind: "none" | "blur" | "image";
+  /** For kind "image". */
+  imageUrl?: string;
+  /** Whether it is the user's to remove. */
+  removable?: boolean;
+}
+
+interface Props {
+  /** Names the group, whose heading is hidden from assistive technology. */
+  label: string;
+  heading: ReactNode;
+  effects: BackgroundEffectOption[];
+  selected: string | undefined;
+  /** Undefined where effects can't run: all but no effect are disabled. */
+  onSelect: ((id: string) => void) | undefined;
+  /** Shown on the selected tile until its effect is on screen. */
+  settling?: boolean;
+  /** Id of the text saying what the user should know before choosing. */
+  describedBy?: string;
+  /** Offers to add a background of one's own. Omit to leave that tile out. */
+  onAdd?: () => void;
+  addLabel?: string;
+  /** Removes a removable one, never the one in force. Omit to offer none. */
+  onRemove?: (id: string) => void;
+  removeLabel?: string;
+}
+
+/**
+ * The background effects as a grid of tiles: one radio choice, walked by the
+ * menu's arrow keys like the device rows.
+ */
+export const BackgroundEffectGrid: FC<Props> = ({
+  label,
+  heading,
+  effects,
+  selected,
+  onSelect,
+  settling = false,
+  describedBy,
+  onAdd,
+  addLabel,
+  onRemove,
+  removeLabel,
+}) => {
+  const choose = (id: string): void => {
+    if (id !== selected) onSelect?.(id);
+  };
+  const tiles = effects.map((effect) => {
+    const checked = effect.id === selected;
+    const disabled = onSelect === undefined && effect.kind !== "none";
+    const remove =
+      effect.removable && !checked && onRemove !== undefined
+        ? (): void => onRemove(effect.id)
+        : undefined;
+    const removeProps =
+      remove === undefined
+        ? {}
+        : {
+            "aria-keyshortcuts": "Delete",
+            onKeyDown: (e: KeyboardEvent): void => {
+              if (e.key !== "Delete" && e.key !== "Backspace") return;
+              e.preventDefault();
+              remove();
+            },
+          };
+    const content = (
+      <TileContent
+        effect={effect}
+        checked={checked}
+        settling={checked && settling}
+      />
+    );
+    const tile = (
+      <MenuItem
+        key={effect.id}
+        role="menuitemradio"
+        aria-checked={checked}
+        aria-busy={checked && settling}
+        disabled={disabled}
+        data-disabled={disabled ? "" : undefined}
+        label={null}
+        hideChevron
+        className={styles.tile}
+        // Without a handler it isn't one of the menu's items, so the keyboard
+        // passes over it.
+        onSelect={
+          disabled
+            ? null
+            : (e): void => {
+                // Kept open, so the user sees what they chose take effect.
+                e.preventDefault();
+                choose(effect.id);
+              }
+        }
+        {...removeProps}
+      >
+        {content}
+      </MenuItem>
+    );
+    if (remove === undefined) return tile;
+    // Beside the item, not in it: inside, the item takes the press first and
+    // the tile is chosen instead.
+    return (
+      <div key={effect.id} className={styles.removable}>
+        {tile}
+        <Tooltip label={removeLabel ?? ""}>
+          {/* Not a control of its own, so the menu keeps one keyboard model:
+              the keyboard reaches the same action through Delete. */}
+          <span aria-hidden className={styles.remove} onClick={remove}>
+            <CloseIcon width={20} height={20} />
+          </span>
+        </Tooltip>
+      </div>
+    );
+  });
+
+  // A command rather than a choice, so an item beside the radios.
+  const addContent = (
+    <>
+      <span aria-hidden className={styles.swatch}>
+        <PlusIcon width={24} height={24} />
+      </span>
+      <VisuallyHidden>{addLabel}</VisuallyHidden>
+    </>
+  );
+  const addTile =
+    onAdd === undefined ? null : (
+      <MenuItem
+        label={null}
+        hideChevron
+        className={styles.tile}
+        onSelect={(e) => {
+          e.preventDefault();
+          onAdd();
+        }}
+      >
+        {addContent}
+      </MenuItem>
+    );
+
+  return (
+    <div role="group" aria-label={label} aria-describedby={describedBy}>
+      {heading}
+      <div role="none" className={styles.grid}>
+        {tiles}
+        {addTile}
+      </div>
+    </div>
+  );
+};
+
+function TileContent({
+  effect,
+  checked,
+  settling,
+}: {
+  effect: BackgroundEffectOption;
+  checked: boolean;
+  settling: boolean;
+}): ReactElement {
+  return (
+    <>
+      <span aria-hidden className={styles.swatch}>
+        {effect.kind === "image" && (
+          <img className={styles.picture} src={effect.imageUrl} alt="" />
+        )}
+        {settling ? (
+          <span className={styles.mark}>
+            <InlineSpinner size={20} />
+          </span>
+        ) : checked ? (
+          <CheckCircleSolidIcon
+            className={styles.mark}
+            width={20}
+            height={20}
+          />
+        ) : effect.kind === "none" ? (
+          <BlockIcon width={20} height={20} />
+        ) : effect.kind === "blur" ? (
+          <BlurIcon width={20} height={20} />
+        ) : null}
+      </span>
+      {effect.kind === "image" ? (
+        <VisuallyHidden>{effect.label}</VisuallyHidden>
+      ) : (
+        <span className={styles.label}>{effect.label}</span>
+      )}
+    </>
+  );
+}

src/components/CallFooter.module.css

@@ -43,7 +43,10 @@ Please see LICENSE in the repository root for full details.
   inset-inline: 0;
 }
 
-.footer.overlay:has(:focus-visible) {
+/* Keep the footer while it is in use: focus inside it, or a menu opened from
+   it. The menu is portalled out, so the trigger's aria-expanded tracks it. */
+.footer.overlay:has(:focus-visible),
+.footer.overlay:has([aria-expanded="true"]) {
   opacity: 1;
   pointer-events: initial;
 }

src/components/CallFooter.stories.tsx

@@ -13,6 +13,7 @@ import { Link } from "@vector-im/compound-web";
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { CallFooter, type FooterSnapshot } from "./CallFooter";
 import inCallViewStyles from "../room/InCallView.module.css";
+import styles from "./CallFooter.module.css";
 import { useStaticViewModel } from "../state/ViewModel";
 import { ReactionsSenderContext } from "../reactions/useReactionsSender";
 import { type ReactionOption } from "../reactions";
@@ -21,6 +22,7 @@ import { MediaDevices } from "../state/MediaDevices";
 import { globalScope } from "../state/ObservableScope";
 import { constant } from "../state/Behavior";
 import { type LayoutMode } from "../state/LayoutSwitchViewModel";
+import { shippedBackgrounds } from "../livekit/backgroundEffects";
 
 // consts for tests
 const reactionIdentifier = "@user:example.com:DEVICE";
@@ -122,8 +124,24 @@ export const Default: Story = {
     toggleAudio: fn(),
     toggleVideo: fn(),
     toggleScreenSharing: fn(),
-    toggleBlur: fn(),
-    videoBlurEnabled: true,
+    selectBackgroundEffect: fn(),
+    backgroundEffect: "blur",
+    backgroundEffects: [
+      { id: "none", kind: "none", removable: false },
+      { id: "blur", kind: "blur", removable: false },
+      ...shippedBackgrounds.map((background) => ({
+        id: `image:${background.id}`,
+        kind: "image" as const,
+        imageUrl: background.imagePath,
+        removable: false,
+      })),
+    ],
+    backgroundEffectNotice: undefined,
+    backgroundEffectSettling: false,
+    backgroundImageRefusal: undefined,
+    addBackgroundImage: fn(),
+    removeBackgroundEffect: fn(),
+    cameraTrack: null,
     hangup: fn(),
     buttonSize: "lg",
     showFooter: true,
@@ -137,10 +155,13 @@ export const Default: Story = {
     debugTileLayout: false,
     tileStoreGeneration: undefined,
     audioOptions: [],
+    audioOutputOptions: [],
     videoOptions: [],
     selectedAudio: undefined,
+    selectedAudioOutput: undefined,
     selectedVideo: undefined,
     selectAudioButtonOption: undefined,
+    selectAudioOutputOption: undefined,
     selectVideoButtonOption: undefined,
   },
   parameters: {
@@ -158,15 +179,46 @@ export const WithAudioAndVideoOptions: Story = {
       { label: { type: "name", name: "Microphone 1" }, id: "1" },
       { label: { type: "name", name: "Microphone 2" }, id: "2" },
     ],
+    audioOutputOptions: [
+      { label: { type: "default", name: "Built-in Output" }, id: "default" },
+      { label: { type: "name", name: "Headset" }, id: "2" },
+    ],
     videoOptions: [
       { label: { type: "name", name: "Camera 1" }, id: "1" },
       { label: { type: "name", name: "Camera 2" }, id: "2" },
     ],
     selectedAudio: "2",
+    selectedAudioOutput: "default",
     selectedVideo: "1",
   },
 };
 
+export const StaysWhileAMenuIsOpen: Story = {
+  ...Default,
+  args: {
+    ...WithAudioAndVideoOptions.args,
+    // In a short window the footer overlays the call and hides itself.
+    asOverlay: true,
+    showFooter: true,
+  },
+  play: async ({ canvasElement }): Promise<void> => {
+    const footer = canvasElement.querySelector<HTMLElement>(
+      '[data-testid="footer-container"]',
+    )!;
+    await userEvent.click(
+      within(canvasElement).getByRole("button", { name: "Microphone" }),
+    );
+    await expect(document.body.querySelector('[role="menu"]')).not.toBeNull();
+
+    // The call hides the footer with this class.
+    footer.classList.add(styles.hidden);
+
+    // Read after the 0.15s fade, not mid-transition.
+    await new Promise((settled) => setTimeout(settled, 400));
+    await expect(getComputedStyle(footer).opacity).toBe("1");
+  },
+};
+
 export const AudioBusy: Story = {
   ...Default,
   args: {

src/components/CallFooter.tsx

@@ -7,6 +7,8 @@ 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 { type LocalVideoTrack } from "livekit-client";
+import { useTranslation } from "react-i18next";
 
 import LogoMark from "../icons/LogoMark.svg?react";
 import LogoType from "../icons/LogoType.svg?react";
@@ -31,6 +33,23 @@ import { type ViewModel } from "../state/ViewModel";
 import { useBehavior } from "../useBehavior";
 import { type LayoutSwitchViewModel } from "../state/LayoutSwitchViewModel";
 import { LayoutSwitch } from "../room/LayoutSwitch";
+import { type BackgroundEffectOption } from "./BackgroundEffectGrid";
+import { SelfPreview } from "./SelfPreview";
+import { type UnusableReason } from "../livekit/backgroundImages";
+
+export interface BackgroundImageRefusal {
+  reason: UnusableReason | "not-kept";
+}
+
+/** A background effect on offer, which the view names. */
+export interface BackgroundEffectChoice {
+  /** Its option id, as `backgroundEffect` gives the one in force. */
+  id: string;
+  kind: "none" | "blur" | "image";
+  imageUrl?: string;
+  /** One the user added, which they can take away again. */
+  removable: boolean;
+}
 
 export interface AudioOutputSwitcher {
   targetOutput: string;
@@ -56,20 +75,37 @@ export interface FooterActions {
   toggleAudio: (() => void) | undefined;
   /** Also controls if the videoMute button is disabled */
   toggleVideo: (() => void) | undefined;
-  toggleBlur: (() => void) | undefined;
+  /** Undefined where background effects can't be chosen. */
+  selectBackgroundEffect: ((id: string) => void) | undefined;
+  /** Undefined where no background can be added. */
+  addBackgroundImage: ((file: File) => void) | undefined;
+  /** Removes an added background by its option id; never the one in force. */
+  removeBackgroundEffect: ((id: string) => void) | undefined;
   toggleScreenSharing: (() => void) | undefined;
   /** Also controls if the settings button is visible */
   openSettings: (() => void) | undefined;
   /** Also controls if the hangup button is visible */
   hangup: (() => void) | undefined;
 }
+
 // we do not use any ? optional properties so that the vm type is including all fields.
 export interface FooterState {
   audioEnabled: boolean;
   audioBusy: boolean;
   videoEnabled: boolean;
   videoBusy: boolean;
-  videoBlurEnabled: boolean;
+  /** The background effect in force, as its option id. */
+  backgroundEffect: string;
+  /** Every effect on offer, in the order they are shown. */
+  backgroundEffects: BackgroundEffectChoice[];
+  /** What the user is told about effects here, if anything. */
+  backgroundEffectNotice: "unavailable" | "slow" | undefined;
+  /** Whether the first effect chosen is still being prepared. */
+  backgroundEffectSettling: boolean;
+  /** Why the last file offered couldn't be kept, if it couldn't. */
+  backgroundImageRefusal: BackgroundImageRefusal | undefined;
+  /** The camera to preview, with the effect in force; null while it is off. */
+  cameraTrack: LocalVideoTrack | null;
   showFooter: boolean;
 
   /* This is needed for WindowMode = "flat" */
@@ -99,11 +135,15 @@ export interface FooterState {
 
   /** Providing no options `[]` or `undefined` will imply that we dont have a audio fast switcher */
   audioOptions: MenuOptions[];
+  /** Output (speaker) devices. */
+  audioOutputOptions: MenuOptions[];
   /** Providing no options `[]` or `undefined` will imply that we dont have a audio fast switcher */
   videoOptions: MenuOptions[];
   selectedAudio: string | undefined;
+  selectedAudioOutput: string | undefined;
   selectedVideo: string | undefined;
   selectAudioButtonOption: ((deviceId: string) => void) | undefined;
+  selectAudioOutputOption: ((deviceId: string) => void) | undefined;
   selectVideoButtonOption: ((option: string) => void) | undefined;
 }
 
@@ -113,12 +153,14 @@ export interface FooterProps {
   children?: JSX.Element | JSX.Element[] | false;
   vm: ViewModel<FooterSnapshot>;
 }
+
 export const CallFooter: FC<FooterProps> = ({
   className,
   ref,
   children,
   vm,
 }) => {
+  const { t } = useTranslation();
   const asOverlay = useBehavior(vm.asOverlay$);
   const showFooter = useBehavior(vm.showFooter$);
   const hideControls = useBehavior(vm.hideControls$);
@@ -143,9 +185,35 @@ export const CallFooter: FC<FooterProps> = ({
   const audioOptions = useBehavior(vm.audioOptions$);
   const selectedAudio = useBehavior(vm.selectedAudio$);
   const selectAudioButtonOption = useBehavior(vm.selectAudioButtonOption$);
+  const audioOutputOptions = useBehavior(vm.audioOutputOptions$);
+  const selectedAudioOutput = useBehavior(vm.selectedAudioOutput$);
+  const selectAudioOutputOption = useBehavior(vm.selectAudioOutputOption$);
   const selectVideoButtonOption = useBehavior(vm.selectVideoButtonOption$);
-  const toggleBlur = useBehavior(vm.toggleBlur$);
-  const videoBlurEnabled = useBehavior(vm.videoBlurEnabled$);
+  const backgroundEffect = useBehavior(vm.backgroundEffect$);
+  const selectBackgroundEffect = useBehavior(vm.selectBackgroundEffect$);
+  const backgroundEffectNotice = useBehavior(vm.backgroundEffectNotice$);
+  const backgroundEffectSettling = useBehavior(vm.backgroundEffectSettling$);
+  const addBackgroundImage = useBehavior(vm.addBackgroundImage$);
+  const removeBackgroundEffect = useBehavior(vm.removeBackgroundEffect$);
+  const cameraTrack = useBehavior(vm.cameraTrack$);
+  const refusal = useBehavior(vm.backgroundImageRefusal$);
+  const refusalMessage = useMemo(() => {
+    switch (refusal?.reason) {
+      case undefined:
+        return undefined;
+      case "not-an-image":
+        return { text: t("error.background_not_an_image") };
+      case "animated":
+        return { text: t("error.background_animated") };
+      case "undecodable":
+        return { text: t("error.background_undecodable") };
+      case "not-kept":
+        return { text: t("error.background_not_kept") };
+    }
+  }, [refusal, t]);
+  const backgroundEffects = useBackgroundEffectLabels(
+    useBehavior(vm.backgroundEffects$),
+  );
   const buttonSize = useBehavior(vm.buttonSize$);
   const showLogo = useBehavior(vm.showLogo$);
 
@@ -168,7 +236,6 @@ export const CallFooter: FC<FooterProps> = ({
   if ((audioOptions?.length ?? 0) > 0) {
     buttons.push(
       <MediaMuteAndSwitchButton
-        title={"Mic Source"}
         key="audio"
         iconsAndLabels="audio"
         enabled={audioEnabled ?? false}
@@ -178,6 +245,9 @@ export const CallFooter: FC<FooterProps> = ({
         options={audioOptions}
         selectedOption={selectedAudio}
         onSelect={selectAudioButtonOption}
+        outputOptions={audioOutputOptions}
+        selectedOutputOption={selectedAudioOutput}
+        onSelectOutput={selectAudioOutputOption}
       />,
     );
   } else {
@@ -197,7 +267,6 @@ export const CallFooter: FC<FooterProps> = ({
   if ((videoOptions?.length ?? 0) > 0) {
     buttons.push(
       <MediaMuteAndSwitchButton
-        title={"Camera Source"}
         key="video"
         iconsAndLabels="video"
         enabled={videoEnabled ?? false}
@@ -206,8 +275,21 @@ export const CallFooter: FC<FooterProps> = ({
         options={videoOptions}
         selectedOption={selectedVideo}
         onSelect={selectVideoButtonOption}
-        videoBlurToggleClick={toggleBlur}
-        videoBlurEnabled={videoBlurEnabled}
+        backgroundEffects={backgroundEffects}
+        selectedBackgroundEffect={backgroundEffect}
+        onSelectBackgroundEffect={selectBackgroundEffect}
+        backgroundEffectSettling={backgroundEffectSettling}
+        onAddBackgroundImage={addBackgroundImage}
+        onRemoveBackgroundEffect={removeBackgroundEffect}
+        selfPreview={<SelfPreview track={cameraTrack} />}
+        backgroundImageRefusal={refusalMessage}
+        backgroundEffectNotice={
+          backgroundEffectNotice === "unavailable"
+            ? t("background_effects.unavailable")
+            : backgroundEffectNotice === "slow"
+              ? t("background_effects.slow")
+              : undefined
+        }
       />,
     );
   } else {
@@ -332,3 +414,21 @@ const TilesDebugInfo: FC<TilesDebugInfoProps> = ({ generation$ }) => {
   const generation = useBehavior(generation$);
   return `Tiles generation: ${generation}`;
 };
+
+function useBackgroundEffectLabels(
+  choices: BackgroundEffectChoice[],
+): BackgroundEffectOption[] {
+  const { t } = useTranslation();
+  return useMemo(() => {
+    let pictures = 0;
+    return choices.map((choice) => ({
+      ...choice,
+      label:
+        choice.kind === "none"
+          ? t("background_effects.none")
+          : choice.kind === "blur"
+            ? t("background_effects.blur")
+            : t("background_effects.numbered", { n: ++pictures }),
+    }));
+  }, [choices, t]);
+}

src/components/CallFooterViewModel.test.ts

@@ -5,17 +5,38 @@ 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 { type LocalVideoTrack } from "livekit-client";
 
-import { testScope, mockMuteStates, mockMediaDevices } from "../utils/test";
-import { constant } from "../state/Behavior";
+import {
+  flushPromises,
+  testScope,
+  mockMuteStates,
+  mockMediaDevices,
+} from "../utils/test";
+import { type Behavior, 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 {
+  createCallFooterViewModel,
+  createLobbyFooterViewModel,
+} from "./CallFooterViewModel";
 import { HeaderStyle } from "../UrlParams";
+import { type BackgroundEffectsState } from "../livekit/BackgroundEffectsContext";
+import { SyncedCameraTrack } from "../livekit/cameraTrack";
+import { type MuteStates } from "../state/MuteStates";
+import { backgroundEffect as backgroundEffectSetting } from "../settings/settings";
+import { shippedBackgrounds } from "../livekit/backgroundEffects";
+import type * as BackgroundImages from "../livekit/backgroundImages";
+import {
+  type AddedBackground,
+  addedBackgrounds,
+  maxAddedBackgrounds,
+  UnusableImage,
+} from "../livekit/backgroundImages";
 
 const platformMock = vi.hoisted(() => vi.fn(() => "desktop"));
 vi.mock("../Platform", () => ({
@@ -24,10 +45,33 @@ vi.mock("../Platform", () => ({
   },
 }));
 
-// Prevent supportsBackgroundProcessors from throwing in jsdom – it is not
-// exercised by these tests (only used in `videoToggles`, not `videoOptions`).
+// The SDK's own check needs WebGL and canvas APIs jsdom does not have.
+const sdkSupportMock = vi.hoisted(() => vi.fn(() => false));
+const modernRouteMock = vi.hoisted(() => vi.fn(() => true));
 vi.mock("@livekit/track-processors", () => ({
-  supportsBackgroundProcessors: (): boolean => false,
+  supportsBackgroundProcessors: (): boolean => sdkSupportMock(),
+  supportsModernBackgroundProcessors: (): boolean => modernRouteMock(),
+}));
+
+const store = vi.hoisted(() => ({
+  add: vi.fn<(file: Blob) => Promise<string>>(),
+  remove: vi.fn<(id: string) => Promise<void>>(),
+}));
+vi.mock("../livekit/backgroundImages", async (original) => {
+  const { BehaviorSubject } = await import("rxjs");
+  return {
+    ...(await original<typeof BackgroundImages>()),
+    addedBackgrounds: {
+      added$: new BehaviorSubject<AddedBackground[] | undefined>([]),
+      add: store.add,
+      remove: store.remove,
+    },
+  };
+});
+
+const outputSelectionMock = vi.hoisted(() => vi.fn(() => true));
+vi.mock("livekit-client", () => ({
+  supportsAudioOutputSelection: (): boolean => outputSelectionMock(),
 }));
 
 /**
@@ -73,6 +117,16 @@ const pipLayout: Layout = {
   spotlight: {} as SpotlightTileViewModel,
 };
 
+const noPipeline = constant<BackgroundEffectsState>({
+  supported: false,
+  processor: undefined,
+});
+
+/** The provider's verdict, which the SDK's check stands for here. */
+function pipelineAsTheSdkSays(): Behavior<BackgroundEffectsState> {
+  return constant({ supported: sdkSupportMock(), processor: undefined });
+}
+
 const twoMicsAndOneCamMediaDevices = mockMediaDevices({
   audioInput: {
     available$: constant(
@@ -96,6 +150,67 @@ const twoMicsAndOneCamMediaDevices = mockMediaDevices({
 });
 
 describe("createCallFooterViewModel", () => {
+  describe("selectAudioOutputOption", () => {
+    function buildFooterVm(): ReturnType<typeof createCallFooterViewModel> {
+      platformMock.mockReturnValue("desktop");
+      return createCallFooterViewModel(
+        testScope(),
+        buildMinimalCallViewModel(gridLayout),
+        mockMuteStates(),
+        twoMicsAndOneCamMediaDevices,
+        noPipeline,
+        /* reactionIdentifier */ undefined,
+        { showControls: true, header: HeaderStyle.Standard },
+      );
+    }
+
+    it("is withheld where the platform cannot route audio to a chosen device", () => {
+      outputSelectionMock.mockReturnValue(false);
+      expect(buildFooterVm().selectAudioOutputOption$.value).toBeUndefined();
+    });
+
+    it("is offered where the platform can route audio to a chosen device", () => {
+      outputSelectionMock.mockReturnValue(true);
+      expect(buildFooterVm().selectAudioOutputOption$.value).toBeDefined();
+    });
+  });
+
+  describe("audioOutputOptions", () => {
+    it("is an empty list, not absent, where the platform enumerates no outputs", () => {
+      platformMock.mockReturnValue("desktop");
+      outputSelectionMock.mockReturnValue(true);
+
+      const vm = createCallFooterViewModel(
+        testScope(),
+        buildMinimalCallViewModel(gridLayout),
+        mockMuteStates(),
+        mockMediaDevices({
+          audioInput: {
+            available$: constant(
+              new Map<string, DeviceLabel>([
+                ["mic1", { type: "name", name: "Microphone 1" }],
+              ]),
+            ),
+            selected$: constant(undefined),
+            select: vi.fn(),
+          },
+          // As Safari: no outputs listed.
+          audioOutput: {
+            available$: constant(new Map<string, DeviceLabel>()),
+            selected$: constant(undefined),
+            select: vi.fn(),
+          },
+        }),
+        noPipeline,
+        /* reactionIdentifier */ undefined,
+        { showControls: true, header: HeaderStyle.Standard },
+      );
+
+      // Empty, not undefined: undefined would hide the section.
+      expect(vm.audioOutputOptions$.value).toEqual([]);
+    });
+  });
+
   describe("audioOptions and videoOptions", () => {
     function checkEmptyFor(platform: string, layout: Layout): void {
       platformMock.mockReturnValue(platform);
@@ -105,6 +220,7 @@ describe("createCallFooterViewModel", () => {
         buildMinimalCallViewModel(layout),
         mockMuteStates(),
         twoMicsAndOneCamMediaDevices,
+        noPipeline,
         /* reactionIdentifier */ undefined,
         { showControls: true, header: HeaderStyle.Standard },
       );
@@ -127,6 +243,7 @@ describe("createCallFooterViewModel", () => {
         buildMinimalCallViewModel(gridLayout),
         mockMuteStates(),
         twoMicsAndOneCamMediaDevices,
+        noPipeline,
         /* reactionIdentifier */ undefined,
         { showControls: true, header: HeaderStyle.Standard },
       );
@@ -158,4 +275,252 @@ describe("createCallFooterViewModel", () => {
       ]);
     });
   });
+
+  describe("background effects", () => {
+    afterEach(() => backgroundEffectSetting.setValue("none"));
+
+    // The lobby, because in a call the whole device switcher is already
+    // withheld on a phone, whatever the verdict says.
+    function lobbyOn(
+      platform: string,
+    ): ReturnType<typeof createLobbyFooterViewModel> {
+      platformMock.mockReturnValue(platform);
+      return createLobbyFooterViewModel(
+        testScope(),
+        mockMuteStates(),
+        twoMicsAndOneCamMediaDevices,
+        pipelineAsTheSdkSays(),
+        /* openSettings */ undefined,
+        /* hangup */ undefined,
+        /* showLogo */ false,
+      );
+    }
+
+    it("offers them on a phone whose browser can run them", () => {
+      sdkSupportMock.mockReturnValue(true);
+      expect(lobbyOn("ios").selectBackgroundEffect$.value).toBeDefined();
+    });
+
+    it("offers them on a desktop whose browser can run them", () => {
+      sdkSupportMock.mockReturnValue(true);
+      expect(lobbyOn("desktop").selectBackgroundEffect$.value).toBeDefined();
+    });
+
+    it("offers nothing where the browser itself cannot run them", () => {
+      sdkSupportMock.mockReturnValue(false);
+      expect(lobbyOn("desktop").selectBackgroundEffect$.value).toBeUndefined();
+      expect(lobbyOn("desktop").addBackgroundImage$.value).toBeUndefined();
+    });
+
+    it("puts no effect in force where the browser cannot run them", () => {
+      backgroundEffectSetting.setValue("blur");
+      sdkSupportMock.mockReturnValue(false);
+      expect(lobbyOn("desktop").backgroundEffect$.value).toBe("none");
+      sdkSupportMock.mockReturnValue(true);
+      expect(lobbyOn("desktop").backgroundEffect$.value).toBe("blur");
+    });
+
+    it("stores the effect chosen", () => {
+      sdkSupportMock.mockReturnValue(true);
+      const vm = lobbyOn("desktop");
+      vm.selectBackgroundEffect$.value?.("image:arc");
+      expect(vm.backgroundEffect$.value).toBe("image:arc");
+      // What isn't an effect on offer is stored as none.
+      vm.selectBackgroundEffect$.value?.("image:gone");
+      expect(backgroundEffectSetting.getValue()).toBe("none");
+    });
+
+    it("says they run slowly where only the slower route exists", () => {
+      sdkSupportMock.mockReturnValue(true);
+      modernRouteMock.mockReturnValue(false);
+      const slow = lobbyOn("desktop");
+      expect(slow.backgroundEffectNotice$.value).toBe("slow");
+      expect(slow.selectBackgroundEffect$.value).toBeDefined();
+      modernRouteMock.mockReturnValue(true);
+      expect(lobbyOn("desktop").backgroundEffectNotice$.value).toBeUndefined();
+    });
+
+    it("offers every effect in order, the added ones removable", () => {
+      sdkSupportMock.mockReturnValue(true);
+      const added$ = addedBackgrounds.added$ as BehaviorSubject<
+        AddedBackground[] | undefined
+      >;
+      added$.next([{ id: "mine", url: "blob:mine" }]);
+      expect(lobbyOn("desktop").backgroundEffects$.value).toEqual([
+        { id: "none", kind: "none", removable: false },
+        { id: "blur", kind: "blur", removable: false },
+        ...shippedBackgrounds.map((background) => ({
+          id: `image:${background.id}`,
+          kind: "image",
+          imageUrl: background.imagePath,
+          removable: false,
+        })),
+        {
+          id: "added:mine",
+          kind: "image",
+          imageUrl: "blob:mine",
+          removable: true,
+        },
+      ]);
+      added$.next([]);
+    });
+
+    it("says they are unavailable where they cannot be chosen", () => {
+      sdkSupportMock.mockReturnValue(false);
+      expect(lobbyOn("desktop").backgroundEffectNotice$.value).toBe(
+        "unavailable",
+      );
+    });
+
+    it("passes on the wait for the first effect", () => {
+      platformMock.mockReturnValue("desktop");
+      const pipeline$ = new BehaviorSubject<BackgroundEffectsState>({
+        supported: true,
+        processor: undefined,
+        settling: true,
+      });
+      const vm = createLobbyFooterViewModel(
+        testScope(),
+        mockMuteStates(),
+        twoMicsAndOneCamMediaDevices,
+        pipeline$,
+        /* openSettings */ undefined,
+        /* hangup */ undefined,
+        /* showLogo */ false,
+      );
+      expect(vm.backgroundEffectSettling$.value).toBe(true);
+      pipeline$.next({ ...pipeline$.value, settling: false });
+      expect(vm.backgroundEffectSettling$.value).toBe(false);
+    });
+
+    it("offers nothing once the pipeline fails to build, keeping the choice", () => {
+      platformMock.mockReturnValue("desktop");
+      backgroundEffectSetting.setValue("blur");
+      const pipeline$ = new BehaviorSubject<BackgroundEffectsState>({
+        supported: true,
+        processor: undefined,
+      });
+      const vm = createLobbyFooterViewModel(
+        testScope(),
+        mockMuteStates(),
+        twoMicsAndOneCamMediaDevices,
+        pipeline$,
+        /* openSettings */ undefined,
+        /* hangup */ undefined,
+        /* showLogo */ false,
+      );
+      expect(vm.backgroundEffect$.value).toBe("blur");
+
+      pipeline$.next({ supported: false, processor: undefined });
+      expect(vm.selectBackgroundEffect$.value).toBeUndefined();
+      expect(vm.addBackgroundImage$.value).toBeUndefined();
+      expect(vm.backgroundEffect$.value).toBe("none");
+      expect(backgroundEffectSetting.getValue()).toBe("blur");
+    });
+
+    it("adding is unavailable at the limit", () => {
+      sdkSupportMock.mockReturnValue(true);
+      const added$ = addedBackgrounds.added$ as BehaviorSubject<
+        AddedBackground[] | undefined
+      >;
+      const vm = lobbyOn("desktop");
+      expect(vm.addBackgroundImage$.value).toBeDefined();
+      added$.next(
+        Array.from({ length: maxAddedBackgrounds }, (_, i) => ({
+          id: `${i}`,
+          url: `blob:${i}`,
+        })),
+      );
+      expect(vm.addBackgroundImage$.value).toBeUndefined();
+      added$.next(added$.value!.slice(1));
+      expect(vm.addBackgroundImage$.value).toBeDefined();
+      added$.next([]);
+    });
+
+    it("says why each refused file was refused", async () => {
+      sdkSupportMock.mockReturnValue(true);
+      const vm = lobbyOn("desktop");
+      store.add.mockRejectedValue(new UnusableImage("animated"));
+      vm.addBackgroundImage$.value!(new File(["x"], "a.gif"));
+      await flushPromises();
+      const first = vm.backgroundImageRefusal$.value;
+      expect(first).toEqual({ reason: "animated" });
+
+      // The same again is a refusal of its own, so it is shown again.
+      vm.addBackgroundImage$.value!(new File(["x"], "a.gif"));
+      await flushPromises();
+      expect(vm.backgroundImageRefusal$.value).toEqual({ reason: "animated" });
+      expect(vm.backgroundImageRefusal$.value).not.toBe(first);
+
+      store.add.mockRejectedValue(new Error("quota"));
+      vm.addBackgroundImage$.value!(new File(["x"], "b.png"));
+      await flushPromises();
+      expect(vm.backgroundImageRefusal$.value).toEqual({ reason: "not-kept" });
+
+      store.add.mockResolvedValue("kept");
+      vm.addBackgroundImage$.value!(new File(["x"], "c.png"));
+      await flushPromises();
+      expect(vm.backgroundImageRefusal$.value).toBeUndefined();
+    });
+
+    it("never removes the background in force", () => {
+      sdkSupportMock.mockReturnValue(true);
+      store.remove.mockResolvedValue();
+      const vm = lobbyOn("desktop");
+      backgroundEffectSetting.setValue("added:worn");
+      vm.removeBackgroundEffect$.value!("added:worn");
+      expect(store.remove).not.toHaveBeenCalled();
+      vm.removeBackgroundEffect$.value!("added:spare");
+      expect(store.remove).toHaveBeenCalledWith("spare");
+    });
+
+    it("previews the camera only while it is on", () => {
+      const camera = new SyncedCameraTrack();
+      const track = {} as LocalVideoTrack;
+      camera.report(track);
+      const videoEnabled$ = new BehaviorSubject(true);
+      const muteStates = mockMuteStates();
+      const vm = createLobbyFooterViewModel(
+        testScope(),
+        {
+          ...muteStates,
+          video: { ...muteStates.video, enabled$: videoEnabled$ },
+        } as unknown as MuteStates,
+        twoMicsAndOneCamMediaDevices,
+        constant({
+          supported: true,
+          processor: undefined,
+          cameraTrack: camera,
+        }),
+        /* openSettings */ undefined,
+        /* hangup */ undefined,
+        /* showLogo */ false,
+      );
+      expect(vm.cameraTrack$.value).toBe(track);
+      videoEnabled$.next(false);
+      expect(vm.cameraTrack$.value).toBeNull();
+    });
+
+    it("availability is the same before and during a call", () => {
+      for (const supported of [true, false]) {
+        sdkSupportMock.mockReturnValue(supported);
+        const lobby = lobbyOn("desktop");
+        const inCall = createCallFooterViewModel(
+          testScope(),
+          buildMinimalCallViewModel(gridLayout),
+          mockMuteStates(),
+          twoMicsAndOneCamMediaDevices,
+          pipelineAsTheSdkSays(),
+          /* reactionIdentifier */ undefined,
+          { showControls: true, header: HeaderStyle.Standard },
+        );
+        const offeredInLobby =
+          lobby.selectBackgroundEffect$.value !== undefined;
+        expect(inCall.selectBackgroundEffect$.value !== undefined).toBe(
+          offeredInLobby,
+        );
+        expect(offeredInLobby).toBe(supported);
+      }
+    });
+  });
 });

src/components/CallFooterViewModel.tsx

@@ -5,14 +5,37 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE in the repository root for full details.
 */
 
-import { combineLatest, map, switchMap } from "rxjs";
-import { supportsBackgroundProcessors } from "@livekit/track-processors";
+import {
+  BehaviorSubject,
+  combineLatest,
+  distinctUntilChanged,
+  map,
+  type Observable,
+  of,
+  switchMap,
+} from "rxjs";
+import { supportsAudioOutputSelection } from "livekit-client";
+import { supportsModernBackgroundProcessors } from "@livekit/track-processors";
+import { logger } from "matrix-js-sdk/lib/logger";
+
+import {
+  parseEffect,
+  serializeEffect,
+  shippedBackgrounds,
+} from "../livekit/backgroundEffects";
+import { type BackgroundEffectsState } from "../livekit/BackgroundEffectsContext";
+import {
+  type AddedBackground,
+  addedBackgrounds,
+  maxAddedBackgrounds,
+  UnusableImage,
+} from "../livekit/backgroundImages";
 
 import { type CallViewModel } from "../state/CallViewModel/CallViewModel";
 import { type MenuOptions } from "./MediaMuteAndSwitchButton";
 import { type MediaDevices } from "../state/MediaDevices";
 import {
-  backgroundBlur as backgroundBlurSettings,
+  backgroundEffect as backgroundEffectSetting,
   debugTileLayout as debugTileLayoutSetting,
 } from "../settings/settings";
 import { type Behavior, constant } from "../state/Behavior";
@@ -21,7 +44,11 @@ import { type MuteStates } from "../state/MuteStates";
 import { createStaticViewModel, type ViewModel } from "../state/ViewModel";
 import { HeaderStyle } from "../UrlParams";
 import { platform } from "../Platform";
-import { type FooterSnapshot } from "./CallFooter";
+import {
+  type BackgroundEffectChoice,
+  type BackgroundImageRefusal,
+  type FooterSnapshot,
+} from "./CallFooter";
 
 /**
  * Shared helper: maps MuteStates into the audio/video enabled + toggle behaviors
@@ -55,77 +82,173 @@ function buildMuteBehaviors(
 
 /**
  * Shared helper: maps MediaDevices into the audio/video device-list behaviors
- * needed by FooterSnapshot (options, selection, callbacks, blur toggle).
+ * needed by FooterSnapshot (options, selection, callbacks, background effect).
  */
 function buildDeviceBehaviors(
   scope: ObservableScope,
   mediaDevices: MediaDevices,
   /** return empty arrays for  audioOptions and videoOptions*/
   disableSwitcher$: Behavior<boolean>,
+  backgroundEffectsState$: Observable<BackgroundEffectsState>,
+  videoEnabled$: Behavior<boolean>,
 ): Pick<
   ViewModel<FooterSnapshot>,
   | "audioOptions$"
   | "selectedAudio$"
   | "selectAudioButtonOption$"
+  | "audioOutputOptions$"
+  | "selectedAudioOutput$"
+  | "selectAudioOutputOption$"
   | "videoOptions$"
   | "selectedVideo$"
   | "selectVideoButtonOption$"
-  | "toggleBlur$"
-  | "videoBlurEnabled$"
+  | "backgroundEffect$"
+  | "selectBackgroundEffect$"
+  | "backgroundEffects$"
+  | "backgroundEffectNotice$"
+  | "backgroundEffectSettling$"
+  | "addBackgroundImage$"
+  | "backgroundImageRefusal$"
+  | "removeBackgroundEffect$"
+  | "cameraTrack$"
 > {
-  return {
-    audioOptions$: scope.behavior(
-      disableSwitcher$.pipe(
-        switchMap((disable) =>
-          disable
-            ? constant([] as MenuOptions[])
-            : mediaDevices.audioInput.available$.pipe(
-                map((available) =>
-                  [...available.entries()].map(([id, label]) => ({
-                    id,
-                    label,
-                  })),
-                ),
+  const options$ = (
+    available$: Behavior<Map<string, MenuOptions["label"]>>,
+  ): Observable<MenuOptions[]> =>
+    disableSwitcher$.pipe(
+      switchMap((disable) =>
+        disable
+          ? constant([] as MenuOptions[])
+          : available$.pipe(
+              map((available) =>
+                [...available.entries()].map(([id, label]) => ({ id, label })),
               ),
-        ),
+            ),
       ),
-    ),
+    );
+
+  // Also false once the pipeline has failed to build this session.
+  const supported$ = backgroundEffectsState$.pipe(
+    map(({ supported }) => supported === true),
+    distinctUntilChanged(),
+  );
+  const slow = !supportsModernBackgroundProcessors();
+  const offered$ = combineLatest([disableSwitcher$, supported$]).pipe(
+    map(([switcherDisabled, supported]) => !switcherDisabled && supported),
+  );
+  // A new object for each refusal, so the same one twice is shown twice.
+  const refusal$ = new BehaviorSubject<BackgroundImageRefusal | undefined>(
+    undefined,
+  );
+  return {
+    audioOptions$: scope.behavior(options$(mediaDevices.audioInput.available$)),
     selectedAudio$: scope.behavior(
       mediaDevices.audioInput.selected$.pipe(map((s) => s?.id)),
     ),
     selectAudioButtonOption$: constant(mediaDevices.audioInput.select),
-    videoOptions$: scope.behavior(
-      disableSwitcher$.pipe(
-        switchMap((disable) =>
-          disable
-            ? constant([] as MenuOptions[])
-            : mediaDevices.videoInput.available$.pipe(
-                map((available) =>
-                  [...available.entries()].map(([id, label]) => ({
-                    id,
-                    label,
-                  })),
-                ),
-              ),
-        ),
-      ),
+    audioOutputOptions$: scope.behavior(
+      options$(mediaDevices.audioOutput.available$),
     ),
+    selectedAudioOutput$: scope.behavior(
+      mediaDevices.audioOutput.selected$.pipe(map((s) => s?.id)),
+    ),
+    // Withheld where the platform can't route audio to a chosen device, which
+    // disables the speaker section.
+    selectAudioOutputOption$: constant(
+      supportsAudioOutputSelection()
+        ? mediaDevices.audioOutput.select
+        : undefined,
+    ),
+    videoOptions$: scope.behavior(options$(mediaDevices.videoInput.available$)),
     selectedVideo$: scope.behavior(
       mediaDevices.videoInput.selected$.pipe(map((s) => s?.id)),
     ),
     selectVideoButtonOption$: constant(mediaDevices.videoInput.select),
-    toggleBlur$: scope.behavior(
-      combineLatest([backgroundBlurSettings.value$, disableSwitcher$]).pipe(
-        map(([current, switcherDisabled]) => {
-          return !switcherDisabled && supportsBackgroundProcessors()
-            ? (): void => {
-                backgroundBlurSettings.setValue(!current);
+    backgroundEffect$: scope.behavior(
+      combineLatest([backgroundEffectSetting.value$, supported$]).pipe(
+        map(([raw, supported]) =>
+          supported ? serializeEffect(parseEffect(raw)) : "none",
+        ),
+      ),
+    ),
+    selectBackgroundEffect$: scope.behavior(
+      offered$.pipe(
+        map((offered) =>
+          offered
+            ? (id: string): void =>
+                backgroundEffectSetting.setValue(
+                  serializeEffect(parseEffect(id)),
+                )
+            : undefined,
+        ),
+      ),
+    ),
+    backgroundEffects$: scope.behavior(
+      addedBackgrounds.added$.pipe(
+        map((added) => backgroundEffectChoices(added ?? [])),
+      ),
+    ),
+    backgroundEffectNotice$: scope.behavior(
+      offered$.pipe(
+        map((offered) =>
+          !offered ? "unavailable" : slow ? "slow" : undefined,
+        ),
+      ),
+    ),
+    backgroundEffectSettling$: scope.behavior(
+      backgroundEffectsState$.pipe(
+        map(({ settling }) => settling ?? false),
+        distinctUntilChanged(),
+      ),
+      false,
+    ),
+    // Kept and offered, not put on: that waits for the user to choose it.
+    addBackgroundImage$: scope.behavior(
+      combineLatest([offered$, addedBackgrounds.added$]).pipe(
+        map(([offered, added]) =>
+          offered && (added?.length ?? 0) < maxAddedBackgrounds
+            ? (file: File): void => {
+                refusal$.next(undefined);
+                addedBackgrounds.add(file).catch((e) => {
+                  logger.warn("Could not keep that background", e);
+                  refusal$.next({
+                    reason: e instanceof UnusableImage ? e.reason : "not-kept",
+                  });
+                });
               }
-            : undefined;
-        }),
+            : undefined,
+        ),
+      ),
+    ),
+    backgroundImageRefusal$: refusal$,
+    cameraTrack$: scope.behavior(
+      combineLatest([
+        backgroundEffectsState$.pipe(
+          switchMap(({ cameraTrack }) => cameraTrack?.track$ ?? of(null)),
+        ),
+        videoEnabled$,
+      ]).pipe(map(([track, videoEnabled]) => (videoEnabled ? track : null))),
+      null,
+    ),
+    // Never the one in force: taking it away would leave nothing chosen.
+    removeBackgroundEffect$: scope.behavior(
+      offered$.pipe(
+        map((offered) =>
+          offered
+            ? (optionId: string): void => {
+                const effect = parseEffect(optionId);
+                if (effect.kind !== "added") return;
+                if (backgroundEffectSetting.getValue() === optionId) return;
+                addedBackgrounds
+                  .remove(effect.id)
+                  .catch((e) =>
+                    logger.warn("Could not remove that background", e),
+                  );
+              }
+            : undefined,
+        ),
       ),
     ),
-    videoBlurEnabled$: backgroundBlurSettings.value$,
   };
 }
 
@@ -136,6 +259,8 @@ function buildDeviceBehaviors(
  * @param callModel - The root CallViewModel; provides layout, grid mode, reactions, etc.
  * @param muteStates - Audio and video mute state + toggles.
  * @param mediaDevices - Available and selected input devices.
+ * @param backgroundEffectsState$ - The background pipeline's state: whether effects
+ *   run here, the wait for the first, and the camera it is synced to.
  * @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.
@@ -146,6 +271,7 @@ export function createCallFooterViewModel(
   callModel: CallViewModel,
   muteStates: MuteStates,
   mediaDevices: MediaDevices,
+  backgroundEffectsState$: Observable<BackgroundEffectsState>,
   reactionIdentifier: string | undefined,
   options: { showControls: boolean; header: HeaderStyle },
 ): ViewModel<FooterSnapshot> {
@@ -160,7 +286,13 @@ export function createCallFooterViewModel(
   );
   return {
     ...buildMuteBehaviors(scope, muteStates),
-    ...buildDeviceBehaviors(scope, mediaDevices, disableDeviceSwitcher$),
+    ...buildDeviceBehaviors(
+      scope,
+      mediaDevices,
+      disableDeviceSwitcher$,
+      backgroundEffectsState$,
+      muteStates.video.enabled$,
+    ),
     // candidat to move into the FooterViewModel
     showFooter$: callModel.showFooter$,
     hideControls$: constant(!showControls),
@@ -222,6 +354,8 @@ export function createCallFooterViewModel(
  * @param scope - ObservableScope that bounds the lifetime of derived behaviors.
  * @param muteStates - Audio and video mute state + toggles.
  * @param mediaDevices - Available and selected input devices.
+ * @param backgroundEffectsState$ - The background pipeline's state: whether effects
+ *   run here, the wait for the first, and the camera it is synced to.
  * @param openSettings - Callback to open the settings modal, or undefined.
  * @param hangup - Callback to leave/cancel, or undefined (hides the button).
  * @param showLogo - Whether to show the Element Call logo.
@@ -230,6 +364,7 @@ export function createLobbyFooterViewModel(
   scope: ObservableScope,
   muteStates: MuteStates,
   mediaDevices: MediaDevices,
+  backgroundEffectsState$: Observable<BackgroundEffectsState>,
   openSettings: (() => void) | undefined,
   hangup: (() => void) | undefined,
   showLogo: boolean,
@@ -263,13 +398,43 @@ export function createLobbyFooterViewModel(
       reactionData: undefined,
       tileStoreGeneration: undefined,
       audioOptions: undefined,
+      audioOutputOptions: undefined,
       videoOptions: undefined,
       selectedAudio: undefined,
+      selectedAudioOutput: undefined,
       selectedVideo: undefined,
       selectAudioButtonOption: undefined,
+      selectAudioOutputOption: undefined,
       selectVideoButtonOption: undefined,
     }),
     ...buildMuteBehaviors(scope, muteStates),
-    ...buildDeviceBehaviors(scope, mediaDevices, constant(false)),
+    ...buildDeviceBehaviors(
+      scope,
+      mediaDevices,
+      constant(false),
+      backgroundEffectsState$,
+      muteStates.video.enabled$,
+    ),
   };
 }
+
+function backgroundEffectChoices(
+  added: AddedBackground[],
+): BackgroundEffectChoice[] {
+  return [
+    { id: serializeEffect({ kind: "none" }), kind: "none", removable: false },
+    { id: serializeEffect({ kind: "blur" }), kind: "blur", removable: false },
+    ...shippedBackgrounds.map((background) => ({
+      id: serializeEffect({ kind: "shipped", id: background.id }),
+      kind: "image" as const,
+      imageUrl: background.imagePath,
+      removable: false,
+    })),
+    ...added.map((background) => ({
+      id: serializeEffect({ kind: "added", id: background.id }),
+      kind: "image" as const,
+      imageUrl: background.url,
+      removable: true,
+    })),
+  ];
+}

src/components/MediaMuteAndSwitchButton.module.css

@@ -35,3 +35,129 @@ Please see LICENSE in the repository root for full details.
     transform: rotate(360deg);
   }
 }
+
+/* The width design sets: a long device name wraps. */
+.menu {
+  inline-size: 296px;
+}
+
+/* Its share of the measured call area: the menu is portalled out of the root,
+   so CSS can't size it against the call. */
+.deviceList {
+  max-block-size: var(--device-list-max-height);
+  /* The raised headings stay raised within the list, under the menu's frame. */
+  isolation: isolate;
+  /* Keeps a row reached by keyboard clear of the sticky heading. */
+  scroll-padding-block-start: var(--device-list-scroll-padding-start, 0);
+}
+
+/* Compound's heading rule heads each section; the design adds space below it. */
+.menu h3 {
+  margin-block-end: var(--cpd-space-5x);
+}
+
+/* And more above a heading that follows another section. */
+.deviceList [role="group"] + [role="group"] h3 {
+  margin-block-start: var(--cpd-space-7x);
+}
+
+/* Sticky within its own section: opaque, so rows scroll under it, and raised,
+   or the positioned tiles scroll over it. */
+.sectionHeading {
+  position: sticky;
+  z-index: 1;
+  inset-block-start: 0;
+  background: var(--cpd-color-bg-canvas-default);
+}
+
+/* Sticky at the foot of the microphone section; opaque as above. */
+.stickyMeter {
+  position: sticky;
+  inset-block-end: 0;
+  background: var(--cpd-color-bg-canvas-default);
+}
+
+/* Fills the band between the meter and the frame, or rows show through it. */
+.stickyMeter::after {
+  content: "";
+  position: absolute;
+  inset-inline: 0;
+  inset-block-start: 100%;
+  block-size: var(--cpd-menu-padding-block-end, 0px);
+  background: var(--cpd-color-bg-canvas-default);
+}
+
+/* Not Compound's fade: that stays at the edge while a bounce carries the meter.
+   This one starts at the chevron, below the meter at rest. */
+.deviceList.deviceListWithMeter[data-more-below] {
+  mask-image: linear-gradient(
+    to bottom,
+    #000 calc(100% - var(--cpd-space-6x)),
+    transparent calc(100% - var(--cpd-space-3x))
+  );
+}
+
+/* Radix focuses whatever the pointer is over, so the browser's ring would
+   follow the mouse. Replaced by one shown only for keyboard focus. */
+.menu [role^="menuitem"]:focus,
+.menu [role^="menuitem"]:focus-visible {
+  outline: none;
+}
+
+.menu[data-focus-source="keyboard"] [role^="menuitem"]:focus {
+  outline: var(--cpd-border-width-2) solid var(--cpd-color-border-focused);
+  outline-offset: calc(-1 * var(--cpd-border-width-2));
+}
+
+.notice {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--cpd-space-3x);
+  margin: var(--cpd-space-2x) var(--cpd-space-4x) 0;
+  padding: var(--cpd-space-3x);
+  border-radius: var(--cpd-space-2x);
+  background: var(--cpd-color-bg-subtle-secondary);
+  color: var(--cpd-color-text-primary);
+  font: var(--cpd-font-body-md-regular);
+}
+
+.notice > svg {
+  flex-shrink: 0;
+  color: var(--cpd-color-icon-secondary);
+}
+
+.refusal {
+  margin: var(--cpd-space-2x) var(--cpd-space-4x) 0;
+}
+
+.selfPreview {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  aspect-ratio: 16 / 9;
+  margin-block-end: var(--cpd-space-2x);
+  overflow: clip;
+  border-start-start-radius: var(--cpd-space-3x);
+  border-start-end-radius: var(--cpd-space-3x);
+  background: var(--cpd-color-bg-subtle-secondary);
+  color: var(--cpd-color-icon-secondary);
+}
+
+.selfPreview > video {
+  position: absolute;
+  inset: 0;
+  inline-size: 100%;
+  block-size: 100%;
+  object-fit: cover;
+  /* Rounded itself too: a video can be drawn on a layer of its own, which the
+     frame's rounded clip doesn't always reach. */
+  border-radius: inherit;
+}
+
+/* Up to the menu's frame, over the padding at its top. */
+.selfPreviewPinned,
+.deviceListLeadsWithPreview {
+  margin-block-start: calc(-1 * var(--cpd-space-5x));
+}

src/components/MediaMuteAndSwitchButton.test.tsx

@@ -5,40 +5,70 @@ 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, describe, expect, onTestFinished, test, vi } from "vitest";
+import { axe } from "vitest-axe";
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  within,
+  type RenderResult,
+} from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
-import { type JSX, useState, type ReactNode } from "react";
+import { Profiler, type JSX, useState, type ReactNode } from "react";
 import { TooltipProvider } from "@vector-im/compound-web";
 
-import { MediaMuteAndSwitchButton } from "./MediaMuteAndSwitchButton";
+import {
+  MediaMuteAndSwitchButton,
+  type MenuOptions,
+} from "./MediaMuteAndSwitchButton";
+import { type BackgroundEffectOption } from "./BackgroundEffectGrid";
 import { MediaDevicesContext } from "../MediaDevicesContext";
 import { type MediaDevices } from "../state/MediaDevices";
+import { restoreAudioCapture, stubAudioCapture } from "../utils/test";
+
+const effects: BackgroundEffectOption[] = [
+  { id: "none", kind: "none", label: "None" },
+  { id: "blur", kind: "blur", label: "Blur" },
+  { id: "image:arc", kind: "image", label: "Background 1", imageUrl: "" },
+  { id: "image:glow", kind: "image", label: "Background 2", imageUrl: "" },
+];
 
 interface RenderOptions {
   requestDeviceNames: () => void;
 }
 
-function renderComponent(
+function withProviders(
   component: ReactNode,
   { requestDeviceNames = (): void => {} }: Partial<RenderOptions> = {},
-): RenderResult {
-  return render(
+): JSX.Element {
+  return (
     <TooltipProvider>
       <MediaDevicesContext
         value={{ requestDeviceNames } as unknown as MediaDevices}
       >
         {component}
       </MediaDevicesContext>
-    </TooltipProvider>,
+    </TooltipProvider>
   );
 }
 
+function renderComponent(
+  component: ReactNode,
+  options: Partial<RenderOptions> = {},
+): RenderResult {
+  return render(withProviders(component, options));
+}
+
 describe("MediaMuteAndSwitchButton", () => {
+  // Only one test stubs the capture; don't let it leak into the rest.
+  afterEach(restoreAudioCapture);
+
   test("renders", () => {
     const { container } = renderComponent(
       <TooltipProvider>
-        <MediaMuteAndSwitchButton title={"Switcher"} iconsAndLabels={"audio"} />
+        <MediaMuteAndSwitchButton iconsAndLabels={"audio"} />
       </TooltipProvider>,
     );
     expect(container).toMatchSnapshot();
@@ -50,11 +80,7 @@ describe("MediaMuteAndSwitchButton", () => {
       enabled: boolean,
     ): RenderResult => {
       return renderComponent(
-        <MediaMuteAndSwitchButton
-          title={"Switcher"}
-          iconsAndLabels={type}
-          enabled={enabled}
-        />,
+        <MediaMuteAndSwitchButton iconsAndLabels={type} enabled={enabled} />,
       );
     };
     const renderAudioEndabled = renderLabels("audio", true);
@@ -81,7 +107,6 @@ describe("MediaMuteAndSwitchButton", () => {
     const onMute = vi.fn();
     const { getByRole } = renderComponent(
       <MediaMuteAndSwitchButton
-        title={"Switcher"}
         onMuteClick={onMute}
         iconsAndLabels="audio"
         enabled={true}
@@ -98,7 +123,6 @@ describe("MediaMuteAndSwitchButton", () => {
     const onMute = vi.fn();
     const { getByRole } = renderComponent(
       <MediaMuteAndSwitchButton
-        title={"Switcher"}
         onMuteClick={onMute}
         iconsAndLabels="audio"
         enabled={true}
@@ -119,7 +143,6 @@ describe("MediaMuteAndSwitchButton", () => {
     const onMute = vi.fn();
     const { getByRole } = renderComponent(
       <MediaMuteAndSwitchButton
-        title={"Switcher"}
         onMuteClick={onMute}
         iconsAndLabels="video"
         enabled={true}
@@ -139,11 +162,7 @@ describe("MediaMuteAndSwitchButton", () => {
     const user = userEvent.setup();
     const requestDeviceNames = vi.fn();
     renderComponent(
-      <MediaMuteAndSwitchButton
-        title="Switcher"
-        iconsAndLabels="audio"
-        enabled
-      />,
+      <MediaMuteAndSwitchButton iconsAndLabels="audio" enabled />,
       { requestDeviceNames },
     );
 
@@ -157,7 +176,6 @@ describe("MediaMuteAndSwitchButton", () => {
     renderComponent(
       <>
         <MediaMuteAndSwitchButton
-          title="Switcher"
           iconsAndLabels="audio"
           enabled
           options={[
@@ -167,7 +185,6 @@ describe("MediaMuteAndSwitchButton", () => {
           selectedOption="mic1"
         />
         <MediaMuteAndSwitchButton
-          title="Switcher"
           iconsAndLabels="video"
           enabled
           options={[
@@ -193,7 +210,6 @@ describe("MediaMuteAndSwitchButton", () => {
     const onSelect = vi.fn();
     const { getByRole } = renderComponent(
       <MediaMuteAndSwitchButton
-        title="Switcher"
         iconsAndLabels="audio"
         enabled={true}
         options={[
@@ -217,7 +233,6 @@ describe("MediaMuteAndSwitchButton", () => {
     const onSelect = vi.fn();
     const { getByRole } = renderComponent(
       <MediaMuteAndSwitchButton
-        title="Switcher"
         iconsAndLabels="audio"
         enabled={true}
         options={[
@@ -246,7 +261,6 @@ describe("MediaMuteAndSwitchButton", () => {
       const [selectedOption, setSelectedOption] = useState("mic1");
       return (
         <MediaMuteAndSwitchButton
-          title="Switcher"
           iconsAndLabels="audio"
           enabled={true}
           options={[
@@ -300,38 +314,209 @@ describe("MediaMuteAndSwitchButton", () => {
     expect(mic2ItemAfter.querySelector(".rotate")).toBeNull();
   });
 
-  test("renders menu with toggle control and calls toggle callback", async () => {
+  test("background effects are one keyboard-operable labelled choice", async () => {
     const user = userEvent.setup();
-    const onSelect = vi.fn();
-    const onVideoBlurToggle = vi.fn();
+    const onSelectBackgroundEffect = vi.fn();
     const { getByRole } = renderComponent(
       <MediaMuteAndSwitchButton
-        title="Switcher"
         iconsAndLabels="video"
         enabled={true}
-        videoBlurToggleClick={onVideoBlurToggle}
-        onSelect={onSelect}
+        options={[{ label: { type: "name", name: "Camera 1" }, id: "cam1" }]}
+        selectedOption="cam1"
+        onSelect={vi.fn()}
+        backgroundEffects={effects}
+        selectedBackgroundEffect="none"
+        onSelectBackgroundEffect={onSelectBackgroundEffect}
       />,
     );
 
     await user.click(getByRole("button", { name: "Camera" }));
-
-    const toggle = screen.getByRole("menuitemcheckbox", {
-      name: "Blur background",
+    const section = screen.getByRole("group", { name: "Background effects" });
+    within(section).getByRole("menuitemradio", { name: "None", checked: true });
+    within(section).getByRole("menuitemradio", {
+      name: "Background 1",
+      checked: false,
     });
-    expect(toggle).toBeInTheDocument();
-    expect(toggle).toHaveAttribute("aria-checked", "false");
 
-    await user.click(toggle);
-
-    expect(onVideoBlurToggle).toHaveBeenCalled();
+    const blur = within(section).getByRole("menuitemradio", { name: "Blur" });
+    for (let i = 0; i < 6 && document.activeElement !== blur; i++)
+      await user.keyboard("{ArrowDown}");
+    expect(document.activeElement).toBe(blur);
+    await user.keyboard("{Enter}");
+    expect(onSelectBackgroundEffect).toHaveBeenCalledWith("blur");
+    expect(screen.getByRole("menu")).toBeInTheDocument();
   });
 
-  test("renders check icon to mark the selected menu item", async () => {
+  test("does not choose the effect already in force again", async () => {
+    const user = userEvent.setup();
+    const onSelectBackgroundEffect = vi.fn();
+    const { getByRole } = renderComponent(
+      <MediaMuteAndSwitchButton
+        iconsAndLabels="video"
+        enabled={true}
+        options={[{ label: { type: "name", name: "Camera 1" }, id: "cam1" }]}
+        selectedOption="cam1"
+        backgroundEffects={effects}
+        selectedBackgroundEffect="blur"
+        onSelectBackgroundEffect={onSelectBackgroundEffect}
+      />,
+    );
+
+    await user.click(getByRole("button", { name: "Camera" }));
+    await user.click(screen.getByRole("menuitemradio", { name: "Blur" }));
+    expect(onSelectBackgroundEffect).not.toHaveBeenCalled();
+  });
+
+  test("added images are chosen like shipped ones", async () => {
+    const user = userEvent.setup();
+    const onSelectBackgroundEffect = vi.fn();
+    const { getByRole } = renderComponent(
+      <MediaMuteAndSwitchButton
+        iconsAndLabels="video"
+        enabled={true}
+        options={[{ label: { type: "name", name: "Camera 1" }, id: "cam1" }]}
+        selectedOption="cam1"
+        backgroundEffects={[
+          ...effects,
+          {
+            id: "added:mine",
+            kind: "image",
+            label: "Background 3",
+            imageUrl: "",
+          },
+        ]}
+        selectedBackgroundEffect="none"
+        onSelectBackgroundEffect={onSelectBackgroundEffect}
+      />,
+    );
+
+    await user.click(getByRole("button", { name: "Camera" }));
+    const section = screen.getByRole("group", { name: "Background effects" });
+    await user.click(
+      within(section).getByRole("menuitemradio", { name: "Background 3" }),
+    );
+    expect(onSelectBackgroundEffect).toHaveBeenCalledWith("added:mine");
+  });
+
+  test("adds the file chosen from the add tile, and stays open", async () => {
+    const user = userEvent.setup();
+    const onAddBackgroundImage = vi.fn();
+    const pick = vi
+      .spyOn(HTMLInputElement.prototype, "click")
+      .mockImplementation(() => {});
+    try {
+      const { getByRole, container } = renderComponent(
+        <MediaMuteAndSwitchButton
+          iconsAndLabels="video"
+          enabled={true}
+          options={[{ label: { type: "name", name: "Camera 1" }, id: "cam1" }]}
+          selectedOption="cam1"
+          backgroundEffects={effects}
+          selectedBackgroundEffect="none"
+          onSelectBackgroundEffect={vi.fn()}
+          onAddBackgroundImage={onAddBackgroundImage}
+        />,
+      );
+
+      await user.click(getByRole("button", { name: "Camera" }));
+      await user.click(screen.getByRole("menuitem", { name: "Add image" }));
+      expect(pick).toHaveBeenCalled();
+      // The picker takes the focus, which would otherwise close the menu.
+      await user.keyboard("{Escape}");
+      expect(screen.getByRole("menu")).toBeInTheDocument();
+
+      const file = new File(["x"], "mine.png", { type: "image/png" });
+      // What the picker hands back; the open menu blocks pointer events.
+      fireEvent.change(
+        container.querySelector<HTMLInputElement>("input[type=file]")!,
+        { target: { files: [file] } },
+      );
+      expect(onAddBackgroundImage).toHaveBeenCalledWith(file);
+      screen.getByRole("menuitemradio", { name: "None", checked: true });
+    } finally {
+      pick.mockRestore();
+    }
+  });
+
+  test("a refusal can be dismissed and does not outlive the menu", async () => {
+    const user = userEvent.setup();
+    // jsdom lays nothing out, so has nothing to scroll.
+    const scroll = Element.prototype.scrollIntoView;
+    Element.prototype.scrollIntoView = vi.fn();
+    onTestFinished(() => {
+      Element.prototype.scrollIntoView = scroll;
+    });
+    const menu = (refusal?: { text: string }): JSX.Element =>
+      withProviders(
+        <MediaMuteAndSwitchButton
+          iconsAndLabels="video"
+          enabled={true}
+          options={[{ label: { type: "name", name: "Camera 1" }, id: "cam1" }]}
+          selectedOption="cam1"
+          backgroundEffects={effects}
+          selectedBackgroundEffect="blur"
+          onSelectBackgroundEffect={vi.fn()}
+          onAddBackgroundImage={vi.fn()}
+          backgroundImageRefusal={refusal}
+        />,
+      );
+    const { rerender, getByRole } = render(menu());
+    await user.click(getByRole("button", { name: "Camera" }));
+
+    rerender(menu({ text: "That file is not a supported image" }));
+    expect(
+      screen.getByText("That file is not a supported image"),
+    ).toBeVisible();
+    screen.getByRole("menuitemradio", { name: "Blur", checked: true });
+    await user.click(screen.getByRole("button", { name: "Close" }));
+    expect(screen.queryByText("That file is not a supported image")).toBeNull();
+
+    // The next refusal is shown, even if it says the same.
+    rerender(menu({ text: "That file is not a supported image" }));
+    expect(
+      screen.getByText("That file is not a supported image"),
+    ).toBeVisible();
+
+    await user.keyboard("{Escape}");
+    await user.click(getByRole("button", { name: "Camera" }));
+    expect(screen.queryByText("That file is not a supported image")).toBeNull();
+  });
+
+  test("offers the background effects in a phone's drawer", async () => {
+    const userAgent = vi
+      .spyOn(navigator, "userAgent", "get")
+      .mockReturnValue("Mozilla/5.0 (Linux; Android 14)");
+    try {
+      const user = userEvent.setup();
+      const onSelectBackgroundEffect = vi.fn();
+      const { getByRole } = renderComponent(
+        <MediaMuteAndSwitchButton
+          iconsAndLabels="video"
+          enabled={true}
+          options={[{ label: { type: "name", name: "Camera 1" }, id: "cam1" }]}
+          selectedOption="cam1"
+          backgroundEffects={effects}
+          selectedBackgroundEffect="none"
+          onSelectBackgroundEffect={onSelectBackgroundEffect}
+        />,
+      );
+
+      await user.click(getByRole("button", { name: "Camera" }));
+      const section = screen.getByRole("group", { name: "Background effects" });
+      // A click alone: the drawer's drag handling reads layout jsdom lacks.
+      fireEvent.click(
+        within(section).getByRole("menuitemradio", { name: "Background 2" }),
+      );
+      expect(onSelectBackgroundEffect).toHaveBeenCalledWith("image:glow");
+    } finally {
+      userAgent.mockRestore();
+    }
+  });
+
+  test("marks the selected menu item as checked", async () => {
     const user = userEvent.setup();
     const { getByRole } = renderComponent(
       <MediaMuteAndSwitchButton
-        title="Switcher"
         iconsAndLabels="audio"
         enabled={true}
         options={[
@@ -342,19 +527,496 @@ describe("MediaMuteAndSwitchButton", () => {
       />,
     );
 
-    // open menu
     await user.click(getByRole("button", { name: "Microphone" }));
 
-    // The selected item (mic2) renders both an IconOptions SVG and a CheckIcon SVG
-    const mic1Item = screen.getByRole("menuitemradio", {
-      name: "Microphone 2",
-    });
-    expect(mic1Item.querySelectorAll("svg").length).toBe(2);
+    screen.getByRole("menuitemradio", { name: "Microphone 2", checked: true });
+    screen.getByRole("menuitemradio", { name: "Microphone 1", checked: false });
+  });
 
-    // The unselected item (mic1) only renders its IconOptions SVG
-    const mic2Item = screen.getByRole("menuitemradio", {
+  test("disables every device while a selection is settling", async () => {
+    const user = userEvent.setup();
+    const { promise, resolve } = Promise.withResolvers<void>();
+    function Wrapper(): JSX.Element {
+      const [selectedOption, setSelectedOption] = useState("mic1");
+      return (
+        <MediaMuteAndSwitchButton
+          iconsAndLabels="audio"
+          enabled={true}
+          options={[
+            { label: { type: "name", name: "Microphone 1" }, id: "mic1" },
+            { label: { type: "name", name: "Microphone 2" }, id: "mic2" },
+          ]}
+          selectedOption={selectedOption}
+          onSelect={(id) => {
+            void promise.then(() => setSelectedOption(id));
+          }}
+          outputOptions={[
+            { label: { type: "name", name: "Speakers" }, id: "spk1" },
+            { label: { type: "name", name: "Headset" }, id: "spk2" },
+          ]}
+          selectedOutputOption="spk1"
+          onSelectOutput={vi.fn()}
+        />
+      );
+    }
+
+    const { getByRole } = renderComponent(<Wrapper />);
+    await user.click(getByRole("button", { name: "Microphone" }));
+    await user.click(
+      screen.getByRole("menuitemradio", { name: "Microphone 2" }),
+    );
+
+    // In flight: nothing else can be picked, in either section.
+    for (const name of ["Microphone 1", "Speakers", "Headset"]) {
+      expect(screen.getByRole("menuitemradio", { name })).toHaveAttribute(
+        "aria-disabled",
+        "true",
+      );
+    }
+
+    await act(async () => {
+      resolve();
+      await promise;
+    });
+
+    // Settled: selectable again.
+    expect(
+      screen.getByRole("menuitemradio", { name: "Microphone 1" }),
+    ).not.toHaveAttribute("aria-disabled", "true");
+    expect(
+      screen.getByRole("menuitemradio", { name: "Headset" }),
+    ).not.toHaveAttribute("aria-disabled", "true");
+  });
+
+  test("lets go of a device switch that never arrives", async () => {
+    const user = userEvent.setup();
+    // onSelect never reports back, as when a device is removed mid-switch.
+    const { getByRole } = renderComponent(
+      <MediaMuteAndSwitchButton
+        iconsAndLabels="audio"
+        enabled={true}
+        options={[
+          { label: { type: "name", name: "Microphone 1" }, id: "mic1" },
+          { label: { type: "name", name: "Microphone 2" }, id: "mic2" },
+        ]}
+        selectedOption="mic1"
+        onSelect={vi.fn()}
+        outputOptions={[
+          { label: { type: "name", name: "Speakers" }, id: "spk1" },
+          { label: { type: "name", name: "Headset" }, id: "spk2" },
+        ]}
+        selectedOutputOption="spk1"
+        onSelectOutput={vi.fn()}
+      />,
+    );
+
+    await user.click(getByRole("button", { name: "Microphone" }));
+    await user.click(
+      screen.getByRole("menuitemradio", { name: "Microphone 2" }),
+    );
+    await user.keyboard("{Escape}");
+    await user.click(getByRole("button", { name: "Microphone" }));
+
+    for (const name of ["Microphone 1", "Speakers", "Headset"]) {
+      expect(screen.getByRole("menuitemradio", { name })).not.toHaveAttribute(
+        "aria-disabled",
+        "true",
+      );
+    }
+  });
+
+  test("lets go of a device switch whose device is unplugged", async () => {
+    const user = userEvent.setup();
+    const mics: MenuOptions[] = [
+      { label: { type: "name", name: "Microphone 1" }, id: "mic1" },
+      { label: { type: "name", name: "Microphone 2" }, id: "mic2" },
+    ];
+    const menu = (options: MenuOptions[]): JSX.Element => (
+      <MediaMuteAndSwitchButton
+        iconsAndLabels="audio"
+        enabled={true}
+        options={options}
+        selectedOption="mic1"
+        onSelect={vi.fn()}
+        outputOptions={[
+          { label: { type: "name", name: "Speakers" }, id: "spk1" },
+          { label: { type: "name", name: "Headset" }, id: "spk2" },
+        ]}
+        selectedOutputOption="spk1"
+        onSelectOutput={vi.fn()}
+      />
+    );
+
+    const { getByRole, rerender } = renderComponent(menu(mics));
+    await user.click(getByRole("button", { name: "Microphone" }));
+    await user.click(
+      screen.getByRole("menuitemradio", { name: "Microphone 2" }),
+    );
+
+    // The second microphone is unplugged before the switch lands.
+    rerender(withProviders(menu(mics.slice(0, 1))));
+
+    // Selectable again without closing the menu.
+    expect(
+      screen.getByRole("menuitemradio", { name: "Headset" }),
+    ).not.toHaveAttribute("aria-disabled", "true");
+  });
+
+  test("moves the level without re-rendering anything", async () => {
+    // The level is drawn into the DOM, so a moving level commits nothing.
+    const capture = stubAudioCapture();
+    const user = userEvent.setup();
+    let commits = 0;
+
+    const { getByRole } = renderComponent(
+      <Profiler
+        id="menu"
+        onRender={(): void => {
+          commits++;
+        }}
+      >
+        <MediaMuteAndSwitchButton
+          iconsAndLabels="audio"
+          enabled={true}
+          options={[
+            { label: { type: "name", name: "Microphone 1" }, id: "mic1" },
+            { label: { type: "name", name: "Microphone 2" }, id: "mic2" },
+          ]}
+          selectedOption="mic1"
+          onSelect={vi.fn()}
+          outputOptions={[
+            { label: { type: "name", name: "Speakers" }, id: "spk1" },
+            { label: { type: "name", name: "Headset" }, id: "spk2" },
+          ]}
+          selectedOutputOption="spk1"
+          onSelectOutput={vi.fn()}
+        />
+      </Profiler>,
+    );
+
+    await user.click(getByRole("button", { name: "Microphone" }));
+    capture.grant();
+    await vi.waitFor(() => expect(capture.contexts).toHaveLength(1));
+    const meter = await screen.findByRole("meter");
+    // The capture's arrival is one render: the idle level swapped for its own.
+    await act(async () => {});
+    const settled = commits;
+
+    // The meter smooths by elapsed time, so hand-driven frames need a clock.
+    let elapsed = performance.now();
+    const clock = vi
+      .spyOn(performance, "now")
+      .mockImplementation(() => (elapsed += 16));
+
+    // One frame per task, as a browser delivers them: one act() would batch them.
+    for (let step = 1; step <= 8; step++) {
+      capture.speak(step / 8);
+      await act(async () => {
+        capture.drawFrames(1);
+        await Promise.resolve();
+      });
+    }
+    clock.mockRestore();
+
+    expect(meter.getAttribute("aria-valuenow")).not.toBe("0");
+    expect(commits - settled).toBe(0);
+  });
+
+  test("camera menu uses the same selection pattern and keeps the blur toggle", async () => {
+    const user = userEvent.setup();
+    const { getByRole } = renderComponent(
+      <MediaMuteAndSwitchButton
+        iconsAndLabels="video"
+        enabled={true}
+        options={[
+          { label: { type: "name", name: "Camera 1" }, id: "cam1" },
+          { label: { type: "name", name: "Camera 2" }, id: "cam2" },
+        ]}
+        selectedOption="cam1"
+        onSelect={vi.fn()}
+        backgroundEffects={effects}
+        selectedBackgroundEffect="none"
+        onSelectBackgroundEffect={vi.fn()}
+      />,
+    );
+
+    await user.click(getByRole("button", { name: "Camera" }));
+
+    screen.getByRole("menuitemradio", { name: "Camera 1", checked: true });
+    screen.getByRole("menuitemradio", { name: "Camera 2", checked: false });
+    within(screen.getByRole("group", { name: "Background effects" })).getByRole(
+      "menuitemradio",
+      { name: "Blur" },
+    );
+  });
+
+  test("marks focus as keyboard-driven only when the keyboard moved it", async () => {
+    const user = userEvent.setup();
+    const { getByRole } = renderComponent(
+      <MediaMuteAndSwitchButton
+        iconsAndLabels="audio"
+        enabled={true}
+        options={[
+          { label: { type: "name", name: "Microphone 1" }, id: "mic1" },
+          { label: { type: "name", name: "Microphone 2" }, id: "mic2" },
+        ]}
+        selectedOption="mic1"
+        onSelect={vi.fn()}
+      />,
+    );
+
+    await user.click(getByRole("button", { name: "Microphone" }));
+    const list = screen
+      .getByRole("menuitemradio", { name: "Microphone 1" })
+      .closest("[data-focus-source]");
+
+    // The menu focuses whatever the pointer is over, so focus alone says nothing.
+    expect(list).toHaveAttribute("data-focus-source", "pointer");
+
+    await user.keyboard("{ArrowDown}");
+    expect(list).toHaveAttribute("data-focus-source", "keyboard");
+
+    await user.pointer({
+      target: screen.getByRole("menuitemradio", { name: "Microphone 2" }),
+      coords: { clientX: 10, clientY: 10 },
+    });
+    expect(list).toHaveAttribute("data-focus-source", "pointer");
+  });
+
+  test("marks the selected device with the accent fill", async () => {
+    const user = userEvent.setup();
+    const { getByRole } = renderComponent(
+      <MediaMuteAndSwitchButton
+        iconsAndLabels="audio"
+        enabled={true}
+        options={[
+          { label: { type: "name", name: "Microphone 1" }, id: "mic1" },
+          { label: { type: "name", name: "Microphone 2" }, id: "mic2" },
+        ]}
+        selectedOption="mic2"
+        onSelect={vi.fn()}
+      />,
+    );
+
+    await user.click(getByRole("button", { name: "Microphone" }));
+
+    const selected = screen
+      .getByRole("menuitemradio", { name: "Microphone 2" })
+      .querySelector("input[type=radio]");
+    expect(selected).toBeChecked();
+    // readOnly would paint the selected radio muted.
+    expect(selected).not.toHaveAttribute("readonly");
+  });
+
+  test("the open menu has no accessibility violations", async () => {
+    const user = userEvent.setup();
+    const { getByRole } = renderComponent(
+      <MediaMuteAndSwitchButton
+        iconsAndLabels="audio"
+        enabled={true}
+        options={[
+          { label: { type: "name", name: "Microphone 1" }, id: "mic1" },
+          { label: { type: "name", name: "Microphone 2" }, id: "mic2" },
+        ]}
+        selectedOption="mic1"
+        onSelect={vi.fn()}
+        outputOptions={[
+          { label: { type: "name", name: "Speakers" }, id: "spk1" },
+          { label: { type: "name", name: "Headset" }, id: "spk2" },
+        ]}
+        selectedOutputOption="spk1"
+        onSelectOutput={vi.fn()}
+      />,
+    );
+
+    await user.click(getByRole("button", { name: "Microphone" }));
+
+    const menu = document.querySelector('[role="menu"]');
+    expect(await axe(menu as HTMLElement)).toHaveNoViolations();
+  });
+
+  test("puts the speaker section above the microphone section", async () => {
+    const user = userEvent.setup();
+    const { getByRole } = renderComponent(
+      <MediaMuteAndSwitchButton
+        iconsAndLabels="audio"
+        enabled={true}
+        options={[
+          { label: { type: "name", name: "Microphone 1" }, id: "mic1" },
+          { label: { type: "name", name: "Microphone 2" }, id: "mic2" },
+        ]}
+        selectedOption="mic1"
+        onSelect={vi.fn()}
+        outputOptions={[
+          { label: { type: "name", name: "Speakers" }, id: "spk1" },
+          { label: { type: "name", name: "Headset" }, id: "spk2" },
+        ]}
+        selectedOutputOption="spk1"
+        onSelectOutput={vi.fn()}
+      />,
+    );
+
+    await user.click(getByRole("button", { name: "Microphone" }));
+
+    const speakers = screen.getByRole("menuitemradio", { name: "Speakers" });
+    const microphone = screen.getByRole("menuitemradio", {
       name: "Microphone 1",
     });
-    expect(mic2Item.querySelectorAll("svg").length).toBe(1);
+    expect(
+      speakers.compareDocumentPosition(microphone) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  test("lists speaker and microphone sections", async () => {
+    const user = userEvent.setup();
+    const { getByRole } = renderComponent(
+      <MediaMuteAndSwitchButton
+        iconsAndLabels="audio"
+        enabled={true}
+        options={[
+          { label: { type: "name", name: "Microphone 1" }, id: "mic1" },
+          { label: { type: "name", name: "Microphone 2" }, id: "mic2" },
+        ]}
+        selectedOption="mic1"
+        onSelect={vi.fn()}
+        outputOptions={[
+          {
+            label: { type: "default", name: "Built-in Output" },
+            id: "default",
+          },
+          { label: { type: "name", name: "Headset" }, id: "spk2" },
+        ]}
+        selectedOutputOption="default"
+        onSelectOutput={vi.fn()}
+      />,
+    );
+
+    await user.click(getByRole("button", { name: "Microphone" }));
+
+    screen.getByRole("menuitemradio", {
+      name: "Default (Built-in Output)",
+      checked: true,
+    });
+    screen.getByRole("menuitemradio", { name: "Headset", checked: false });
+    screen.getByRole("menuitemradio", { name: "Microphone 1", checked: true });
+    screen.getByRole("menuitemradio", { name: "Microphone 2", checked: false });
+  });
+
+  test("calls the output select callback on speaker click", async () => {
+    const user = userEvent.setup();
+    const onSelectOutput = vi.fn();
+    const { getByRole } = renderComponent(
+      <MediaMuteAndSwitchButton
+        iconsAndLabels="audio"
+        enabled={true}
+        options={[
+          { label: { type: "name", name: "Microphone 1" }, id: "mic1" },
+          { label: { type: "name", name: "Microphone 2" }, id: "mic2" },
+        ]}
+        selectedOption="mic1"
+        outputOptions={[
+          { label: { type: "name", name: "Speakers" }, id: "spk1" },
+          { label: { type: "name", name: "Headset" }, id: "spk2" },
+        ]}
+        selectedOutputOption="spk1"
+        onSelectOutput={onSelectOutput}
+      />,
+    );
+
+    await user.click(getByRole("button", { name: "Microphone" }));
+    await user.click(screen.getByRole("menuitemradio", { name: "Headset" }));
+
+    expect(onSelectOutput).toHaveBeenCalledWith("spk2");
+  });
+
+  test("shows a single device entry disabled", async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    const { getByRole } = renderComponent(
+      <MediaMuteAndSwitchButton
+        iconsAndLabels="audio"
+        enabled={true}
+        options={[
+          { label: { type: "name", name: "Microphone 1" }, id: "mic1" },
+        ]}
+        selectedOption="mic1"
+        onSelect={onSelect}
+      />,
+    );
+
+    await user.click(getByRole("button", { name: "Microphone" }));
+
+    // Shown, but not selectable.
+    const only = screen.getByRole("menuitemradio", { name: "Microphone 1" });
+    expect(only).toHaveAttribute("aria-disabled", "true");
+  });
+
+  test("shows a default speaker where the platform lists none", async () => {
+    const user = userEvent.setup();
+    const { getByRole } = renderComponent(
+      <MediaMuteAndSwitchButton
+        iconsAndLabels="audio"
+        enabled={true}
+        options={[
+          { label: { type: "name", name: "Microphone 1" }, id: "mic1" },
+          { label: { type: "name", name: "Microphone 2" }, id: "mic2" },
+        ]}
+        selectedOption="mic1"
+        onSelect={vi.fn()}
+        // As Safari: no outputs listed.
+        outputOptions={[]}
+        selectedOutputOption={undefined}
+        onSelectOutput={undefined}
+      />,
+    );
+
+    await user.click(getByRole("button", { name: "Microphone" }));
+
+    const speakers = screen
+      .getAllByRole("group")
+      .find((group) => group.getAttribute("aria-label") === "Speaker")!;
+    const entries = within(speakers).getAllByRole("menuitemradio");
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toHaveAccessibleName("Default");
+    expect(entries[0]).toHaveAttribute("aria-disabled", "true");
+    expect(entries[0]).toHaveAttribute("aria-checked", "true");
+    expect(
+      within(entries[0]).getByRole("radio", { hidden: true }),
+    ).toBeChecked();
+  });
+
+  test("shows the speaker section disabled when output selection is unsupported", async () => {
+    const user = userEvent.setup();
+    const { getByRole } = renderComponent(
+      <MediaMuteAndSwitchButton
+        iconsAndLabels="audio"
+        enabled={true}
+        options={[
+          { label: { type: "name", name: "Microphone 1" }, id: "mic1" },
+          { label: { type: "name", name: "Microphone 2" }, id: "mic2" },
+        ]}
+        selectedOption="mic1"
+        onSelect={vi.fn()}
+        outputOptions={[
+          { label: { type: "name", name: "Speakers" }, id: "spk1" },
+          { label: { type: "name", name: "Headset" }, id: "spk2" },
+        ]}
+        selectedOutputOption="spk1"
+        onSelectOutput={undefined}
+      />,
+    );
+
+    await user.click(getByRole("button", { name: "Microphone" }));
+
+    expect(
+      screen.getByRole("menuitemradio", { name: "Speakers" }),
+    ).toHaveAttribute("aria-disabled", "true");
+    expect(
+      screen.getByRole("menuitemradio", { name: "Headset" }),
+    ).toHaveAttribute("aria-disabled", "true");
+    expect(
+      screen.getByRole("menuitemradio", { name: "Microphone 2" }),
+    ).not.toHaveAttribute("aria-disabled", "true");
   });
 });

src/components/MediaMuteAndSwitchButton.tsx

@@ -5,37 +5,58 @@ 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 {
+  useCallback,
+  useId,
+  useRef,
+  useState,
+  type CSSProperties,
+  type FC,
+  useEffect,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import {
+  Alert,
   Button,
+  InlineSpinner,
   Menu,
   MenuItem,
-  ToggleMenuItem,
+  MenuScrollArea,
+  MenuTitle,
+  RadioInput,
 } from "@vector-im/compound-web";
 import {
-  CheckIcon,
   ChevronUpIcon,
   ChevronDownIcon,
-  MicOnIcon,
+  InfoIcon,
   SpinnerIcon,
-  VideoCallIcon,
 } from "@vector-im/compound-design-tokens/assets/web/icons";
 import classNames from "classnames";
 import { useTranslation } from "react-i18next";
+import { distinctUntilChanged, map } from "rxjs";
 
 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 { useRootElement } from "../RootElementContext";
+import { observeElementSize$ } from "../utils/elementSize";
+import { LiveMicrophoneLevelMeter } from "./MicrophoneLevelMeter";
+import {
+  BackgroundEffectGrid,
+  type BackgroundEffectOption,
+} from "./BackgroundEffectGrid";
 
 export interface MenuOptions {
-  label: DeviceLabel;
+  label: DeviceLabel | AudioOutputDeviceLabel;
   id: string;
 }
 
 export interface MediaMuteAndSwitchButtonProps {
-  /** The title used in the Switcher modal. */
-  title: string;
   /** If the Mute button is enabled */
   enabled?: boolean;
   /** Callback if the mute button is clicked */
@@ -47,8 +68,29 @@ export interface MediaMuteAndSwitchButtonProps {
   options?: MenuOptions[];
   /** The option that will currently be rendered as the selected option */
   selectedOption?: string;
-  videoBlurToggleClick?: () => void;
-  videoBlurEnabled?: boolean;
+  /** Output (speaker) devices. Audio menu only. */
+  outputOptions?: MenuOptions[];
+  /** The output option currently rendered as selected */
+  selectedOutputOption?: string;
+  /** Picks an output device. Undefined disables the speaker section. */
+  onSelectOutput?: (id: string) => void;
+  /** Camera menu only. None or an empty list leaves the section out. */
+  backgroundEffects?: BackgroundEffectOption[];
+  selectedBackgroundEffect?: string;
+  /** Undefined where effects can't run: all but no effect are disabled. */
+  onSelectBackgroundEffect?: (id: string) => void;
+  /** What the user should know before choosing an effect, if anything. */
+  backgroundEffectNotice?: string;
+  /** Whether the first effect chosen is still being prepared. */
+  backgroundEffectSettling?: boolean;
+  /** Called with the file chosen from the add tile. Omit to leave it out. */
+  onAddBackgroundImage?: (file: File) => void;
+  /** Removes a removable effect, never the one in force. */
+  onRemoveBackgroundEffect?: (id: string) => void;
+  /** Why the last file offered couldn't be used; a new object each time. */
+  backgroundImageRefusal?: { text: string };
+  /** The user's own camera, shown at the top of the camera menu. */
+  selfPreview?: ReactNode;
   /**
    * 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`
@@ -56,92 +98,316 @@ export interface MediaMuteAndSwitchButtonProps {
   onSelect?: (id: string) => void;
 }
 
-const BLUR_ID = "blur";
+/** Id of the placeholder "Default" row, shown when the platform lists no outputs. */
+const DEFAULT_OUTPUT_ID = "default";
+
+/** Largest share of the call area's height the device list may take. */
+const LIST_SHARE_OF_CALL = 0.6;
+
+/** Smallest device list height in px, so a short call still shows more than one device. */
+const MIN_LIST_HEIGHT = 160;
+
+/** The menu's width as its stylesheet sets it, to place the preview before
+    the menu is drawn. */
+const MENU_WIDTH = 296;
+
+/** Space kept between the menu and the call area's sides. */
+const MENU_MARGIN = 16;
 
 export const MediaMuteAndSwitchButton: FC<MediaMuteAndSwitchButtonProps> = ({
-  title,
   enabled,
   busy,
   onMuteClick,
   iconsAndLabels,
   options,
   selectedOption,
-  videoBlurEnabled,
-  videoBlurToggleClick,
+  outputOptions,
+  selectedOutputOption,
+  onSelectOutput,
+  backgroundEffects,
+  selectedBackgroundEffect,
+  onSelectBackgroundEffect,
+  backgroundEffectNotice,
+  backgroundEffectSettling,
+  onAddBackgroundImage,
+  onRemoveBackgroundEffect,
+  backgroundImageRefusal,
+  selfPreview,
   onSelect,
 }) => {
-  const [plannedSelection, setPlannedSelection] = useState<string | null>(null);
+  // Requested but not yet selected. Keyed by kind too, since Chrome uses
+  // "default" for both an input and an output.
+  const [plannedSelection, setPlannedSelection] = useState<{
+    kind: "input" | "output";
+    id: string;
+  } | null>(null);
   const [menuOpen, setMenuOpen] = useState(false);
+  // The file picker takes the focus, which the menu reads as a click
+  // elsewhere; it is held open until the picker is done.
+  const choosingFile = useRef(false);
+  const fileInput = useRef<HTMLInputElement | null>(null);
+  // A refusal is about the attempt that caused it: shown until dismissed or
+  // until the menu closes, and again for the next one.
+  const [seenRefusal, setSeenRefusal] = useState<object>();
+  const refusal =
+    backgroundImageRefusal !== seenRefusal ? backgroundImageRefusal : undefined;
+  const onOpenChange = useCallback(
+    (open: boolean): void => {
+      if (!open && choosingFile.current) return;
+      setMenuOpen(open);
+      // Drop a request that never arrived.
+      if (!open) setPlannedSelection(null);
+      if (!open) setSeenRefusal(backgroundImageRefusal);
+    },
+    [backgroundImageRefusal],
+  );
+  // Scrolled to as it appears, as the list may be scrolled away from it.
+  const scrollIntoView = useCallback((element: HTMLElement | null): void => {
+    element?.scrollIntoView({ block: "nearest" });
+  }, []);
+  const watchFileInput = useCallback(
+    (input: HTMLInputElement | null): (() => void) | undefined => {
+      fileInput.current = input;
+      if (input === null) return;
+      // Dismissing the picker fires cancel, which React doesn't type.
+      const done = (): void => {
+        choosingFile.current = false;
+      };
+      input.addEventListener("cancel", done);
+      return (): void => input.removeEventListener("cancel", done);
+    },
+    [],
+  );
   const isBusy = busy ?? false;
   const { t } = useTranslation();
   const devices = useMediaDevices();
+  const noticeId = useId();
+
+  /**
+   * Records on the menu whether the keyboard or the pointer moved focus, for
+   * the focus ring. `:focus-visible` can't tell: Radix focuses whatever the
+   * pointer is over. Listened for on the menu, not the document, so a second
+   * Element Call on the page doesn't answer for this one.
+   */
+  const trackFocusSource = useCallback(
+    (list: HTMLDivElement | null): (() => void) | undefined => {
+      const menu = list?.closest<HTMLElement>('[role="menu"]');
+      if (menu === null || menu === undefined) return;
+      const record = (source: "keyboard" | "pointer"): void => {
+        menu.dataset.focusSource = source;
+      };
+      record("pointer");
+      const usedKeyboard = (): void => record("keyboard");
+      const usedPointer = (): void => record("pointer");
+      menu.addEventListener("keydown", usedKeyboard, true);
+      menu.addEventListener("pointermove", usedPointer, true);
+      return (): void => {
+        menu.removeEventListener("keydown", usedKeyboard, true);
+        menu.removeEventListener("pointermove", usedPointer, true);
+      };
+    },
+    [],
+  );
+
+  // Measured on the call area: CSS can't size the portalled menu against it.
+  const rootElement = useRootElement();
+  const [listShare, setListShare] = useState<number>();
+  const [previewBlock, setPreviewBlock] = useState(0);
+  useEffect(() => {
+    if (!menuOpen) return;
+    // From the tokens the stylesheets size the preview with, so that it is
+    // placed once rather than measured and moved.
+    const tokens = getComputedStyle(rootElement);
+    const px = (token: string): number =>
+      parseFloat(tokens.getPropertyValue(token)) || 0;
+    const below = px("--cpd-space-2x") + px("--cpd-space-1x");
+    // Followed, since a host can resize the call while the menu is open.
+    const subscription = observeElementSize$(rootElement)
+      .pipe(
+        map(({ width, height }) => ({
+          height: Math.round(height * LIST_SHARE_OF_CALL),
+          width: Math.min(MENU_WIDTH, Math.round(width - 2 * MENU_MARGIN)),
+        })),
+        distinctUntilChanged(
+          (a, b) => a.height === b.height && a.width === b.width,
+        ),
+      )
+      .subscribe(({ height, width }) => {
+        setListShare(height);
+        setPreviewBlock(Math.round((width * 9) / 16) + below);
+      });
+    return (): void => subscription.unsubscribe();
+  }, [menuOpen, rootElement]);
+
+  // Paid for out of the list's share, so a preview makes the menu no taller.
+  const hasPreview =
+    iconsAndLabels === "video" &&
+    selfPreview !== undefined &&
+    listShare !== undefined;
+  const previewPinned =
+    hasPreview && listShare - previewBlock >= MIN_LIST_HEIGHT;
+  const listMaxHeight =
+    listShare === undefined
+      ? undefined
+      : Math.max(
+          MIN_LIST_HEIGHT,
+          listShare - (previewPinned ? previewBlock : 0),
+        );
+  const preview = hasPreview && (
+    <div
+      aria-hidden
+      className={classNames(styles.selfPreview, {
+        [styles.selfPreviewPinned]: previewPinned,
+      })}
+    >
+      {backgroundEffectSettling ? <InlineSpinner size={32} /> : selfPreview}
+    </div>
+  );
+
+  // Kept clear at the list's foot, so a row reached by keyboard isn't under
+  // the meter.
+  const [meterHeight, meter] = useMeasuredHeight();
+
+  // Likewise at its head, for the sticky headings.
+  const [headingHeight, heading] = useMeasuredHeight();
 
   useEffect(() => {
     if (menuOpen) devices.requestDeviceNames(); // No-op after the first call
   }, [menuOpen, devices]);
 
-  let button;
-  let toggles: { label: string; enabled: boolean; id: string }[] = [];
-  switch (iconsAndLabels) {
-    case "video":
-      button = (
-        <VideoButton
-          enabled={enabled ?? false}
-          busy={isBusy}
-          onClick={(e) => {
-            onMuteClick?.();
-            e.preventDefault();
-            e.stopPropagation();
-          }}
-          disabled={isBusy || onMuteClick === undefined}
-          data-testid="incall_videomute"
-        />
-      );
-      if (videoBlurToggleClick !== undefined) {
-        toggles = [
-          {
-            label: t("action.blur_background"),
-            enabled: videoBlurEnabled ?? false,
-            id: BLUR_ID,
-          },
-        ];
+  const MuteButton = iconsAndLabels === "audio" ? MicButton : VideoButton;
+  const button = (
+    <MuteButton
+      enabled={enabled ?? false}
+      busy={isBusy}
+      onClick={(e) => {
+        onMuteClick?.();
+        e.preventDefault();
+        e.stopPropagation();
+      }}
+      disabled={isBusy || onMuteClick === undefined}
+      data-testid={
+        iconsAndLabels === "audio" ? "incall_mute" : "incall_videomute"
       }
-      break;
-    case "audio":
-      button = (
-        <MicButton
-          enabled={enabled ?? false}
-          busy={isBusy}
-          onClick={(e) => {
-            onMuteClick?.();
-            e.preventDefault();
-            e.stopPropagation();
-          }}
-          disabled={isBusy || onMuteClick === undefined}
-          data-testid="incall_mute"
-        />
-      );
-      break;
-  }
+    />
+  );
+
+  const showEffects =
+    iconsAndLabels === "video" && (backgroundEffects?.length ?? 0) > 0;
 
-  let IconOptions: ComponentType<React.SVGAttributes<SVGElement>> | undefined;
   let optionsButtonLabel: string;
+  let menuTitle: string;
   let numberedLabel: (number: number) => string;
   switch (iconsAndLabels) {
     case "video":
-      IconOptions = VideoCallIcon;
       optionsButtonLabel = t("settings.devices.camera");
+      menuTitle = t("settings.devices.camera_source");
       numberedLabel = (n): string =>
         t("settings.devices.camera_numbered", { n });
       break;
     case "audio":
-      IconOptions = MicOnIcon;
       optionsButtonLabel = t("settings.devices.microphone");
+      menuTitle = t("settings.devices.mic_source");
       numberedLabel = (n): string =>
         t("settings.devices.microphone_numbered", { n });
       break;
   }
 
+  const labelText = (
+    label: MenuOptions["label"],
+    numbered: (n: number) => string,
+  ): string => {
+    switch (label.type) {
+      case "name":
+        return label.name;
+      case "number":
+        return numbered(label.number);
+      case "default":
+        return label.name === null
+          ? t("settings.devices.default")
+          : t("settings.devices.default_named_plain", { name: label.name });
+      case "speaker":
+        return t("settings.devices.loudspeaker");
+      case "earpiece":
+        return t("settings.devices.handset");
+    }
+  };
+
+  // Nothing can be picked while a requested device is on offer but not yet
+  // selected, so a second request can't overtake it.
+  const plannedOutput = plannedSelection?.kind === "output";
+  const selectedOfPlannedKind = plannedOutput
+    ? selectedOutputOption
+    : selectedOption;
+  const offeredOfPlannedKind = plannedOutput ? outputOptions : options;
+  const settling =
+    plannedSelection !== null &&
+    plannedSelection.id !== selectedOfPlannedKind &&
+    offeredOfPlannedKind?.some(({ id }) => id === plannedSelection.id) === true;
+
+  // Safari lists no outputs: show a disabled, selected Default rather than an
+  // empty section.
+  const noOutputsListed = outputOptions?.length === 0;
+  const speakerOptions: MenuOptions[] | undefined = noOutputsListed
+    ? [{ id: DEFAULT_OUTPUT_ID, label: { type: "default", name: null } }]
+    : outputOptions;
+  const selectedSpeaker = noOutputsListed
+    ? DEFAULT_OUTPUT_ID
+    : selectedOutputOption;
+
+  const deviceItems = (
+    kind: "input" | "output",
+    items: MenuOptions[] | undefined,
+    selected: string | undefined,
+    select: ((id: string) => void) | undefined,
+    numbered: (n: number) => string,
+  ): ReactElement[] => {
+    const list = items ?? [];
+    // Disabled rather than hidden, so the menu keeps its shape.
+    const disabled = select === undefined || list.length <= 1 || settling;
+    return list.map(({ label, id }) => (
+      <MenuItem
+        // A radio input may not sit inside a button.
+        as="div"
+        hideChevron
+        disabled={disabled}
+        label={labelText(label, numbered)}
+        Icon={
+          // Inert, not aria-hidden: aria-hidden alone leaves it focusable.
+          <span inert>
+            <RadioInput
+              checked={selected === id}
+              disabled={disabled}
+              // Not readOnly, which mutes the selected fill. The item handles
+              // the click.
+              onChange={(): void => {}}
+            />
+          </span>
+        }
+        onSelect={(e) => {
+          e.preventDefault();
+          if (id === selected) return;
+          setPlannedSelection({ kind, id });
+          select?.(id);
+        }}
+        key={id}
+        role="menuitemradio"
+        aria-checked={selected === id}
+      >
+        {selected !== id &&
+          plannedSelection?.kind === kind &&
+          plannedSelection.id === id && (
+            <SpinnerIcon
+              width={24}
+              height={24}
+              className={styles.rotate}
+              aria-label={t("settings.devices.activating")}
+            />
+          )}
+      </MenuItem>
+    ));
+  };
+
   return (
     <div
       className={classNames({
@@ -151,12 +417,31 @@ export const MediaMuteAndSwitchButton: FC<MediaMuteAndSwitchButtonProps> = ({
     >
       {/* The mute button lives inside */}
       {button}
+      {onAddBackgroundImage !== undefined && (
+        <input
+          ref={watchFileInput}
+          type="file"
+          accept="image/*"
+          hidden
+          onChange={(e) => {
+            const file = e.target.files?.[0];
+            // Cleared, so the same file can be chosen twice in a row.
+            e.target.value = "";
+            choosingFile.current = false;
+            if (file) onAddBackgroundImage(file);
+          }}
+        />
+      )}
       <Menu
-        title={title}
-        showTitle={true}
+        className={styles.menu}
+        // Named for screen readers only: each section has its own heading.
+        title={menuTitle}
+        showTitle={false}
         open={menuOpen}
-        onOpenChange={setMenuOpen}
+        onOpenChange={onOpenChange}
         side="top"
+        collisionBoundary={rootElement}
+        collisionPadding={MENU_MARGIN}
         trigger={
           <Button
             iconOnly
@@ -171,71 +456,141 @@ export const MediaMuteAndSwitchButton: FC<MediaMuteAndSwitchButtonProps> = ({
           />
         }
       >
-        {options?.map(({ label, id }) => {
-          let labelText: string;
-          switch (label.type) {
-            case "name":
-              labelText = label.name;
-              break;
-            case "number":
-              labelText = numberedLabel(label.number);
-              break;
+        {previewPinned && preview}
+        <MenuScrollArea
+          ref={trackFocusSource}
+          className={classNames(styles.deviceList, {
+            [styles.deviceListLeadsWithPreview]: hasPreview && !previewPinned,
+            [styles.deviceListWithMeter]: iconsAndLabels === "audio",
+          })}
+          style={
+            {
+              "--device-list-max-height":
+                listMaxHeight === undefined ? undefined : `${listMaxHeight}px`,
+              // A row reached by keyboard stays above the meter and the band its
+              // ground fills.
+              scrollPaddingBlockEnd:
+                meterHeight === undefined
+                  ? undefined
+                  : `calc(${meterHeight}px + var(--cpd-menu-padding-block-end, 0px))`,
+              "--device-list-scroll-padding-start":
+                headingHeight === undefined ? undefined : `${headingHeight}px`,
+            } as CSSProperties
           }
-          return (
-            <MenuItem
-              hideChevron
-              label={labelText}
-              Icon={
-                IconOptions && (
-                  <IconOptions
-                    width={24}
-                    height={24}
-                    className={styles.itemIcon}
-                    aria-hidden
-                  />
-                )
+        >
+          {hasPreview && !previewPinned && preview}
+          {iconsAndLabels === "audio" && speakerOptions && (
+            <>
+              {/* A menu may only contain items, separators and groups, so each
+                  heading is a hidden part of a named group. */}
+              <div role="group" aria-label={t("settings.devices.speaker")}>
+                <div aria-hidden className={styles.sectionHeading}>
+                  <MenuTitle title={t("settings.devices.speaker")} />
+                </div>
+                {deviceItems(
+                  "output",
+                  speakerOptions,
+                  selectedSpeaker,
+                  onSelectOutput,
+                  (n) => t("settings.devices.speaker_numbered", { n }),
+                )}
+              </div>
+            </>
+          )}
+          <div role="group" aria-label={optionsButtonLabel}>
+            <div ref={heading} aria-hidden className={styles.sectionHeading}>
+              <MenuTitle title={optionsButtonLabel} />
+            </div>
+            {/* Apart from the heading, so the sticky meter can't ride over it. */}
+            <div role="none">
+              {deviceItems(
+                "input",
+                options,
+                selectedOption,
+                onSelect,
+                numberedLabel,
+              )}
+              {iconsAndLabels === "audio" && (
+                <LiveMicrophoneLevelMeter
+                  ref={meter}
+                  deviceId={selectedOption}
+                  // Only while open, so the microphone isn't held all call.
+                  active={menuOpen}
+                  className={styles.stickyMeter}
+                />
+              )}
+            </div>
+          </div>
+          {showEffects && (
+            <BackgroundEffectGrid
+              label={t("settings.background_effects_header")}
+              heading={
+                <div aria-hidden className={styles.sectionHeading}>
+                  <MenuTitle title={t("settings.background_effects_header")} />
+                </div>
               }
-              onSelect={(e) => {
-                e.preventDefault();
-                if (id === selectedOption) return;
-                setPlannedSelection(id);
-                onSelect?.(id);
-              }}
-              key={id}
-              role="menuitemradio"
-              aria-checked={selectedOption === id}
-            >
-              {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>
-          );
-        })}
-        {(toggles?.length ?? 0) > 0 && <hr />}
-        {toggles?.map((toggle) => (
-          <ToggleMenuItem
-            label={toggle.label}
-            onSelect={(e) => {
-              videoBlurToggleClick?.();
-              e.preventDefault();
-            }}
-            checked={toggle.enabled ?? false}
-            key={toggle.id}
-          />
-        ))}
+              effects={backgroundEffects ?? []}
+              selected={selectedBackgroundEffect}
+              onSelect={onSelectBackgroundEffect}
+              settling={backgroundEffectSettling}
+              describedBy={
+                backgroundEffectNotice === undefined ? undefined : noticeId
+              }
+              onAdd={
+                onAddBackgroundImage === undefined
+                  ? undefined
+                  : (): void => {
+                      choosingFile.current = true;
+                      fileInput.current?.click();
+                    }
+              }
+              addLabel={t("action.add_background_image")}
+              onRemove={onRemoveBackgroundEffect}
+              removeLabel={t("action.remove")}
+            />
+          )}
+          {/* In the list, so the menu grows no taller for it. */}
+          {showEffects && refusal !== undefined && (
+            <div ref={scrollIntoView} role="none" className={styles.refusal}>
+              <Alert
+                type="critical"
+                title={refusal.text}
+                onClose={(): void => setSeenRefusal(refusal)}
+              />
+            </div>
+          )}
+          {showEffects &&
+            refusal === undefined &&
+            backgroundEffectNotice !== undefined && (
+              <div id={noticeId} role="none" className={styles.notice}>
+                <InfoIcon width={20} height={20} />
+                <span>{backgroundEffectNotice}</span>
+              </div>
+            )}
+        </MenuScrollArea>
       </Menu>
     </div>
   );
 };
+
+/** Follows an element's height. */
+function useMeasuredHeight(): [
+  number | undefined,
+  (element: HTMLElement | null) => (() => void) | undefined,
+] {
+  const [height, setHeight] = useState<number>();
+  const ref = useCallback(
+    (element: HTMLElement | null): (() => void) | undefined => {
+      if (element === null) return;
+      const subscription = observeElementSize$(element)
+        .pipe(
+          map((size) => size.height),
+          distinctUntilChanged(),
+        )
+        .subscribe(setHeight);
+      return (): void => subscription.unsubscribe();
+    },
+    [],
+  );
+  return [height, ref];
+}

src/components/MicrophoneLevelMeter.module.css

@@ -0,0 +1,65 @@
+/*
+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 {
+  /* A device row's icon column, so the bars start where the names do. */
+  --meter-icon-size: 24px;
+
+  /* Compound's radio size, whose centre line the icon shares. */
+  --device-control-size: 20px;
+
+  display: flex;
+  align-items: center;
+  gap: var(--cpd-space-3x);
+  padding-block: var(--cpd-space-2x);
+  /* Centres the icon on the radio column: less half the icon's extra width.
+     Checked in the MeterAlignsWithTheDeviceRows story. */
+  padding-inline-start: calc(
+    var(--cpd-space-4x) -
+      (var(--meter-icon-size) - var(--device-control-size)) / 2
+  );
+  padding-inline-end: calc(var(--cpd-space-4x) * 2 + var(--cpd-space-2x));
+}
+
+.icon {
+  color: var(--cpd-color-icon-secondary);
+  flex-shrink: 0;
+  inline-size: var(--meter-icon-size);
+  block-size: var(--meter-icon-size);
+}
+
+.segments {
+  /* Bars keep one size and the width decides how many; the component reads the
+     sizes back from here. */
+  flex: 1;
+  /* So the bars never set the menu's width. */
+  contain: inline-size;
+  min-inline-size: 0;
+  display: flex;
+  align-items: center;
+  /* Half again a bar's width, per the design. */
+  gap: var(--cpd-space-1-5x);
+}
+
+.segment {
+  flex: none;
+  inline-size: var(--cpd-space-1x);
+  block-size: var(--cpd-space-4x);
+  border-radius: var(--cpd-space-1x);
+  background: var(--cpd-color-bg-subtle-primary);
+}
+
+/* The count of lit bars carries the level as well as their colour. */
+.segmentLit {
+  background: var(--cpd-color-bg-accent-rest);
+}
+
+.message {
+  color: var(--cpd-color-text-secondary);
+  /* A paragraph's margin would lift the text off centre. */
+  margin-block: 0;
+}

src/components/MicrophoneLevelMeter.stories.tsx

@@ -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 { expect, within } from "storybook/test";
+import { type JSX } from "react";
+
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import {
+  MicrophoneLevelMeter,
+  type MicrophoneLevelMeterProps,
+} from "./MicrophoneLevelMeter";
+import styles from "./MicrophoneLevelMeter.module.css";
+import { LEVEL_SCALE } from "../state/MicrophoneLevel";
+import { constant } from "../state/Behavior";
+
+/** Roughly the menu's width. It only decides how many bars fit. */
+const STORY_WIDTH = 256;
+
+const meta = {
+  component: MicrophoneLevelMeter,
+  decorators: [
+    (Story): JSX.Element => (
+      <div style={{ inlineSize: STORY_WIDTH }}>
+        <Story />
+      </div>
+    ),
+  ],
+  argTypes: {
+    state: {
+      description:
+        "What the selected microphone can say about itself: a level, or a reason there is none.",
+    },
+  },
+} satisfies Meta<typeof MicrophoneLevelMeter>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** A quiet room: hiss below the noise floor lights nothing. */
+export const Silent: Story = {
+  args: { state: { type: "level", level$: constant(0) } },
+  play: async ({ canvasElement }) => {
+    await expect(litSegments(canvasElement)).toBe(0);
+  },
+};
+
+export const QuietSpeech: Story = {
+  args: { state: { type: "level", level$: constant(5) } },
+};
+
+export const NormalSpeech: Story = {
+  args: { state: { type: "level", level$: constant(12) } },
+  play: async ({ canvasElement }) => {
+    // A floor, not a count: the count follows from the design's bar and gap sizes.
+    await expect(
+      canvasElement.getElementsByClassName(styles.segment).length,
+    ).toBeGreaterThanOrEqual(15);
+  },
+};
+
+export const LoudSpeech: Story = {
+  args: { state: { type: "level", level$: constant(LEVEL_SCALE) } },
+};
+
+/** The three volumes differ in how many bars are lit, not only in colour. */
+export const VolumesAreDistinguishable: Story = {
+  args: { state: { type: "level", level$: constant(5) } },
+  play: async ({ canvasElement, mount }) => {
+    const lit: number[] = [];
+    for (const level of [5, 12, LEVEL_SCALE]) {
+      await mount(
+        <MicrophoneLevelMeter
+          state={{ type: "level", level$: constant(level) }}
+        />,
+      );
+      lit.push(litSegments(canvasElement));
+      await expect(within(canvasElement).getByRole("meter")).toHaveAttribute(
+        "aria-valuenow",
+        String(level),
+      );
+    }
+    await expect(new Set(lit).size).toBe(lit.length);
+    await expect(lit).toEqual([...lit].sort((a, b) => a - b));
+  },
+};
+
+/** Permission refused: a message with a next action, not a still meter. */
+export const PermissionDenied: Story = {
+  args: { state: { type: "permission-denied" } },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.queryByRole("meter")).toBeNull();
+    await expect(
+      canvas.getByText(/Microphone access is blocked/),
+    ).toBeVisible();
+  },
+};
+
+/** No input device, told apart from a refusal. */
+export const NoDevice: Story = {
+  args: { state: { type: "no-device" } },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.queryByRole("meter")).toBeNull();
+    await expect(canvas.getByText(/No microphone found/)).toBeVisible();
+
+    // The icon sits on the middle of the text, however many lines it runs to.
+    const middle = (element: Element): number => {
+      const box = element.getBoundingClientRect();
+      return box.top + box.height / 2;
+    };
+    const icon = canvasElement.getElementsByClassName(styles.icon)[0];
+    const words = canvasElement.getElementsByClassName(styles.message)[0];
+    await expect(Math.abs(middle(icon) - middle(words))).toBeLessThanOrEqual(1);
+  },
+};
+
+/** The same meter at two widths: the bars keep their size and only their count changes. */
+export const ShapeStaysTheSameAtAnyWidth: Story = {
+  args: { state: { type: "level", level$: constant(12) } },
+  play: async ({ mount, args }) => {
+    const narrow = await measureAt(mount, args, 180);
+    const wide = await measureAt(mount, args, 400);
+
+    await expect(narrow.bar).toBe(wide.bar);
+    await expect(narrow.gap).toBe(wide.gap);
+    await expect(narrow.count).toBeLessThan(wide.count);
+    // The bars are still separate, not one run of colour.
+    await expect(narrow.gap).toBeGreaterThan(0);
+  },
+};
+
+/** How many bars are lit. */
+function litSegments(canvasElement: HTMLElement): number {
+  return canvasElement.getElementsByClassName(styles.segmentLit).length;
+}
+
+/** Renders the meter at one width and reports its bars' shape. */
+async function measureAt(
+  mount: (ui: JSX.Element) => Promise<unknown>,
+  args: MicrophoneLevelMeterProps,
+  width: number,
+): Promise<{ count: number; bar: number; gap: number }> {
+  await mount(
+    <div style={{ inlineSize: width }}>
+      <MicrophoneLevelMeter {...args} />
+    </div>,
+  );
+  const bars = Array.from(document.body.getElementsByClassName(styles.segment));
+  const first = bars[0].getBoundingClientRect();
+  const second = bars[1].getBoundingClientRect();
+  return {
+    count: bars.length,
+    bar: first.width,
+    gap: second.left - first.right,
+  };
+}

src/components/MicrophoneLevelMeter.test.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 { describe, expect, test } from "vitest";
+import { render, screen } from "@testing-library/react";
+
+import { MicrophoneLevelMeter } from "./MicrophoneLevelMeter";
+import { LEVEL_SCALE } from "../state/MicrophoneLevel";
+import { constant } from "../state/Behavior";
+
+describe("MicrophoneLevelMeter", () => {
+  test("announces the level rather than relying on hue", () => {
+    render(
+      <MicrophoneLevelMeter state={{ type: "level", level$: constant(6) }} />,
+    );
+
+    const meter = screen.getByRole("meter", { name: "Microphone level" });
+    expect(meter).toHaveAttribute("aria-valuenow", "6");
+    expect(meter).toHaveAttribute("aria-valuemax", String(LEVEL_SCALE));
+    expect(meter).toHaveAttribute("aria-valuetext", `6 of ${LEVEL_SCALE}`);
+  });
+
+  test("shows distinct messages for denied permission and no input device", () => {
+    const denied = render(
+      <MicrophoneLevelMeter state={{ type: "permission-denied" }} />,
+    );
+    expect(
+      denied.getByText(/Microphone access is blocked/),
+    ).toBeInTheDocument();
+    expect(denied.queryByRole("meter")).toBeNull();
+
+    const missing = render(
+      <MicrophoneLevelMeter state={{ type: "no-device" }} />,
+    );
+    expect(missing.getByText(/No microphone found/)).toBeInTheDocument();
+    expect(missing.queryByRole("meter")).toBeNull();
+  });
+});

src/components/MicrophoneLevelMeter.tsx

@@ -0,0 +1,146 @@
+/*
+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 {
+  useCallback,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type FC,
+  type Ref,
+} from "react";
+import { Text } from "@vector-im/compound-web";
+import { MicOnIcon } from "@vector-im/compound-design-tokens/assets/web/icons";
+import classNames from "classnames";
+import { useTranslation } from "react-i18next";
+
+import { distinctUntilChanged, map } from "rxjs";
+
+import styles from "./MicrophoneLevelMeter.module.css";
+import { LEVEL_SCALE, type MicrophoneState } from "../state/MicrophoneLevel";
+import { observeElementSize$ } from "../utils/elementSize";
+import { useMicrophoneLevel } from "./useMicrophoneLevel";
+
+export interface LiveMicrophoneLevelMeterProps {
+  /** The microphone to listen to. */
+  deviceId: string | undefined;
+  /** Whether to hold a capture at all. */
+  active: boolean;
+  className?: string;
+  ref?: Ref<HTMLDivElement>;
+}
+
+/**
+ * The meter, wired to a live capture. Its own component so a changing level
+ * re-renders the meter, not its parent.
+ */
+export const LiveMicrophoneLevelMeter: FC<LiveMicrophoneLevelMeterProps> = ({
+  deviceId,
+  active,
+  className,
+  ref,
+}) => {
+  const state = useMicrophoneLevel(deviceId, active);
+  return <MicrophoneLevelMeter state={state} className={className} ref={ref} />;
+};
+
+export interface MicrophoneLevelMeterProps {
+  state: MicrophoneState;
+  className?: string;
+  ref?: Ref<HTMLDivElement>;
+}
+
+/** The input level of a microphone, or why there is none. */
+export const MicrophoneLevelMeter: FC<MicrophoneLevelMeterProps> = ({
+  state,
+  className,
+  ref,
+}) => {
+  const { t } = useTranslation();
+  // Bars keep one size, so their count follows the width. Starts full so the
+  // first paint, and jsdom, draw a whole meter.
+  const [barCount, setBarCount] = useState(LEVEL_SCALE);
+  const segments = useRef<HTMLDivElement | null>(null);
+  const track = useCallback(
+    (element: HTMLDivElement | null): (() => void) | undefined => {
+      if (element === null) return;
+      segments.current = element;
+      const subscription = observeElementSize$(element)
+        .pipe(
+          map(({ width }) => barsThatFit(element, width)),
+          distinctUntilChanged(),
+        )
+        .subscribe(setBarCount);
+      return (): void => {
+        subscription.unsubscribe();
+        segments.current = null;
+      };
+    },
+    [],
+  );
+
+  // Drawn straight into the DOM: the level changes many times a second, and
+  // re-rendering for each change is what this avoids.
+  useLayoutEffect(() => {
+    const element = segments.current;
+    if (state.type !== "level" || element === null) return;
+    const subscription = state.level$.subscribe((level) => {
+      element.setAttribute("aria-valuenow", String(level));
+      element.setAttribute(
+        "aria-valuetext",
+        t("microphone_level.value", { level, max: LEVEL_SCALE }),
+      );
+      // The level is a share of the scale, not a bar count.
+      const lit = Math.round((level / LEVEL_SCALE) * barCount);
+      Array.from(element.children).forEach((bar, i) =>
+        bar.classList.toggle(styles.segmentLit, i < lit),
+      );
+    });
+    return (): void => subscription.unsubscribe();
+  }, [state, barCount, t]);
+
+  return (
+    <div ref={ref} className={classNames(styles.meter, className)}>
+      <MicOnIcon className={styles.icon} aria-hidden />
+      {state.type !== "level" ? (
+        <Text size="sm" className={styles.message}>
+          {state.type === "permission-denied"
+            ? t("microphone_level.permission_denied")
+            : t("microphone_level.no_device")}
+        </Text>
+      ) : (
+        <div
+          ref={track}
+          className={styles.segments}
+          role="meter"
+          aria-label={t("microphone_level.label")}
+          aria-valuemin={0}
+          aria-valuemax={LEVEL_SCALE}
+          // The first paint's value; the effect above keeps it current.
+          aria-valuenow={state.level$.value}
+          aria-valuetext={t("microphone_level.value", {
+            level: state.level$.value,
+            max: LEVEL_SCALE,
+          })}
+        >
+          {Array.from({ length: barCount }, (_, i) => (
+            <span key={i} aria-hidden className={styles.segment} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+/** How many bars fit across `width`, measured so the stylesheet alone sets their size. */
+function barsThatFit(track: HTMLElement, width: number): number {
+  const gap = Number.parseFloat(getComputedStyle(track).columnGap);
+  const bar = track.firstElementChild?.getBoundingClientRect().width ?? 0;
+  // No layout (jsdom): keep the full count.
+  if (!(bar > 0) || !(gap >= 0)) return LEVEL_SCALE;
+  return Math.max(1, Math.floor((width + gap) / (bar + gap)));
+}

src/components/SelfPreview.module.css

@@ -0,0 +1,10 @@
+/*
+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.
+*/
+
+.mirrored {
+  transform: scaleX(-1);
+}

src/components/SelfPreview.tsx

@@ -0,0 +1,36 @@
+/*
+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 } from "react";
+import { type LocalVideoTrack } from "livekit-client";
+import { VideoCallOffIcon } from "@vector-im/compound-design-tokens/assets/web/icons";
+
+import styles from "./SelfPreview.module.css";
+import { useAttachedTrack } from "../useAttachedTrack";
+
+interface Props {
+  /** The camera as the pipeline has it, or none while the camera is off. */
+  track: LocalVideoTrack | null;
+}
+
+/**
+ * The user's own camera with the effect in force: the pipeline's own track,
+ * shown a second time rather than captured again.
+ */
+export const SelfPreview: FC<Props> = ({ track }) => {
+  const { videoRef, mirrored } = useAttachedTrack(track);
+
+  if (!track) return <VideoCallOffIcon width={32} height={32} />;
+  return (
+    <video
+      ref={videoRef}
+      muted
+      playsInline
+      className={mirrored ? styles.mirrored : undefined}
+    />
+  );
+};

src/components/__snapshots__/MediaMuteAndSwitchButton.test.tsx.snap

@@ -9,7 +9,7 @@ exports[`MediaMuteAndSwitchButton > renders 1`] = `
       aria-busy="false"
       aria-checked="false"
       aria-disabled="true"
-      aria-labelledby="_r_0_"
+      aria-labelledby="_r_1_"
       class="_button_1nw83_8 _has-icon_1nw83_60 _icon-only_1nw83_53"
       data-kind="primary"
       data-size="lg"
@@ -39,7 +39,7 @@ exports[`MediaMuteAndSwitchButton > renders 1`] = `
       data-kind="tertiary"
       data-size="lg"
       data-state="closed"
-      id="radix-_r_5_"
+      id="radix-_r_6_"
       role="button"
       tabindex="0"
       type="button"

src/components/useMicrophoneLevel.test.tsx

@@ -0,0 +1,41 @@
+/*
+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 } from "vitest";
+import { renderHook } from "@testing-library/react";
+
+import { useMicrophoneLevel } from "./useMicrophoneLevel";
+import { restoreAudioCapture, stubAudioCapture } from "../utils/test";
+
+// Capture and release are covered in MicrophoneLevel.test.ts; this covers the bridge.
+describe("useMicrophoneLevel", () => {
+  afterEach(restoreAudioCapture);
+
+  test("holds no capture while the meter is not shown", () => {
+    const capture = stubAudioCapture();
+
+    renderHook(() => useMicrophoneLevel("mic1", false));
+
+    expect(capture.getUserMedia).not.toHaveBeenCalled();
+  });
+
+  test("starts from nothing rather than the previous device's level", () => {
+    const capture = stubAudioCapture();
+
+    const { result, rerender } = renderHook(
+      ({ id }: { id: string }) => useMicrophoneLevel(id, true),
+      { initialProps: { id: "mic1" } },
+    );
+    capture.grant();
+
+    rerender({ id: "mic2" });
+
+    // No level carried over from the previous device.
+    const state = result.current;
+    expect(state.type === "level" ? state.level$.value : state.type).toBe(0);
+  });
+});

src/components/useMicrophoneLevel.ts

@@ -0,0 +1,34 @@
+/*
+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 {
+  type MicrophoneState,
+  observeMicrophoneState$,
+} from "../state/MicrophoneLevel";
+import { constant } from "../state/Behavior";
+
+const IDLE: MicrophoneState = { type: "level", level$: constant(0) };
+
+/** The live level of a microphone, captured only while `active`. */
+export function useMicrophoneLevel(
+  deviceId: string | undefined,
+  active: boolean,
+): MicrophoneState {
+  const [state, setState] = useState<MicrophoneState>(IDLE);
+
+  useEffect(() => {
+    if (!active) return;
+    // Idle first, so a new device doesn't start from the previous level.
+    setState(IDLE);
+    const subscription = observeMicrophoneState$(deviceId).subscribe(setState);
+    return (): void => subscription.unsubscribe();
+  }, [deviceId, active]);
+
+  return state;
+}

src/config/ConfigOptions.ts

@@ -207,12 +207,6 @@ export interface ConfigOptions {
    * Take care when changing these options.
    */
   matrix_rtc_session?: {
-    /**
-     * How long (in milliseconds) to wait before rotating end-to-end media encryption keys
-     * when someone leaves a call.
-     */
-    wait_for_key_rotation_ms?: number;
-
     /**
      * How long we wait before retrying after a network error on any of the requests.
      */

src/grid/CallLayout.test.tsx

@@ -0,0 +1,187 @@
+/*
+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 { act, render, screen } from "@testing-library/react";
+import { BehaviorSubject } from "rxjs";
+import { describe, expect, it, vi } from "vitest";
+
+import { arrangeTiles, type Bounds } from "./CallLayout";
+import { makeGridLayout } from "./GridLayout";
+import { makeSpotlightLandscapeLayout } from "./SpotlightLandscapeLayout";
+import { makeSpotlightPortraitLayout } from "./SpotlightPortraitLayout";
+import { type DragCallback, type LayoutProps } from "./Grid";
+import { constant } from "../state/Behavior";
+import {
+  type Alignment,
+  type GridLayout,
+  type SpotlightLandscapeLayout,
+  type SpotlightPortraitLayout,
+} from "../state/layout-types";
+import { type UserMediaViewModel } from "../state/media/UserMediaViewModel";
+import {
+  GridTileViewModel,
+  SpotlightTileViewModel,
+  type TileViewModel,
+} from "../state/TileViewModel";
+
+// Grid supplies these hooks to the layouts it renders; on their own the
+// layouts have no grid to report to
+vi.mock("./Grid", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useUpdateLayout: (): void => {},
+  useVisibleTiles: (): void => {},
+}));
+
+describe("grid layout", () => {
+  it("sizes the tiles from the minimum bounds", () => {
+    const minBounds$ = new BehaviorSubject<Bounds>({ width: 800, height: 600 });
+    const { scrolling: Scrolling } = makeGridLayout({ minBounds$ });
+    render(<Scrolling model={gridModel()} Slot={Slot} />);
+    const layer = screen.getByTestId("slot-0").parentElement!;
+    expect(layer.style.width).toBe("800px");
+    expect(layer.style.getPropertyValue("--width")).toBe(
+      `${Math.floor(arrangeTiles(800, 600, 3).tileWidth)}px`,
+    );
+
+    act(() => minBounds$.next({ width: 400, height: 300 }));
+    expect(layer.style.width).toBe("400px");
+    expect(layer.style.getPropertyValue("--width")).toBe(
+      `${Math.floor(arrangeTiles(400, 300, 3).tileWidth)}px`,
+    );
+  });
+
+  it("moves the spotlight only when a drag reaches another corner", () => {
+    const model = gridModel();
+    const { fixed: Fixed } = makeGridLayout({ minBounds$: bounds });
+    render(<Fixed model={model} Slot={Slot} />);
+    const alignments: Alignment[] = [];
+    model.spotlightAlignment$.subscribe((a) => alignments.push(a));
+    const drag = drags.get("spotlight")!;
+
+    // Still in the bottom right corner
+    act(() => drag({ x: 0, y: 0, xRatio: 0.9, yRatio: 0.9 }));
+    // Over to the bottom left
+    act(() => drag({ x: 0, y: 0, xRatio: 0.1, yRatio: 0.9 }));
+    // And a little further, still bottom left
+    act(() => drag({ x: 0, y: 0, xRatio: 0.2, yRatio: 0.8 }));
+    // Up to the top left
+    act(() => drag({ x: 0, y: 0, xRatio: 0.2, yRatio: 0.1 }));
+
+    expect(alignments).toEqual([
+      { inline: "end", block: "end" },
+      { inline: "start", block: "end" },
+      { inline: "start", block: "start" },
+    ]);
+    const slot = screen.getByTestId("slot-spotlight");
+    expect(slot.getAttribute("data-inline-alignment")).toBe("start");
+    expect(slot.getAttribute("data-block-alignment")).toBe("start");
+  });
+});
+
+describe("spotlight landscape layout", () => {
+  it("puts the spotlight in the fixed layer and the grid in the scrolling one", () => {
+    const { fixed: Fixed, scrolling: Scrolling } = makeSpotlightLandscapeLayout(
+      { minBounds$: bounds },
+    );
+    const model = landscapeModel();
+    const { unmount } = render(<Fixed model={model} Slot={Slot} />);
+    expect(screen.getByTestId("slot-spotlight")).toBeInTheDocument();
+    unmount();
+
+    render(<Scrolling model={model} Slot={Slot} />);
+    expect(slotIds()).toEqual(model.grid.map((tile) => tile.id));
+  });
+});
+
+describe("spotlight portrait layout", () => {
+  it("sizes the grid tiles from the minimum width", () => {
+    const minBounds$ = new BehaviorSubject<Bounds>({ width: 300, height: 700 });
+    const { scrolling: Scrolling } = makeSpotlightPortraitLayout({
+      minBounds$,
+    });
+    const model = portraitModel();
+    render(<Scrolling model={model} Slot={Slot} />);
+    expect(slotIds()).toEqual(model.grid.map((tile) => tile.id));
+    const layer = screen.getByTestId(`slot-${model.grid[0].id}`).parentElement!
+      .parentElement!;
+    expect(layer.style.getPropertyValue("--grid-tile-width")).toBe(
+      `${Math.floor(arrangeTiles(300, 300, 3).tileWidth)}px`,
+    );
+
+    act(() => minBounds$.next({ width: 500, height: 700 }));
+    expect(layer.style.getPropertyValue("--grid-tile-width")).toBe(
+      `${Math.floor(arrangeTiles(500, 500, 3).tileWidth)}px`,
+    );
+  });
+});
+
+const bounds = constant<Bounds>({ width: 800, height: 600 });
+
+// The layouts only pass tile view models through to their slots
+const media = {} as UserMediaViewModel;
+const spotlight = new SpotlightTileViewModel(
+  constant([]),
+  constant(false),
+  constant("solid"),
+);
+const tiles = (): GridTileViewModel[] =>
+  Array.from({ length: 3 }, () => new GridTileViewModel(constant(media)));
+
+function gridModel(): GridLayout {
+  return {
+    type: "grid",
+    spotlight,
+    grid: tiles(),
+    spotlightAlignment$: new BehaviorSubject<Alignment>({
+      inline: "end",
+      block: "end",
+    }),
+    setVisibleTiles: () => {},
+  };
+}
+
+function landscapeModel(): SpotlightLandscapeLayout {
+  return {
+    type: "spotlight-landscape",
+    spotlight,
+    grid: tiles(),
+    setVisibleTiles: () => {},
+  };
+}
+
+function portraitModel(): SpotlightPortraitLayout {
+  return {
+    type: "spotlight-portrait",
+    spotlight,
+    grid: tiles(),
+    setVisibleTiles: () => {},
+  };
+}
+
+// Slots record their drag callback so a test can drag them, and show the id
+// of the tile they hold
+const drags = new Map<string, DragCallback | undefined>();
+const Slot: LayoutProps<unknown, TileViewModel, HTMLDivElement>["Slot"] = ({
+  id,
+  model,
+  onDrag,
+  ...props
+}) => {
+  drags.set(id, onDrag);
+  return (
+    <div data-testid={`slot-${id}`} {...props}>
+      {model instanceof GridTileViewModel ? model.id : "spotlight"}
+    </div>
+  );
+};
+
+function slotIds(): string[] {
+  return screen
+    .getAllByTestId(/^slot-/)
+    .map((slot) => slot.textContent ?? "")
+    .filter((id) => id !== "spotlight");
+}

src/grid/CallLayout.ts

@@ -5,11 +5,11 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE in the repository root for full details.
 */
 
-import { type Observable } from "rxjs";
 import { type ComponentType } from "react";
 
 import { type LayoutProps } from "./Grid";
 import { type TileViewModel } from "../state/TileViewModel";
+import { type Behavior } from "../state/Behavior";
 
 export interface Bounds {
   width: number;
@@ -20,7 +20,7 @@ export interface CallLayoutInputs {
   /**
    * The minimum bounds of the layout area.
    */
-  minBounds$: Observable<Bounds>;
+  minBounds$: Behavior<Bounds>;
 }
 
 export interface CallLayoutOutputs<Model> {

src/grid/GridLayout.tsx

@@ -11,14 +11,12 @@ import {
   useCallback,
   useMemo,
 } from "react";
-import { distinctUntilChanged } from "rxjs";
-import { useObservableEagerState } from "observable-hooks";
 
 import { type GridLayout as GridLayoutModel } from "../state/layout-types.ts";
 import styles from "./GridLayout.module.css";
-import { useInitial } from "../useInitial";
 import { type CallLayout, arrangeTiles } from "./CallLayout";
 import { type DragCallback, useUpdateLayout, useVisibleTiles } from "./Grid";
+import { useBehavior } from "../useBehavior";
 
 interface GridCSSProperties extends CSSProperties {
   "--gap": string;
@@ -39,22 +37,18 @@ export const makeGridLayout: CallLayout<GridLayoutModel> = ({
   // lives
   fixed: function GridLayoutFixed({ ref, model, Slot }): ReactNode {
     useUpdateLayout();
-    const alignment = useObservableEagerState(
-      useInitial(() =>
-        model.spotlightAlignment$.pipe(
-          distinctUntilChanged(
-            (a1, a2) => a1.block === a2.block && a1.inline === a2.inline,
-          ),
-        ),
-      ),
-    );
+    const alignment = useBehavior(model.spotlightAlignment$);
 
     const onDragSpotlight: DragCallback = useCallback(
-      ({ xRatio, yRatio }) =>
-        model.spotlightAlignment$.next({
-          block: yRatio < 0.5 ? "start" : "end",
-          inline: xRatio < 0.5 ? "start" : "end",
-        }),
+      ({ xRatio, yRatio }) => {
+        const block = yRatio < 0.5 ? "start" : "end";
+        const inline = xRatio < 0.5 ? "start" : "end";
+        // A drag reports the same alignment on every move; only a change is
+        // worth a re-render
+        const current = model.spotlightAlignment$.value;
+        if (current.block !== block || current.inline !== inline)
+          model.spotlightAlignment$.next({ block, inline });
+      },
       [model.spotlightAlignment$],
     );
 
@@ -78,7 +72,7 @@ export const makeGridLayout: CallLayout<GridLayoutModel> = ({
   scrolling: function GridLayout({ ref, model, Slot }): ReactNode {
     useUpdateLayout();
     useVisibleTiles(model.setVisibleTiles);
-    const { width, height: minHeight } = useObservableEagerState(minBounds$);
+    const { width, height: minHeight } = useBehavior(minBounds$);
     const { gap, tileWidth, tileHeight } = useMemo(
       () => arrangeTiles(width, minHeight, model.grid.length),
       [width, minHeight, model.grid.length],

src/grid/OneOnOneDesktopLayout.tsx

@@ -7,7 +7,6 @@ Please see LICENSE in the repository root for full details.
 */
 
 import { type ReactNode, useCallback, useMemo } from "react";
-import { useObservableEagerState } from "observable-hooks";
 import classNames from "classnames";
 
 import { type OneOnOneDesktopLayout as OneOnOneDesktopLayoutModel } from "../state/layout-types.ts";
@@ -37,7 +36,7 @@ export const makeOneOnOneDesktopLayout: CallLayout<
     Slot,
   }): ReactNode {
     useUpdateLayout();
-    const { width, height } = useObservableEagerState(minBounds$);
+    const { width, height } = useBehavior(minBounds$);
     const pipAlignment = useBehavior(model.pipAlignment$);
     const { tileWidth, tileHeight } = useMemo(
       () => arrangeTiles(width, height, 1),

src/grid/SpotlightLandscapeLayout.tsx

@@ -6,7 +6,6 @@ Please see LICENSE in the repository root for full details.
 */
 
 import { type FC, type ReactNode } from "react";
-import { useObservableEagerState } from "observable-hooks";
 import classNames from "classnames";
 
 import { type CallLayout } from "./CallLayout";
@@ -33,7 +32,7 @@ export const makeSpotlightLandscapeLayout: CallLayout<
     Slot,
   }): ReactNode {
     useUpdateLayout();
-    useObservableEagerState(minBounds$);
+    useBehavior(minBounds$);
 
     return (
       <div ref={ref} className={styles.layer}>
@@ -56,7 +55,7 @@ export const makeSpotlightLandscapeLayout: CallLayout<
   }): ReactNode {
     useUpdateLayout();
     useVisibleTiles(model.setVisibleTiles);
-    useObservableEagerState(minBounds$);
+    useBehavior(minBounds$);
 
     return (
       <div ref={ref} className={styles.layer}>

src/grid/SpotlightPortraitLayout.tsx

@@ -6,7 +6,6 @@ Please see LICENSE in the repository root for full details.
 */
 
 import { type ReactNode, type CSSProperties } from "react";
-import { useObservableEagerState } from "observable-hooks";
 import classNames from "classnames";
 
 import { type CallLayout, arrangeTiles } from "./CallLayout";
@@ -58,7 +57,7 @@ export const makeSpotlightPortraitLayout: CallLayout<
   }): ReactNode {
     useUpdateLayout();
     useVisibleTiles(model.setVisibleTiles);
-    const { width } = useObservableEagerState(minBounds$);
+    const { width } = useBehavior(minBounds$);
     const { gap, tileWidth, tileHeight } = arrangeTiles(
       width,
       // TODO: We pretend that the minimum height is the width, because the

src/index.css

@@ -7,10 +7,24 @@ Please see LICENSE in the repository root for full details.
 
 /* Styles for Element Call as a page of its own. The parts that apply wherever
 Element Call is shown live in base.css; these are about owning the document,
-and are not loaded when a host embeds Element Call as a component. */
+and are not loaded when a host embeds Element Call as a component.
+
+That includes Compound: the page brings the design tokens, the component styles
+and their fonts, where a host embedding the component supplies its own. The
+`compound` layers are ordered by base.css. */
 
 @import url("./base.css");
 
+@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("@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);
+
 body {
   background-color: var(--cpd-color-bg-canvas-default);
   color: var(--cpd-color-text-primary);

src/livekit/BackgroundEffectTransformer.test.ts

@@ -0,0 +1,116 @@
+/*
+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, it, vi } from "vitest";
+import {
+  BackgroundTransformer,
+  VideoTransformer,
+  type VideoTransformerInitOptions,
+} from "@livekit/track-processors";
+import { ImageSegmenter } from "@mediapipe/tasks-vision";
+
+import {
+  BackgroundEffectTransformer,
+  canSegment,
+} from "./BackgroundEffectTransformer";
+
+const frame = {} as VideoFrame;
+const controller = {} as TransformStreamDefaultController<VideoFrame>;
+
+describe("BackgroundEffectTransformer", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("loads a background chosen before it was built", async () => {
+    vi.spyOn(VideoTransformer.prototype, "init").mockResolvedValue();
+    vi.spyOn(ImageSegmenter, "createFromOptions").mockResolvedValue(
+      {} as ImageSegmenter,
+    );
+    const load = vi
+      .spyOn(BackgroundTransformer.prototype, "loadAndSetBackground")
+      .mockResolvedValue();
+    const transformer = new BackgroundEffectTransformer({
+      backgroundDisabled: true,
+    });
+    // Chosen before the camera is processed, as the first effect always is:
+    // loaded then, there is nothing yet to draw it with.
+    await transformer.update({ imagePath: "/background.jpg" });
+    load.mockClear();
+
+    await transformer.init({} as VideoTransformerInitOptions);
+    expect(load).toHaveBeenCalledWith("/background.jpg");
+  });
+
+  it("reports the first frame carrying an effect, once", async () => {
+    vi.spyOn(BackgroundTransformer.prototype, "transform").mockImplementation(
+      async function (this: BackgroundTransformer) {
+        this.isFirstFrame = false;
+        return Promise.resolve();
+      },
+    );
+    const transformer = new BackgroundEffectTransformer({});
+    transformer.onFirstFrame = vi.fn();
+
+    await transformer.transform(frame, controller);
+    await transformer.transform(frame, controller);
+    expect(transformer.onFirstFrame).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not report a frame passed through untouched", async () => {
+    vi.spyOn(BackgroundTransformer.prototype, "transform").mockResolvedValue();
+    const transformer = new BackgroundEffectTransformer({
+      backgroundDisabled: true,
+    });
+    transformer.onFirstFrame = vi.fn();
+
+    await transformer.transform(frame, controller);
+    expect(transformer.onFirstFrame).not.toHaveBeenCalled();
+  });
+
+  it("passes frames on untouched once disabled, even after blurring", async () => {
+    const transformer = new BackgroundEffectTransformer({});
+    await transformer.update({ blurRadius: 15, backgroundDisabled: false });
+    await transformer.update({
+      imagePath: undefined,
+      backgroundDisabled: true,
+    });
+    // With neither, the library passes a frame on without segmenting it.
+    expect(transformer.options.blurRadius).toBeUndefined();
+    expect(transformer.options.imagePath).toBeUndefined();
+  });
+
+  it("segments on the CPU where the GPU refuses", async () => {
+    vi.spyOn(VideoTransformer.prototype, "init").mockResolvedValue();
+    const build = vi
+      .spyOn(ImageSegmenter, "createFromOptions")
+      .mockRejectedValueOnce(new Error("blocklisted"))
+      .mockResolvedValue({} as ImageSegmenter);
+
+    await new BackgroundEffectTransformer({}).init(
+      {} as VideoTransformerInitOptions,
+    );
+    expect(build.mock.calls.map(([, o]) => o.baseOptions?.delegate)).toEqual([
+      "GPU",
+      "CPU",
+    ]);
+  });
+
+  it("says whether a segmenter can be built at all", async () => {
+    vi.stubGlobal("OffscreenCanvas", class {});
+    const close = vi.fn();
+    const build = vi
+      .spyOn(ImageSegmenter, "createFromOptions")
+      .mockResolvedValue({ close } as unknown as ImageSegmenter);
+    expect(await canSegment()).toBe(true);
+    expect(close).toHaveBeenCalled();
+
+    build.mockRejectedValue(new Error("no model"));
+    expect(await canSegment()).toBe(false);
+  });
+});

src/livekit/BackgroundEffectTransformer.ts

@@ -0,0 +1,144 @@
+/*
+Copyright 2024-2025 New Vector Ltd.
+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 {
+  BackgroundTransformer,
+  VideoTransformer,
+  type VideoTransformerInitOptions,
+  type BackgroundOptions,
+  type SegmenterOptions,
+} from "@livekit/track-processors";
+import { logger } from "matrix-js-sdk/lib/logger";
+import { ImageSegmenter } from "@mediapipe/tasks-vision";
+
+import modelAssetPath from "../mediapipe/imageSegmenter/selfie_segmenter.tflite?url";
+
+interface WasmFileset {
+  /** The path to the Wasm loader script. */
+  wasmLoaderPath: string;
+  /** The path to the Wasm binary. */
+  wasmBinaryPath: string;
+}
+
+// The MediaPipe package, by default, ships some alternative versions of the
+// WASM files which avoid SIMD for compatibility with older browsers. But SIMD
+// in WASM is actually fine by our support policy, so we include just the SIMD
+// versions.
+// It's really not ideal that we have to reference these internal files from
+// MediaPipe and depend on node_modules having this specific structure. It's
+// easy to see this breaking if our dependencies changed and MediaPipe were
+// no longer hoisted, or if we switched to another dependency loader such as
+// yarn PnP.
+// https://github.com/google-ai-edge/mediapipe/issues/5961
+const wasmFileset: WasmFileset = {
+  wasmLoaderPath: new URL(
+    "../../node_modules/@mediapipe/tasks-vision/wasm/vision_wasm_internal.js",
+    import.meta.url,
+  ).href,
+  wasmBinaryPath: new URL(
+    "../../node_modules/@mediapipe/tasks-vision/wasm/vision_wasm_internal.wasm",
+    import.meta.url,
+  ).href,
+};
+
+/**
+ * Track processor that applies effects such as blurring to a user's background.
+ *
+ * This is just like LiveKit's prebuilt BackgroundTransformer except that it
+ * loads the segmentation models from our own bundle rather than as an external
+ * resource fetched from the public internet.
+ */
+export class BackgroundEffectTransformer extends BackgroundTransformer {
+  /** Called once, when the first frame carrying an effect has been drawn. */
+  public onFirstFrame: (() => void) | undefined;
+
+  public override async transform(
+    frame: VideoFrame,
+    controller: TransformStreamDefaultController<VideoFrame>,
+  ): Promise<void> {
+    const priming = this.isFirstFrame;
+    await super.transform(frame, controller);
+    // Cleared only once a frame has been through the segmenter; a frame
+    // passed through untouched leaves it set.
+    if (priming && !this.isFirstFrame) this.onFirstFrame?.();
+  }
+
+  /**
+   * As the library's, except that disabling also drops the blur radius: kept,
+   * it has every frame segmented and the result thrown away, where with
+   * neither a radius nor a picture frames are passed on untouched.
+   */
+  public override async update(opts: BackgroundOptions): Promise<void> {
+    await super.update(
+      opts.backgroundDisabled ? { ...opts, blurRadius: undefined } : opts,
+    );
+  }
+
+  public async init({
+    outputCanvas,
+    inputElement: inputVideo,
+  }: VideoTransformerInitOptions): Promise<void> {
+    // Call super.super.init() since we're totally replacing the init method of
+    // BackgroundTransformer here, rather than extending it
+    await VideoTransformer.prototype.init.call(this, {
+      outputCanvas,
+      inputElement: inputVideo,
+    });
+
+    this.imageSegmenter = await createSegmenter(
+      this.canvas,
+      this.options.segmenterOptions,
+    );
+
+    // BackgroundTransformer's own init applies these, and this one replaces it.
+    if (this.options.imagePath) {
+      await this.loadAndSetBackground(this.options.imagePath).catch((e) =>
+        logger.warn("Failed to load the background image", e),
+      );
+    }
+    if (this.options.blurRadius) {
+      this.gl?.setBlurRadius(this.options.blurRadius);
+    }
+    this.gl?.setBackgroundDisabled(this.options.backgroundDisabled ?? false);
+  }
+}
+
+/**
+ * Whether a segmenter can be built here, asked once before any camera depends
+ * on one: a pipeline that fails to build takes the camera down with it.
+ */
+export async function canSegment(): Promise<boolean> {
+  try {
+    (await createSegmenter(new OffscreenCanvas(1, 1))).close();
+    return true;
+  } catch (e) {
+    logger.warn("Background effects cannot run here", e);
+    return false;
+  }
+}
+
+/** On the GPU, or on the CPU where the GPU refuses, as a blocklisted one does. */
+async function createSegmenter(
+  canvas: HTMLCanvasElement | OffscreenCanvas | undefined,
+  segmenterOptions?: SegmenterOptions,
+): Promise<ImageSegmenter> {
+  const build = async (delegate: "GPU" | "CPU"): Promise<ImageSegmenter> =>
+    ImageSegmenter.createFromOptions(wasmFileset, {
+      baseOptions: { modelAssetPath, delegate, ...segmenterOptions },
+      canvas,
+      runningMode: "VIDEO",
+      outputCategoryMask: true,
+      outputConfidenceMasks: false,
+    });
+  try {
+    return await build("GPU");
+  } catch (e) {
+    logger.warn("Segmenting on the CPU, as the GPU refused", e);
+    return build("CPU");
+  }
+}

src/livekit/BackgroundEffectsContext.test.ts

@@ -0,0 +1,347 @@
+/*
+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 { act, createElement, type FC } from "react";
+import { render } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { type LocalVideoTrack } from "livekit-client";
+import { BehaviorSubject } from "rxjs";
+import {
+  type BackgroundOptions,
+  type ProcessorWrapper,
+} from "@livekit/track-processors";
+
+import {
+  applyProcessor,
+  BackgroundEffectsProvider,
+  type BackgroundEffectsState,
+  syncBackgroundEffects,
+  useBackgroundEffects,
+  useSyncBackgroundEffects,
+  createAppBackgroundEffects,
+} from "./BackgroundEffectsContext";
+import { type BackgroundEffects } from "../state/BackgroundEffects";
+import { backgroundEffect } from "../settings/settings";
+import { SyncedCameraTrack } from "./cameraTrack";
+import { type AddedBackground } from "./backgroundImages";
+import { constant } from "../state/Behavior";
+import { flushPromises, testScope } from "../utils/test";
+
+const sdkSupportMock = vi.hoisted(() => vi.fn(() => true));
+const pipelines = vi.hoisted(() => ({
+  built: 0,
+  destroyed: 0,
+  switches: [] as unknown[],
+}));
+
+// The pipeline itself needs WebGL and MediaPipe; what these tests are about is
+// what the provider asks of it.
+vi.mock("@livekit/track-processors", () => ({
+  BackgroundProcessorWrapper: vi.fn(function (this: Record<string, unknown>) {
+    pipelines.built += 1;
+    this.switchTo = vi.fn(async (options: unknown) => {
+      pipelines.switches.push(options);
+      return Promise.resolve();
+    });
+    this.destroy = vi.fn(async () => {
+      pipelines.destroyed += 1;
+      return Promise.resolve();
+    });
+  }),
+  supportsBackgroundProcessors: (): boolean => sdkSupportMock(),
+}));
+const platformMock = vi.hoisted(() => ({ platform: "desktop" }));
+vi.mock("../Platform", () => platformMock);
+vi.mock("./backgroundImages", async () => {
+  const { BehaviorSubject } = await import("rxjs");
+  return {
+    addedBackgrounds: {
+      added$: new BehaviorSubject<AddedBackground[] | undefined>(undefined),
+    },
+  };
+});
+vi.mock("./BackgroundEffectTransformer", () => ({
+  BackgroundEffectTransformer: vi.fn(function () {}),
+  canSegment: async (): Promise<boolean> => Promise.resolve(true),
+}));
+
+const processor = {} as ProcessorWrapper<BackgroundOptions>;
+
+function mockTrack(
+  readyState: MediaStreamTrackState,
+  current?: ProcessorWrapper<BackgroundOptions>,
+): LocalVideoTrack {
+  return {
+    mediaStreamTrack: { readyState },
+    getProcessor: vi.fn().mockReturnValue(current),
+    setProcessor: vi.fn().mockResolvedValue(undefined),
+    stopProcessor: vi.fn().mockResolvedValue(undefined),
+  } as unknown as LocalVideoTrack;
+}
+
+describe("applyProcessor", () => {
+  it("attaches the processor to a live track", () => {
+    const track = mockTrack("live");
+    applyProcessor(track, processor);
+    expect(track.setProcessor).toHaveBeenCalledWith(processor);
+  });
+
+  it("does not attach the processor to an ended track", () => {
+    const track = mockTrack("ended");
+    applyProcessor(track, processor);
+    expect(track.setProcessor).not.toHaveBeenCalled();
+  });
+
+  it("does not surface a rejected setProcessor", async () => {
+    const track = mockTrack("live");
+    vi.mocked(track.setProcessor).mockRejectedValue(
+      new TypeError("Input track cannot be ended"),
+    );
+    const unhandled = vi.fn();
+    process.on("unhandledRejection", unhandled);
+    applyProcessor(track, processor);
+    await flushPromises();
+    process.off("unhandledRejection", unhandled);
+    expect(unhandled).not.toHaveBeenCalled();
+  });
+
+  it("stops the processor when none is wanted", () => {
+    const track = mockTrack("live", processor);
+    applyProcessor(track, undefined);
+    expect(track.stopProcessor).toHaveBeenCalled();
+  });
+
+  it("does not surface a rejected stopProcessor", async () => {
+    const track = mockTrack("live", processor);
+    vi.mocked(track.stopProcessor).mockRejectedValue(new Error("nope"));
+    const unhandled = vi.fn();
+    process.on("unhandledRejection", unhandled);
+    applyProcessor(track, undefined);
+    await flushPromises();
+    process.off("unhandledRejection", unhandled);
+    expect(unhandled).not.toHaveBeenCalled();
+  });
+});
+
+describe("syncBackgroundEffects", () => {
+  it("applies the processor to the current track", () => {
+    const track = mockTrack("live");
+    syncBackgroundEffects(
+      testScope(),
+      constant(track),
+      constant({ supported: true, processor }),
+    );
+    expect(track.setProcessor).toHaveBeenCalledWith(processor);
+  });
+});
+
+describe("the synced camera", () => {
+  it("is the track last synced, and cleared only while still its own", () => {
+    const camera = new SyncedCameraTrack();
+    const pipeline = constant<BackgroundEffectsState>({
+      supported: false,
+      processor: undefined,
+      cameraTrack: camera,
+    });
+    const lobby = mockTrack("live");
+    const call = mockTrack("live");
+    const lobbyTrack$ = new BehaviorSubject<LocalVideoTrack | null>(lobby);
+    syncBackgroundEffects(testScope(), lobbyTrack$, pipeline);
+    expect(camera.track$.value).toBe(lobby);
+
+    const callScope = testScope();
+    syncBackgroundEffects(callScope, constant(call), pipeline);
+    expect(camera.track$.value).toBe(call);
+
+    lobbyTrack$.next(null);
+    expect(camera.track$.value).toBe(call);
+    callScope.end();
+    expect(camera.track$.value).toBeNull();
+  });
+
+  it("reports the camera once, however often the pipeline's state changes", () => {
+    const camera = new SyncedCameraTrack();
+    const report = vi.spyOn(camera, "report");
+    const state$ = new BehaviorSubject<BackgroundEffectsState>({
+      supported: true,
+      processor: undefined,
+      cameraTrack: camera,
+    });
+    syncBackgroundEffects(testScope(), constant(mockTrack("live")), state$);
+    state$.next({ ...state$.value, settling: true });
+    state$.next({ ...state$.value, settling: false });
+    expect(report).toHaveBeenCalledOnce();
+  });
+
+  it("keeps each call's camera to its own", () => {
+    const seen: (SyncedCameraTrack | undefined)[] = [];
+    const Call: FC<{ track: LocalVideoTrack }> = ({ track }) => {
+      const { cameraTrack } = useBackgroundEffects();
+      seen.push(cameraTrack);
+      useSyncBackgroundEffects(track);
+      return null;
+    };
+    const first = mockTrack("live");
+    const second = mockTrack("live");
+    render(
+      createElement(
+        "div",
+        null,
+        createElement(BackgroundEffectsProvider, {
+          effects: createAppBackgroundEffects(testScope()),
+          children: createElement(Call, { track: first }),
+        }),
+        createElement(BackgroundEffectsProvider, {
+          effects: createAppBackgroundEffects(testScope()),
+          children: createElement(Call, { track: second }),
+        }),
+      ),
+    );
+    const [mine, theirs] = [...new Set(seen)];
+    expect(mine).not.toBe(theirs);
+    expect(mine?.track$.value).toBe(first);
+    expect(theirs?.track$.value).toBe(second);
+  });
+});
+
+describe("BackgroundEffectsProvider", () => {
+  /** A camera track that holds whatever processor it is given. */
+  function cameraTrack(): LocalVideoTrack {
+    let current: unknown;
+    return {
+      mediaStreamTrack: { readyState: "live" },
+      getProcessor: vi.fn(() => current),
+      setProcessor: vi.fn(async (next: unknown) => {
+        current = next;
+        return Promise.resolve();
+      }),
+      stopProcessor: vi.fn(async () => {
+        current = undefined;
+        return Promise.resolve();
+      }),
+    } as unknown as LocalVideoTrack;
+  }
+
+  let seen: BackgroundEffectsState[];
+  const Surface: FC<{ track: LocalVideoTrack | null }> = ({ track }) => {
+    seen.push(useBackgroundEffects());
+    useSyncBackgroundEffects(track);
+    return null;
+  };
+  // One component for every render, so a rerender updates the tree rather than
+  // mounting a second provider with a pipeline of its own.
+  let effects: BackgroundEffects | undefined;
+  const Surfaces: FC<{ tracks: (LocalVideoTrack | null)[] }> = ({ tracks }) =>
+    createElement(BackgroundEffectsProvider, {
+      // Made on first render, once a test has set up the platform.
+      effects: (effects ??= createAppBackgroundEffects(testScope())),
+      children: createElement(
+        "div",
+        null,
+        ...tracks.map((track, key) => createElement(Surface, { key, track })),
+      ),
+    });
+  const surfaces = (
+    ...tracks: (LocalVideoTrack | null)[]
+  ): ReturnType<typeof createElement> => createElement(Surfaces, { tracks });
+  const blur = async (on: boolean): Promise<void> => {
+    await act(async () => {
+      backgroundEffect.setValue(on ? "blur" : "none");
+      await flushPromises();
+    });
+  };
+  const latest = (): BackgroundEffectsState => seen[seen.length - 1];
+
+  beforeEach(() => {
+    seen = [];
+    effects = undefined;
+    pipelines.built = 0;
+    pipelines.destroyed = 0;
+    pipelines.switches = [];
+    platformMock.platform = "desktop";
+    sdkSupportMock.mockReturnValue(true);
+    backgroundEffect.setValue("none");
+  });
+  afterEach(() => backgroundEffect.setValue("none"));
+
+  // A pipeline primes itself when it is built and when it is destroyed, and a
+  // primed pipeline lets one frame through untouched: so the frame is spent
+  // once, as long as it is built once and never taken off the camera.
+  it("spends one priming frame on first use and none afterwards", async () => {
+    const track = cameraTrack();
+    render(surfaces(track));
+    for (const on of [true, false, true, false, true]) await blur(on);
+
+    expect(pipelines.built).toBe(1);
+    expect(pipelines.destroyed).toBe(0);
+    expect(track.setProcessor).toHaveBeenCalledTimes(1);
+    expect(track.stopProcessor).not.toHaveBeenCalled();
+  });
+
+  it("camera on with an effect chosen publishes nothing unprocessed", async () => {
+    const view = render(surfaces(cameraTrack()));
+    await blur(true);
+    const pipeline = latest().processor;
+
+    // Camera off, then on again: a new track, given the pipeline as it
+    // arrives, and the pipeline neither rebuilt nor switched again.
+    await act(async () => {
+      view.rerender(surfaces(null));
+      await flushPromises();
+    });
+    const again = cameraTrack();
+    await act(async () => {
+      view.rerender(surfaces(again));
+      await flushPromises();
+    });
+    expect(again.setProcessor).toHaveBeenCalledTimes(1);
+    expect(again.setProcessor).toHaveBeenCalledWith(pipeline);
+    expect(pipelines.built).toBe(1);
+    expect(pipelines.switches).toHaveLength(1);
+  });
+
+  it("runs on a phone whose browser can run it", async () => {
+    platformMock.platform = "ios";
+    const track = cameraTrack();
+    render(surfaces(track));
+    await blur(true);
+
+    expect(latest().supported).toBe(true);
+    expect(track.setProcessor).toHaveBeenCalledWith(latest().processor);
+  });
+
+  it("preview and call share one pipeline", async () => {
+    const preview = cameraTrack();
+    const call = cameraTrack();
+    render(surfaces(preview, call));
+    await blur(true);
+
+    const pipeline = latest().processor;
+    expect(preview.setProcessor).toHaveBeenCalledWith(pipeline);
+    expect(call.setProcessor).toHaveBeenCalledWith(pipeline);
+    expect(pipelines.built).toBe(1);
+  });
+
+  it("applies an effect chosen while the camera is off", async () => {
+    const view = render(surfaces(null));
+    await blur(true);
+    // Already switched to blur, with nothing yet to attach it to.
+    expect(pipelines.switches).toEqual([
+      { mode: "background-blur", blurRadius: 15 },
+    ]);
+
+    const track = cameraTrack();
+    await act(async () => {
+      view.rerender(surfaces(track));
+      await flushPromises();
+    });
+    expect(track.setProcessor).toHaveBeenCalledTimes(1);
+    expect(track.setProcessor).toHaveBeenCalledWith(latest().processor);
+    expect(pipelines.built).toBe(1);
+    expect(pipelines.switches).toHaveLength(1);
+  });
+});

src/livekit/BackgroundEffectsContext.tsx

@@ -0,0 +1,180 @@
+/*
+Copyright 2024-2025 New Vector Ltd.
+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 ProcessorWrapper,
+  type BackgroundOptions,
+  supportsBackgroundProcessors,
+} from "@livekit/track-processors";
+import { createContext, type FC, type JSX, use, useEffect } from "react";
+import { type LocalVideoTrack } from "livekit-client";
+import { logger } from "matrix-js-sdk/lib/logger";
+import {
+  combineLatest,
+  distinctUntilChanged,
+  EMPTY,
+  map,
+  Observable,
+  switchMap,
+} from "rxjs";
+
+import { backgroundEffect as backgroundEffectSetting } from "../settings/settings";
+import {
+  BackgroundEffectTransformer,
+  canSegment,
+} from "./BackgroundEffectTransformer";
+import { type SyncedCameraTrack } from "./cameraTrack";
+import { OneStepPipeline } from "./OneStepPipeline";
+import { addedBackgrounds } from "./backgroundImages";
+import { type Behavior } from "../state/Behavior";
+import { type ObservableScope } from "../state/ObservableScope";
+import {
+  type BackgroundEffects,
+  createBackgroundEffects,
+} from "../state/BackgroundEffects";
+import { useBehavior } from "../useBehavior";
+
+//TODO-MULTI-SFU: This is not yet fully there.
+// it is a combination of exposing observable and react hooks.
+// preferably we should not make this a context anymore and instead just a vm?
+
+export type BackgroundEffectsState = {
+  supported: boolean | undefined;
+  processor: undefined | ProcessorWrapper<BackgroundOptions>;
+  /** From the first effect chosen until a frame carrying it is drawn. */
+  settling?: boolean;
+  /** The camera this provider's pipeline is synced to. */
+  cameraTrack?: SyncedCameraTrack;
+  /** While asking whether the pipeline can be built, before it is attached. */
+  preparing?: boolean;
+};
+
+const BackgroundEffectsContext = createContext<BackgroundEffects | undefined>(
+  undefined,
+);
+
+export function useBackgroundEffects(): BackgroundEffectsState {
+  return useBehavior(useBackgroundEffectsState$());
+}
+
+export function useBackgroundEffectsState$(): Behavior<BackgroundEffectsState> {
+  const effects = use(BackgroundEffectsContext);
+  if (effects === undefined)
+    throw new Error(
+      "useBackgroundEffects must be used within a BackgroundEffectsProvider",
+    );
+  return effects.state$;
+}
+
+/**
+ * Attaches or detaches the processor so that the track matches the desired
+ * state, without throwing.
+ */
+export function applyProcessor(
+  videoTrack: LocalVideoTrack,
+  processor: ProcessorWrapper<BackgroundOptions> | undefined,
+): void {
+  if (processor && !videoTrack.getProcessor()) {
+    // A MediaStreamTrackProcessor cannot be constructed on an ended track
+    // (e.g. the camera was stopped while the processor was being applied),
+    // and setProcessor rejects with a TypeError. The track is going away
+    // anyway, so there is nothing to attach to.
+    if (videoTrack.mediaStreamTrack.readyState === "ended") {
+      logger.debug("Not attaching video processor to an ended track");
+      return;
+    }
+    const track = videoTrack.mediaStreamTrack;
+    videoTrack.setProcessor(processor).catch((e) => {
+      if (track.readyState === "ended")
+        logger.debug("Video processor not attached: the track ended first");
+      else logger.warn("Failed to attach video processor", e);
+    });
+  }
+  if (!processor && videoTrack.getProcessor()) {
+    videoTrack.stopProcessor().catch((e) => {
+      logger.warn("Failed to stop video processor", e);
+    });
+  }
+}
+
+/**
+ * Updates your video tracks to always use the given processor.
+ */
+export const syncBackgroundEffects = (
+  scope: ObservableScope,
+  videoTrack$: Behavior<LocalVideoTrack | null>,
+  backgroundEffectsState$: Behavior<BackgroundEffectsState>,
+): void => {
+  combineLatest([videoTrack$, backgroundEffectsState$])
+    .pipe(scope.bind())
+    .subscribe(([videoTrack, backgroundEffectsState]) => {
+      if (!backgroundEffectsState) return;
+      if (!videoTrack) return;
+      applyProcessor(videoTrack, backgroundEffectsState.processor);
+    });
+  // Keyed on the camera alone: reporting again for every change of state would
+  // blank the preview each time.
+  combineLatest([
+    videoTrack$,
+    backgroundEffectsState$.pipe(
+      map(({ cameraTrack }) => cameraTrack),
+      distinctUntilChanged(),
+    ),
+  ])
+    .pipe(
+      switchMap(([track, cameraTrack]) =>
+        track === null || cameraTrack === undefined
+          ? EMPTY
+          : new Observable<never>(() => cameraTrack.report(track)),
+      ),
+      scope.bind(),
+    )
+    .subscribe();
+};
+
+export const useSyncBackgroundEffects = (
+  videoTrack: LocalVideoTrack | null,
+): void => {
+  const { processor, cameraTrack } = useBackgroundEffects();
+  useEffect(() => {
+    if (!videoTrack) return;
+    applyProcessor(videoTrack, processor);
+  }, [processor, videoTrack]);
+  useEffect(() => {
+    if (videoTrack && cameraTrack) return cameraTrack.report(videoTrack);
+  }, [cameraTrack, videoTrack]);
+};
+
+/** The app's one pipeline, shared by every camera track it opens. */
+export function createAppBackgroundEffects(
+  scope: ObservableScope,
+): BackgroundEffects {
+  const transformer = new BackgroundEffectTransformer({
+    backgroundDisabled: true,
+  });
+  return createBackgroundEffects(scope, {
+    supported: supportsBackgroundProcessors(),
+    effect$: backgroundEffectSetting.value$,
+    setEffect: backgroundEffectSetting.setValue,
+    added$: addedBackgrounds.added$,
+    canSegment,
+    pipeline: new OneStepPipeline(transformer, "background-effect"),
+    transformer,
+  });
+}
+
+interface Props {
+  effects: BackgroundEffects;
+  children: JSX.Element;
+}
+
+export const BackgroundEffectsProvider: FC<Props> = ({ effects, children }) => (
+  <BackgroundEffectsContext value={effects}>
+    {children}
+  </BackgroundEffectsContext>
+);

src/livekit/BlurBackgroundTransformer.ts

@@ -1,80 +0,0 @@
-/*
-Copyright 2024-2025 New Vector Ltd.
-
-SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
-Please see LICENSE in the repository root for full details.
-*/
-
-import {
-  BackgroundTransformer,
-  VideoTransformer,
-  type VideoTransformerInitOptions,
-} from "@livekit/track-processors";
-import { ImageSegmenter } from "@mediapipe/tasks-vision";
-
-import modelAssetPath from "../mediapipe/imageSegmenter/selfie_segmenter.tflite?url";
-
-interface WasmFileset {
-  /** The path to the Wasm loader script. */
-  wasmLoaderPath: string;
-  /** The path to the Wasm binary. */
-  wasmBinaryPath: string;
-}
-
-// The MediaPipe package, by default, ships some alternative versions of the
-// WASM files which avoid SIMD for compatibility with older browsers. But SIMD
-// in WASM is actually fine by our support policy, so we include just the SIMD
-// versions.
-// It's really not ideal that we have to reference these internal files from
-// MediaPipe and depend on node_modules having this specific structure. It's
-// easy to see this breaking if our dependencies changed and MediaPipe were
-// no longer hoisted, or if we switched to another dependency loader such as
-// yarn PnP.
-// https://github.com/google-ai-edge/mediapipe/issues/5961
-const wasmFileset: WasmFileset = {
-  wasmLoaderPath: new URL(
-    "../../node_modules/@mediapipe/tasks-vision/wasm/vision_wasm_internal.js",
-    import.meta.url,
-  ).href,
-  wasmBinaryPath: new URL(
-    "../../node_modules/@mediapipe/tasks-vision/wasm/vision_wasm_internal.wasm",
-    import.meta.url,
-  ).href,
-};
-
-/**
- * Track processor that applies effects such as blurring to a user's background.
- *
- * This is just like LiveKit's prebuilt BackgroundTransformer except that it
- * loads the segmentation models from our own bundle rather than as an external
- * resource fetched from the public internet.
- */
-export class BlurBackgroundTransformer extends BackgroundTransformer {
-  public async init({
-    outputCanvas,
-    inputElement: inputVideo,
-  }: VideoTransformerInitOptions): Promise<void> {
-    // Call super.super.init() since we're totally replacing the init method of
-    // BackgroundTransformer here, rather than extending it
-    await VideoTransformer.prototype.init.call(this, {
-      outputCanvas,
-      inputElement: inputVideo,
-    });
-
-    this.imageSegmenter = await ImageSegmenter.createFromOptions(wasmFileset, {
-      baseOptions: {
-        modelAssetPath,
-        delegate: "GPU",
-        ...this.options.segmenterOptions,
-      },
-      canvas: this.canvas,
-      runningMode: "VIDEO",
-      outputCategoryMask: true,
-      outputConfidenceMasks: false,
-    });
-
-    if (this.options.blurRadius) {
-      this.gl?.setBlurRadius(this.options.blurRadius);
-    }
-  }
-}

src/livekit/OneStepPipeline.test.ts

@@ -0,0 +1,80 @@
+/*
+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, it, vi } from "vitest";
+import { ProcessorWrapper } from "@livekit/track-processors";
+
+import { OneStepPipeline } from "./OneStepPipeline";
+import { BackgroundEffectTransformer } from "./BackgroundEffectTransformer";
+import { flushPromises } from "../utils/test";
+
+const opts = {} as Parameters<OneStepPipeline["init"]>[0];
+
+describe("OneStepPipeline", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("stops and builds again only once a build has finished", async () => {
+    let finishBuild!: () => void;
+    const init = vi
+      .spyOn(ProcessorWrapper.prototype, "init")
+      .mockImplementationOnce(
+        async () => new Promise((resolve) => (finishBuild = resolve)),
+      )
+      .mockResolvedValue();
+    const destroy = vi
+      .spyOn(ProcessorWrapper.prototype, "destroy")
+      .mockResolvedValue();
+    const pipeline = new OneStepPipeline(
+      new BackgroundEffectTransformer({}),
+      "test",
+    );
+
+    const first = pipeline.init(opts);
+    const stopped = pipeline.destroy();
+    const second = pipeline.init(opts);
+    await flushPromises();
+    expect(init).toHaveBeenCalledTimes(1);
+    expect(destroy).not.toHaveBeenCalled();
+
+    finishBuild();
+    await Promise.all([first, stopped, second]);
+    expect(init).toHaveBeenCalledTimes(2);
+    expect(destroy.mock.invocationCallOrder[0]).toBeLessThan(
+      init.mock.invocationCallOrder[1],
+    );
+  });
+
+  it("restarts in one step, without waiting on itself", async () => {
+    const init = vi
+      .spyOn(ProcessorWrapper.prototype, "init")
+      .mockResolvedValue();
+    const destroy = vi
+      .spyOn(ProcessorWrapper.prototype, "destroy")
+      .mockResolvedValue();
+    const pipeline = new OneStepPipeline(
+      new BackgroundEffectTransformer({}),
+      "test",
+    );
+
+    await pipeline.restart(opts);
+    expect(destroy).toHaveBeenCalledWith({ willProcessorRestart: true });
+    expect(init).toHaveBeenCalledOnce();
+  });
+
+  it("carries on after a step that failed", async () => {
+    vi.spyOn(ProcessorWrapper.prototype, "init")
+      .mockRejectedValueOnce(new Error("no GPU"))
+      .mockResolvedValue();
+    const pipeline = new OneStepPipeline(
+      new BackgroundEffectTransformer({}),
+      "test",
+    );
+
+    await expect(pipeline.init(opts)).rejects.toThrow("no GPU");
+    await expect(pipeline.init(opts)).resolves.toBeUndefined();
+  });
+});

src/livekit/OneStepPipeline.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 { BackgroundProcessorWrapper } from "@livekit/track-processors";
+
+type InitOptions = Parameters<BackgroundProcessorWrapper["init"]>[0];
+type DestroyOptions = Parameters<BackgroundProcessorWrapper["destroy"]>[0];
+
+/**
+ * A background pipeline that is built, rebuilt and destroyed one step at a
+ * time. The camera tracks sharing it attach and stop it independently, and
+ * the SDK's wrapper holds a single track's streams: two builds at once
+ * overwrite each other's, and a destroy during a build does nothing.
+ */
+export class OneStepPipeline extends BackgroundProcessorWrapper {
+  private steps: Promise<void> = Promise.resolve();
+
+  public override async init(opts: InitOptions): Promise<void> {
+    return this.inTurn(async () => super.init(opts));
+  }
+
+  // The SDK's restart calls init and destroy, which would wait on itself.
+  public override async restart(opts: InitOptions): Promise<void> {
+    return this.inTurn(async () => {
+      await super.destroy({ willProcessorRestart: true });
+      await super.init(opts);
+    });
+  }
+
+  public override async destroy(options?: DestroyOptions): Promise<void> {
+    return this.inTurn(async () => super.destroy(options));
+  }
+
+  private async inTurn(step: () => Promise<void>): Promise<void> {
+    const turn = this.steps.then(step);
+    this.steps = turn.catch(() => {});
+    return turn;
+  }
+}

src/livekit/TrackProcessorContext.test.ts

@@ -1,87 +0,0 @@
-/*
-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, vi } from "vitest";
-import { type LocalVideoTrack } from "livekit-client";
-import {
-  type BackgroundOptions,
-  type ProcessorWrapper,
-} from "@livekit/track-processors";
-
-import { applyProcessor, trackProcessorSync } from "./TrackProcessorContext";
-import { constant } from "../state/Behavior";
-import { flushPromises, testScope } from "../utils/test";
-
-const processor = {} as ProcessorWrapper<BackgroundOptions>;
-
-function mockTrack(
-  readyState: MediaStreamTrackState,
-  current?: ProcessorWrapper<BackgroundOptions>,
-): LocalVideoTrack {
-  return {
-    mediaStreamTrack: { readyState },
-    getProcessor: vi.fn().mockReturnValue(current),
-    setProcessor: vi.fn().mockResolvedValue(undefined),
-    stopProcessor: vi.fn().mockResolvedValue(undefined),
-  } as unknown as LocalVideoTrack;
-}
-
-describe("applyProcessor", () => {
-  it("attaches the processor to a live track", () => {
-    const track = mockTrack("live");
-    applyProcessor(track, processor);
-    expect(track.setProcessor).toHaveBeenCalledWith(processor);
-  });
-
-  it("does not attach the processor to an ended track", () => {
-    const track = mockTrack("ended");
-    applyProcessor(track, processor);
-    expect(track.setProcessor).not.toHaveBeenCalled();
-  });
-
-  it("does not surface a rejected setProcessor", async () => {
-    const track = mockTrack("live");
-    vi.mocked(track.setProcessor).mockRejectedValue(
-      new TypeError("Input track cannot be ended"),
-    );
-    const unhandled = vi.fn();
-    process.on("unhandledRejection", unhandled);
-    applyProcessor(track, processor);
-    await flushPromises();
-    process.off("unhandledRejection", unhandled);
-    expect(unhandled).not.toHaveBeenCalled();
-  });
-
-  it("stops the processor when none is wanted", () => {
-    const track = mockTrack("live", processor);
-    applyProcessor(track, undefined);
-    expect(track.stopProcessor).toHaveBeenCalled();
-  });
-
-  it("does not surface a rejected stopProcessor", async () => {
-    const track = mockTrack("live", processor);
-    vi.mocked(track.stopProcessor).mockRejectedValue(new Error("nope"));
-    const unhandled = vi.fn();
-    process.on("unhandledRejection", unhandled);
-    applyProcessor(track, undefined);
-    await flushPromises();
-    process.off("unhandledRejection", unhandled);
-    expect(unhandled).not.toHaveBeenCalled();
-  });
-});
-
-describe("trackProcessorSync", () => {
-  it("applies the processor to the current track", () => {
-    const track = mockTrack("live");
-    trackProcessorSync(
-      testScope(),
-      constant(track),
-      constant({ supported: true, processor }),
-    );
-    expect(track.setProcessor).toHaveBeenCalledWith(processor);
-  });
-});

src/livekit/TrackProcessorContext.tsx

@@ -1,155 +0,0 @@
-/*
-Copyright 2024-2025 New Vector Ltd.
-
-SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
-Please see LICENSE in the repository root for full details.
-*/
-
-import {
-  ProcessorWrapper,
-  supportsBackgroundProcessors as supportsBackgroundProcessorsLivekitSdk,
-  type BackgroundOptions,
-} from "@livekit/track-processors";
-import {
-  createContext,
-  type FC,
-  type JSX,
-  use,
-  useEffect,
-  useMemo,
-} from "react";
-import { type LocalVideoTrack } from "livekit-client";
-import { logger } from "matrix-js-sdk/lib/logger";
-import { combineLatest, map, type Observable } from "rxjs";
-import { useObservable } from "observable-hooks";
-
-import {
-  backgroundBlur as backgroundBlurSettings,
-  useSetting,
-} from "../settings/settings";
-import { BlurBackgroundTransformer } from "./BlurBackgroundTransformer";
-import { type Behavior } from "../state/Behavior";
-import { type ObservableScope } from "../state/ObservableScope";
-import { platform } from "../Platform";
-
-//TODO-MULTI-SFU: This is not yet fully there.
-// it is a combination of exposing observable and react hooks.
-// preferably we should not make this a context anymore and instead just a vm?
-
-export type ProcessorState = {
-  supported: boolean | undefined;
-  processor: undefined | ProcessorWrapper<BackgroundOptions>;
-};
-
-const ProcessorContext = createContext<ProcessorState | undefined>(undefined);
-
-export function useTrackProcessor(): ProcessorState {
-  const state = use(ProcessorContext);
-  if (state === undefined)
-    throw new Error(
-      "useTrackProcessor must be used within a ProcessorProvider",
-    );
-  return state;
-}
-
-export function useTrackProcessorObservable$(): Observable<ProcessorState> {
-  const state = use(ProcessorContext);
-  if (state === undefined)
-    throw new Error(
-      "useTrackProcessor must be used within a ProcessorProvider",
-    );
-  const state$ = useObservable(
-    (init$) => init$.pipe(map(([init]) => init)),
-    [state],
-  );
-
-  return state$;
-}
-
-/**
- * Attaches or detaches the processor so that the track matches the desired
- * state, without throwing.
- */
-export function applyProcessor(
-  videoTrack: LocalVideoTrack,
-  processor: ProcessorWrapper<BackgroundOptions> | undefined,
-): void {
-  if (processor && !videoTrack.getProcessor()) {
-    // A MediaStreamTrackProcessor cannot be constructed on an ended track
-    // (e.g. the camera was stopped while the processor was being applied),
-    // and setProcessor rejects with a TypeError. The track is going away
-    // anyway, so there is nothing to attach to.
-    if (videoTrack.mediaStreamTrack.readyState === "ended") {
-      logger.debug("Not attaching video processor to an ended track");
-      return;
-    }
-    videoTrack.setProcessor(processor).catch((e) => {
-      logger.warn("Failed to attach video processor", e);
-    });
-  }
-  if (!processor && videoTrack.getProcessor()) {
-    videoTrack.stopProcessor().catch((e) => {
-      logger.warn("Failed to stop video processor", e);
-    });
-  }
-}
-
-/**
- * Updates your video tracks to always use the given processor.
- */
-export const trackProcessorSync = (
-  scope: ObservableScope,
-  videoTrack$: Behavior<LocalVideoTrack | null>,
-  processor$: Behavior<ProcessorState>,
-): void => {
-  combineLatest([videoTrack$, processor$])
-    .pipe(scope.bind())
-    .subscribe(([videoTrack, processorState]) => {
-      if (!processorState) return;
-      if (!videoTrack) return;
-      applyProcessor(videoTrack, processorState.processor);
-    });
-};
-
-export const useTrackProcessorSync = (
-  videoTrack: LocalVideoTrack | null,
-): void => {
-  const { processor } = useTrackProcessor();
-  useEffect(() => {
-    if (!videoTrack) return;
-    applyProcessor(videoTrack, processor);
-  }, [processor, videoTrack]);
-};
-
-interface Props {
-  children: JSX.Element;
-}
-
-function supportsBackgroundProcessors(): boolean {
-  return supportsBackgroundProcessorsLivekitSdk() && platform === "desktop";
-}
-
-export const ProcessorProvider: FC<Props> = ({ children }) => {
-  // The setting the user wants to have
-  const [blurActivated] = useSetting(backgroundBlurSettings);
-  const supported = useMemo(() => supportsBackgroundProcessors(), []);
-  const blur = useMemo(
-    () =>
-      new ProcessorWrapper(
-        new BlurBackgroundTransformer({ blurRadius: 15 }),
-        "background-blur",
-      ),
-    [],
-  );
-
-  // This is the actual state exposed through the context
-  const processorState = useMemo(
-    () => ({
-      supported,
-      processor: supported && blurActivated ? blur : undefined,
-    }),
-    [supported, blurActivated, blur],
-  );
-
-  return <ProcessorContext value={processorState}>{children}</ProcessorContext>;
-};

src/livekit/backgroundEffects.test.ts

@@ -0,0 +1,64 @@
+/*
+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 { readFile } from "node:fs/promises";
+import { describe, expect, test } from "vitest";
+
+import {
+  type BackgroundEffect,
+  imagePathFor,
+  parseEffect,
+  serializeEffect,
+  shippedBackgrounds,
+} from "./backgroundEffects";
+import { maxAddedBackgrounds } from "./backgroundImages";
+
+describe("the chosen background effect", () => {
+  test("round-trips through its stored form", () => {
+    const effects: BackgroundEffect[] = [
+      { kind: "none" },
+      { kind: "blur" },
+      ...shippedBackgrounds.map(({ id }) => ({ kind: "shipped" as const, id })),
+      { kind: "added", id: "d3b07384" },
+    ];
+    for (const effect of effects)
+      expect(parseEffect(serializeEffect(effect))).toEqual(effect);
+  });
+
+  test("falls back to no effect when the stored form names nothing we ship", () => {
+    expect(parseEffect("image:gone")).toEqual({ kind: "none" });
+    expect(parseEffect("")).toEqual({ kind: "none" });
+    expect(parseEffect("added:")).toEqual({ kind: "none" });
+  });
+
+  test("reads a stored value that is not a string as no effect", () => {
+    for (const raw of [null, 1, {}, ["blur"]])
+      expect(parseEffect(raw)).toEqual({ kind: "none" });
+  });
+
+  test("fills the grid at the limit and one short of it", () => {
+    // No effect, blur and the shipped ones, then the added ones.
+    const fixed = 2 + shippedBackgrounds.length;
+    expect((fixed + maxAddedBackgrounds) % 3).toBe(0);
+    // One short, the add tile takes the last place.
+    expect((fixed + maxAddedBackgrounds - 1 + 1) % 3).toBe(0);
+  });
+
+  test("gives every shipped background an image to draw", () => {
+    for (const { id } of shippedBackgrounds)
+      expect(imagePathFor(id)).toBeTruthy();
+  });
+
+  // A background has to cover what is behind it: JPEG has no alpha channel.
+  test("ships only opaque backgrounds", async () => {
+    for (const { imagePath } of shippedBackgrounds) {
+      const name = imagePath.split("/").pop()!.split("?")[0];
+      const bytes = await readFile(`src/graphics/${name}`);
+      expect([bytes[0], bytes[1], bytes[2]]).toEqual([0xff, 0xd8, 0xff]);
+    }
+  });
+});

src/livekit/backgroundEffects.ts

@@ -0,0 +1,70 @@
+/*
+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 arc from "../graphics/background-arc.jpg?url";
+import glow from "../graphics/background-glow.jpg?url";
+
+export const blurRadius = 15;
+
+export interface ShippedBackground {
+  /** Stored in the user's settings when chosen, so it must not change. */
+  id: string;
+  imagePath: string;
+}
+
+export const shippedBackgrounds: ShippedBackground[] = [
+  { id: "arc", imagePath: arc },
+  { id: "glow", imagePath: glow },
+];
+
+export type BackgroundEffect =
+  | { kind: "none" }
+  | { kind: "blur" }
+  | { kind: "shipped"; id: string }
+  | { kind: "added"; id: string };
+
+/** An effect as the setting stores it, and as the menu names its option. */
+export type EffectId = "none" | "blur" | `image:${string}` | `added:${string}`;
+
+export const noEffect: BackgroundEffect = { kind: "none" };
+
+/**
+ * Reads a stored effect; one we no longer ship reads as no effect. Whether an
+ * added one is still kept only the device knows. Stored by hand or by another
+ * build, the value need not even be a string.
+ */
+export function parseEffect(raw: unknown): BackgroundEffect {
+  if (typeof raw !== "string") return noEffect;
+  if (raw === "blur") return { kind: "blur" };
+  if (raw.startsWith("image:")) {
+    const id = raw.slice("image:".length);
+    if (shippedBackgrounds.some((b) => b.id === id))
+      return { kind: "shipped", id };
+  }
+  if (raw.startsWith("added:")) {
+    const id = raw.slice("added:".length);
+    if (id) return { kind: "added", id };
+  }
+  return noEffect;
+}
+
+export function serializeEffect(effect: BackgroundEffect): EffectId {
+  switch (effect.kind) {
+    case "blur":
+      return "blur";
+    case "shipped":
+      return `image:${effect.id}`;
+    case "added":
+      return `added:${effect.id}`;
+    default:
+      return "none";
+  }
+}
+
+export function imagePathFor(id: string): string | undefined {
+  return shippedBackgrounds.find((b) => b.id === id)?.imagePath;
+}

src/livekit/backgroundImages.test.ts

@@ -0,0 +1,172 @@
+/*
+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 { beforeEach, describe, expect, it, vi } from "vitest";
+import { IDBFactory } from "fake-indexeddb";
+
+import {
+  AddedBackgrounds,
+  type BackgroundImageStorage,
+  IndexedDBImageStorage,
+  type KeptImage,
+  maxAddedBackgrounds,
+  prepareImage,
+  UnusableImage,
+} from "./backgroundImages";
+import { flushPromises } from "../utils/test";
+
+describe("AddedBackgrounds", () => {
+  beforeEach(() => {
+    let n = 0;
+    vi.spyOn(URL, "createObjectURL").mockImplementation(() => `blob:${++n}`);
+  });
+
+  it("offers what the device keeps, oldest first", async () => {
+    const image = new Blob(["x"], { type: "image/png" });
+    const store = new AddedBackgrounds(
+      memoryStorage([
+        { id: "later", image, addedAt: 2 },
+        { id: "earlier", image, addedAt: 1 },
+      ]),
+      asGiven,
+    );
+    expect(store.added$.value).toBeUndefined();
+    await flushPromises();
+    expect(store.added$.value?.map(({ id }) => id)).toEqual([
+      "earlier",
+      "later",
+    ]);
+  });
+
+  it("keeps an added image and offers it after the others", async () => {
+    const storage = memoryStorage();
+    const store = new AddedBackgrounds(storage, asGiven);
+    await flushPromises();
+    const id = await store.add(new Blob(["x"], { type: "image/png" }));
+    expect(store.added$.value?.map((a) => a.id)).toEqual([id]);
+    expect((await storage.list()).map((k) => k.id)).toEqual([id]);
+  });
+
+  it("keeps the prepared image, not the file", async () => {
+    const storage = memoryStorage();
+    const prepared = new Blob(["y"], { type: "image/webp" });
+    const store = new AddedBackgrounds(storage, async () =>
+      Promise.resolve(prepared),
+    );
+    await store.add(new Blob(["x"], { type: "image/png" }));
+    expect((await storage.list())[0].image).toBe(prepared);
+  });
+
+  it("keeps nothing of a file it refuses", async () => {
+    const storage = memoryStorage();
+    const store = new AddedBackgrounds(storage, async () =>
+      Promise.reject(new UnusableImage("animated")),
+    );
+    await flushPromises();
+    await expect(store.add(new Blob(["x"]))).rejects.toThrow(UnusableImage);
+    expect(await storage.list()).toEqual([]);
+    expect(store.added$.value).toEqual([]);
+  });
+
+  it("keeps no more than the grid holds", async () => {
+    const storage = memoryStorage();
+    const store = new AddedBackgrounds(storage, asGiven);
+    for (let i = 0; i < maxAddedBackgrounds; i++)
+      await store.add(new Blob([`${i}`]));
+    await expect(store.add(new Blob(["more"]))).rejects.toThrow(RangeError);
+    expect(await storage.list()).toHaveLength(maxAddedBackgrounds);
+  });
+
+  it("forgets a removed image, and lets its picture go", async () => {
+    const revoke = vi
+      .spyOn(URL, "revokeObjectURL")
+      .mockImplementation(() => {});
+    const storage = memoryStorage();
+    const store = new AddedBackgrounds(storage, asGiven);
+    await flushPromises();
+    const first = await store.add(new Blob(["a"]));
+    const second = await store.add(new Blob(["b"]));
+    const url = store.added$.value![0].url;
+
+    await store.remove(first);
+    expect(store.added$.value?.map((a) => a.id)).toEqual([second]);
+    expect((await storage.list()).map((k) => k.id)).toEqual([second]);
+    expect(revoke).toHaveBeenCalledWith(url);
+  });
+
+  it("offers nothing where the browser keeps nothing", async () => {
+    const store = new AddedBackgrounds(null);
+    await flushPromises();
+    expect(store.added$.value).toEqual([]);
+    await expect(store.add(new Blob(["x"]))).rejects.toThrow();
+  });
+
+  it("offers none, rather than waiting, where the device can't be read", async () => {
+    const unreadable: BackgroundImageStorage = {
+      ...memoryStorage(),
+      list: async () => Promise.reject(new Error("storage cleared")),
+    };
+    const store = new AddedBackgrounds(unreadable);
+    await flushPromises();
+    expect(store.added$.value).toEqual([]);
+  });
+});
+
+describe("prepareImage", () => {
+  // Refused before anything is decoded, which only a real browser could do.
+  it("refuses a file that isn't an image", async () => {
+    await expect(
+      prepareImage(new Blob(["x"], { type: "text/plain" })),
+    ).rejects.toEqual(new UnusableImage("not-an-image"));
+  });
+
+  it("refuses an animated type where the browser can't count frames", async () => {
+    expect(globalThis.ImageDecoder).toBeUndefined();
+    await expect(
+      prepareImage(new Blob(["GIF89a"], { type: "image/gif" })),
+    ).rejects.toEqual(new UnusableImage("animated"));
+  });
+});
+
+describe("IndexedDBImageStorage", () => {
+  it("keeps images across sessions until they are deleted", async () => {
+    const indexedDB = new IDBFactory();
+    const image = new Blob(["x"], { type: "image/webp" });
+    const first = new IndexedDBImageStorage(indexedDB);
+    await first.put({ id: "a", image, addedAt: 1 });
+    await first.put({ id: "b", image, addedAt: 2 });
+
+    // A session of its own, as after a reload.
+    const second = new IndexedDBImageStorage(indexedDB);
+    expect(
+      (await second.list()).map(({ id, addedAt }) => [id, addedAt]),
+    ).toEqual([
+      ["a", 1],
+      ["b", 2],
+    ]);
+    await second.delete("a");
+    expect((await first.list()).map(({ id }) => id)).toEqual(["b"]);
+  });
+});
+
+// Decoding needs a real browser; the end-to-end checks cover it.
+const asGiven = async (file: Blob): Promise<Blob> => Promise.resolve(file);
+
+function memoryStorage(kept: KeptImage[] = []): BackgroundImageStorage {
+  return {
+    list: async (): Promise<KeptImage[]> => Promise.resolve([...kept]),
+    put: async (image): Promise<void> => {
+      kept.push(image);
+      return Promise.resolve();
+    },
+    delete: async (id): Promise<void> => {
+      const index = kept.findIndex((k) => k.id === id);
+      if (index !== -1) kept.splice(index, 1);
+      return Promise.resolve();
+    },
+  };
+}

src/livekit/backgroundImages.ts

@@ -0,0 +1,220 @@
+/*
+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 { BehaviorSubject } from "rxjs";
+import { logger } from "matrix-js-sdk/lib/logger";
+
+import { type Behavior } from "../state/Behavior";
+
+export const maxAddedBackgrounds = 5;
+
+/** The longest edge kept; the pipeline scales every image to the camera. */
+export const maxStoredEdge = 1920;
+
+/** Why a file can't be used as a background. */
+export type UnusableReason = "not-an-image" | "animated" | "undecodable";
+
+export class UnusableImage extends Error {
+  public constructor(public readonly reason: UnusableReason) {
+    super(reason);
+    this.name = "UnusableImage";
+  }
+}
+
+/** A background the user added, as the menu and the pipeline use it. */
+export interface AddedBackground {
+  id: string;
+  url: string;
+}
+
+/** A background the user added, as it is kept on the device. */
+export interface KeptImage {
+  id: string;
+  image: Blob;
+  addedAt: number;
+}
+
+/** Where added backgrounds are kept. */
+export interface BackgroundImageStorage {
+  list(): Promise<KeptImage[]>;
+  put(image: KeptImage): Promise<void>;
+  delete(id: string): Promise<void>;
+}
+
+/** The backgrounds this device keeps, which never leave it. */
+export class AddedBackgrounds {
+  private readonly subject$ = new BehaviorSubject<
+    AddedBackground[] | undefined
+  >(undefined);
+  /** Undefined until what the device keeps has been read. */
+  public readonly added$: Behavior<AddedBackground[] | undefined> =
+    this.subject$;
+
+  public constructor(
+    private readonly storage: BackgroundImageStorage | null,
+    private readonly prepare: (file: Blob) => Promise<Blob> = prepareImage,
+  ) {
+    this.read().catch((e) => {
+      logger.warn("Could not read added backgrounds", e);
+      this.subject$.next([]);
+    });
+  }
+
+  private async read(): Promise<void> {
+    const kept = (await this.storage?.list()) ?? [];
+    kept.sort((a, b) => a.addedAt - b.addedAt);
+    this.subject$.next(
+      kept.map(({ id, image }) => ({ id, url: URL.createObjectURL(image) })),
+    );
+  }
+
+  /**
+   * Keeps a file as a background, and answers with its id. Throws
+   * {@link UnusableImage} for a file that can't be used, and a RangeError
+   * once maxAddedBackgrounds are kept.
+   */
+  public async add(file: Blob): Promise<string> {
+    if (this.storage === null)
+      throw new Error("This browser keeps no backgrounds");
+    const image = await this.prepare(file);
+    if ((await this.storage.list()).length >= maxAddedBackgrounds)
+      throw new RangeError(
+        `${maxAddedBackgrounds} backgrounds are kept already`,
+      );
+    const kept: KeptImage = {
+      id: crypto.randomUUID(),
+      image,
+      addedAt: Date.now(),
+    };
+    await this.storage.put(kept);
+    this.subject$.next([
+      ...(this.subject$.value ?? []),
+      { id: kept.id, url: URL.createObjectURL(image) },
+    ]);
+    return kept.id;
+  }
+
+  public async remove(id: string): Promise<void> {
+    await this.storage?.delete(id);
+    const current = this.subject$.value ?? [];
+    const gone = current.find((a) => a.id === id);
+    if (gone) URL.revokeObjectURL(gone.url);
+    this.subject$.next(current.filter((a) => a.id !== id));
+  }
+}
+
+/**
+ * Refuses what can't be used, reduces what is larger than is kept, and lays
+ * every image on an opaque ground: a background has to cover what is behind
+ * it, so a transparent pixel would be a hole in it.
+ */
+export async function prepareImage(file: Blob): Promise<Blob> {
+  if (!file.type.startsWith("image/")) throw new UnusableImage("not-an-image");
+  if (await isAnimated(file)) throw new UnusableImage("animated");
+
+  let bitmap: ImageBitmap;
+  try {
+    bitmap = await createImageBitmap(file);
+  } catch (e) {
+    logger.debug("Could not decode the chosen file", e);
+    throw new UnusableImage("undecodable");
+  }
+  try {
+    const scale = Math.min(
+      1,
+      maxStoredEdge / Math.max(bitmap.width, bitmap.height),
+    );
+    const canvas = new OffscreenCanvas(
+      Math.round(bitmap.width * scale),
+      Math.round(bitmap.height * scale),
+    );
+    const context = canvas.getContext("2d");
+    if (!context) throw new UnusableImage("undecodable");
+    context.fillStyle = "black";
+    context.fillRect(0, 0, canvas.width, canvas.height);
+    context.drawImage(bitmap, 0, 0, canvas.width, canvas.height);
+    return await canvas.convertToBlob({ type: "image/webp", quality: 0.9 });
+  } finally {
+    bitmap.close();
+  }
+}
+
+// Read from the file, not its type: a still and an animated WebP share one.
+async function isAnimated(file: Blob): Promise<boolean> {
+  if (typeof ImageDecoder === "undefined") return /gif|apng/.test(file.type);
+  try {
+    const decoder = new ImageDecoder({
+      data: await file.arrayBuffer(),
+      type: file.type,
+    });
+    // Some browsers have no selected track until the tracks are ready.
+    await decoder.tracks.ready;
+    await decoder.completed;
+    return (decoder.tracks.selectedTrack?.frameCount ?? 1) > 1;
+  } catch (e) {
+    logger.debug("Could not read the frame count, judging by type", e);
+    return /gif|apng/.test(file.type);
+  }
+}
+
+const DB_NAME = "element-call-background-images";
+const STORE = "backgrounds";
+
+export class IndexedDBImageStorage implements BackgroundImageStorage {
+  private db?: Promise<IDBDatabase>;
+
+  public constructor(private readonly indexedDB: IDBFactory) {}
+
+  private async open(): Promise<IDBDatabase> {
+    return (this.db ??= new Promise((resolve, reject) => {
+      const request = this.indexedDB.open(DB_NAME, 1);
+      request.onupgradeneeded = (): void => {
+        request.result.createObjectStore(STORE, { keyPath: "id" });
+      };
+      request.onsuccess = (): void => resolve(request.result);
+      request.onerror = (): void => reject(request.error);
+    }));
+  }
+
+  private async run<T>(
+    mode: IDBTransactionMode,
+    body: (store: IDBObjectStore) => IDBRequest<T>,
+  ): Promise<T> {
+    const db = await this.open();
+    return new Promise((resolve, reject) => {
+      const request = body(db.transaction(STORE, mode).objectStore(STORE));
+      request.onsuccess = (): void => resolve(request.result);
+      request.onerror = (): void => reject(request.error);
+    });
+  }
+
+  public async list(): Promise<KeptImage[]> {
+    return this.run<KeptImage[]>("readonly", (s) => s.getAll());
+  }
+
+  public async put(image: KeptImage): Promise<void> {
+    await this.run("readwrite", (s) => s.put(image));
+  }
+
+  public async delete(id: string): Promise<void> {
+    await this.run("readwrite", (s) => s.delete(id));
+  }
+}
+
+function openStorage(): BackgroundImageStorage | null {
+  // Merely reading indexedDB throws where it is disabled.
+  try {
+    return globalThis.indexedDB
+      ? new IndexedDBImageStorage(globalThis.indexedDB)
+      : null;
+  } catch (e) {
+    logger.warn("Could not reach IndexedDB", e);
+    return null;
+  }
+}
+
+export const addedBackgrounds = new AddedBackgrounds(openStorage());

src/livekit/cameraTrack.ts

@@ -0,0 +1,28 @@
+/*
+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 { BehaviorSubject } from "rxjs";
+import { type LocalVideoTrack } from "livekit-client";
+
+import { type Behavior } from "../state/Behavior";
+
+/**
+ * The camera track a background pipeline is synced to: the preview's before
+ * joining, the call's after, none while the camera is off.
+ */
+export class SyncedCameraTrack {
+  private readonly subject$ = new BehaviorSubject<LocalVideoTrack | null>(null);
+  public readonly track$: Behavior<LocalVideoTrack | null> = this.subject$;
+
+  public report(track: LocalVideoTrack): () => void {
+    this.subject$.next(track);
+    // Only if still this one, so a lobby leaving doesn't blank a call starting.
+    return (): void => {
+      if (this.subject$.value === track) this.subject$.next(null);
+    };
+  }
+}

src/reactions/index.ts

@@ -29,6 +29,8 @@ import waveSoundOgg from "../sound/reactions/wave.ogg?url";
 import waveSoundMp3 from "../sound/reactions/wave.mp3?url";
 import baduntssSoundOgg from "../sound/reactions/baduntss.ogg?url";
 import baduntssSoundMp3 from "../sound/reactions/baduntss.mp3?url";
+import bellSoundOgg from "../sound/reactions/bell.ogg?url";
+import bellSoundMp3 from "../sound/reactions/bell.mp3?url";
 
 export const ElementCallReactionEventType = "io.element.call.reaction";
 
@@ -202,6 +204,15 @@ export const ReactionSet: ReactionOption[] = [
       mp3: baduntssSoundMp3,
     },
   },
+  {
+    emoji: "🛎️",
+    name: "bell",
+    alias: ["ding"],
+    sound: {
+      ogg: bellSoundOgg,
+      mp3: bellSoundMp3,
+    },
+  },
 ];
 
 export interface RaisedHandInfo {

src/room/CallView.test.tsx

@@ -50,6 +50,7 @@ import {
   mockMediaDevices,
   mockRtcMembership,
   MockRTCSession,
+  testScope,
 } from "../utils/test";
 import { CallView } from "./CallView";
 import { GroupCallErrorBoundary } from "./GroupCallErrorBoundary";
@@ -61,7 +62,10 @@ import {
 } from "../HostBridge";
 import { type JoinCallData } from "../widget";
 import { MatrixRTCTransportMissingError } from "../utils/errors";
-import { ProcessorProvider } from "../livekit/TrackProcessorContext";
+import {
+  BackgroundEffectsProvider,
+  createAppBackgroundEffects,
+} from "../livekit/BackgroundEffectsContext";
 import { MediaDevicesContext } from "../MediaDevicesContext";
 import { constant } from "../state/Behavior";
 
@@ -193,7 +197,9 @@ function createCallView(
       <HostBridgeProvider value={hostBridge}>
         <TooltipProvider>
           <MediaDevicesContext value={mockMediaDevices({})}>
-            <ProcessorProvider>
+            <BackgroundEffectsProvider
+              effects={createAppBackgroundEffects(testScope())}
+            >
               {options.withErrorBoundary ? (
                 <GroupCallErrorBoundary recoveryActionHandler={vi.fn()}>
                   {callView}
@@ -201,7 +207,7 @@ function createCallView(
               ) : (
                 callView
               )}
-            </ProcessorProvider>
+            </BackgroundEffectsProvider>
           </MediaDevicesContext>
         </TooltipProvider>
       </HostBridgeProvider>

src/room/InCallView.test.tsx

@@ -31,6 +31,7 @@ import {
   mockRemoteParticipant,
   mockRtcMembership,
   type MockRTCSession,
+  testScope,
 } from "../utils/test";
 import { E2eeType } from "../e2ee/e2eeType";
 import {
@@ -49,7 +50,10 @@ import { MediaDevicesContext } from "../MediaDevicesContext";
 import { type MediaDevices as ECMediaDevices } from "../state/MediaDevices";
 import { AppBar } from "../AppBar";
 import { type MatrixInfo } from "./VideoPreview";
-import { ProcessorProvider } from "../livekit/TrackProcessorContext";
+import {
+  BackgroundEffectsProvider,
+  createAppBackgroundEffects,
+} from "../livekit/BackgroundEffectsContext";
 import { initializeWidget } from "../widget";
 import { RootElementProvider } from "../RootElementContext";
 
@@ -242,7 +246,9 @@ describe("ActiveCall", () => {
     const { findByTestId } = render(
       <BrowserRouter>
         <MediaDevicesContext value={mediaDevices}>
-          <ProcessorProvider>
+          <BackgroundEffectsProvider
+            effects={createAppBackgroundEffects(testScope())}
+          >
             <TooltipProvider>
               <RoomContext value={mockLivekitRoom({ localParticipant })}>
                 <ActiveCall
@@ -257,7 +263,7 @@ describe("ActiveCall", () => {
                 />
               </RoomContext>
             </TooltipProvider>
-          </ProcessorProvider>
+          </BackgroundEffectsProvider>
         </MediaDevicesContext>
       </BrowserRouter>,
     );
@@ -292,7 +298,9 @@ describe("ActiveCall", () => {
         <BrowserRouter>
           <RootElementProvider value={root}>
             <MediaDevicesContext value={mediaDevices}>
-              <ProcessorProvider>
+              <BackgroundEffectsProvider
+                effects={createAppBackgroundEffects(testScope())}
+              >
                 <TooltipProvider>
                   <RoomContext value={mockLivekitRoom({ localParticipant })}>
                     <ActiveCall
@@ -307,7 +315,7 @@ describe("ActiveCall", () => {
                     />
                   </RoomContext>
                 </TooltipProvider>
-              </ProcessorProvider>
+              </BackgroundEffectsProvider>
             </MediaDevicesContext>
           </RootElementProvider>
         </BrowserRouter>,

src/room/InCallView.tsx

@@ -20,8 +20,6 @@ import {
 import useMeasure from "react-use-measure";
 import { type MatrixRTCSession } from "matrix-js-sdk/lib/matrixrtc";
 import classNames from "classnames";
-import { map } from "rxjs";
-import { useObservable } from "observable-hooks";
 import { logger as rootLogger } from "matrix-js-sdk/lib/logger";
 import { useTranslation } from "react-i18next";
 
@@ -77,10 +75,11 @@ import {
   useAppBarSubtitle,
 } from "../AppBar.tsx";
 import { useBehavior } from "../useBehavior.ts";
+import { useValueBehavior } from "../useValueBehavior.ts";
 import { constant } from "../state/Behavior.ts";
 import { Toast } from "../Toast.tsx";
 import overlayStyles from "../Overlay.module.css";
-import { useTrackProcessorObservable$ } from "../livekit/TrackProcessorContext.tsx";
+import { useBackgroundEffectsState$ } from "../livekit/BackgroundEffectsContext.tsx";
 import { type Layout } from "../state/layout-types.ts";
 import { ObservableScope } from "../state/ObservableScope.ts";
 import { CallFooter, type FooterSnapshot } from "../components/CallFooter.tsx";
@@ -121,7 +120,7 @@ export const ActiveCall: FC<ActiveCallProps> = (props) => {
   const urlParams = useUrlParams();
   const hostBridge = useHostBridge();
   const mediaDevices = useMediaDevices();
-  const trackProcessorState$ = useTrackProcessorObservable$();
+  const backgroundEffectsState$ = useBackgroundEffectsState$();
   // The element we have to draw the call in: the page, or the container a host
   // gave us. Its size, not the window's, decides how the call is laid out.
   const rootElement = useRootElement();
@@ -151,7 +150,7 @@ export const ActiveCall: FC<ActiveCallProps> = (props) => {
       },
       reactionsReader.raisedHands$,
       reactionsReader.reactions$,
-      scope.behavior(trackProcessorState$),
+      backgroundEffectsState$,
     );
     // TODO move this somewhere else once we use the callViewModel in the lobby as well!
     vm.join();
@@ -171,7 +170,7 @@ export const ActiveCall: FC<ActiveCallProps> = (props) => {
     urlParams,
     hostBridge,
     mediaDevices,
-    trackProcessorState$,
+    backgroundEffectsState$,
     props.client,
     rootElement,
   ]);
@@ -185,6 +184,7 @@ export const ActiveCall: FC<ActiveCallProps> = (props) => {
       vm,
       props.muteStates,
       mediaDevices,
+      backgroundEffectsState$,
       `${props.client.getUserId()}:${props.client.getDeviceId()}`,
       { showControls: urlParams.showControls, header: urlParams.header },
     );
@@ -202,7 +202,7 @@ export const ActiveCall: FC<ActiveCallProps> = (props) => {
     props.onLeft,
     urlParams,
     mediaDevices,
-    trackProcessorState$,
+    backgroundEffectsState$,
     props.client,
     vm,
   ]);
@@ -252,7 +252,7 @@ export const InCallView: FC<InCallViewProps> = ({
 
   useWakeLock();
   // TODO-MULTI-SFU This is unused now??
-  // const connectionState = useObservableEagerState(vm.livekitConnectionState$);
+  // const connectionState = useBehavior(vm.livekitConnectionState$);
 
   // annoyingly we don't get the disconnection reason this way,
   // only by listening for the emitted event
@@ -374,10 +374,7 @@ export const InCallView: FC<InCallViewProps> = ({
       edgeToEdge,
     ],
   );
-  const gridBoundsObservable$ = useObservable(
-    (inputs$) => inputs$.pipe(map(([gridBounds]) => gridBounds)),
-    [gridBounds],
-  );
+  const gridBounds$ = useValueBehavior(gridBounds);
 
   useAppBarHidden(!showHeader);
   useAppBarSubtitle(
@@ -538,7 +535,7 @@ export const InCallView: FC<InCallViewProps> = ({
   );
 
   const layouts = useMemo(() => {
-    const inputs = { minBounds$: gridBoundsObservable$ };
+    const inputs = { minBounds$: gridBounds$ };
     return {
       grid: makeGridLayout(inputs),
       "spotlight-landscape": makeSpotlightLandscapeLayout(inputs),
@@ -547,7 +544,7 @@ export const InCallView: FC<InCallViewProps> = ({
       "one-on-one-desktop": makeOneOnOneDesktopLayout(inputs),
       "one-on-one-mobile": makeOneOnOneMobileLayout(inputs),
     };
-  }, [gridBoundsObservable$]);
+  }, [gridBounds$]);
 
   const showFooter = useBehavior(footerVm.showFooter$);
   const renderContent = (): JSX.Element => {

src/room/KnockLobbyView.test.tsx

@@ -10,24 +10,33 @@ import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { TooltipProvider } from "@vector-im/compound-web";
 import { type MatrixClient, type RoomSummary } from "matrix-js-sdk";
+import { type Observable } from "rxjs";
 
 import { KnockLobbyView } from "./KnockLobbyView";
 import { LeaveToHomeProvider } from "../LeaveToHomeContext";
 import { MediaDevicesContext } from "../MediaDevicesContext";
-import { type ProcessorState } from "../livekit/TrackProcessorContext";
+import { type BackgroundEffectsState } from "../livekit/BackgroundEffectsContext";
 import { mockMediaDevices } from "../utils/test";
 
 vi.mock("@livekit/components-react", () => ({
   usePreviewTracks: (): unknown[] => [],
 }));
 
-vi.mock("../livekit/TrackProcessorContext", () => ({
-  useTrackProcessor: (): ProcessorState => ({
+vi.mock("../livekit/BackgroundEffectsContext", async () => {
+  const { of } = await import("rxjs");
+  const none: BackgroundEffectsState = {
     supported: false,
     processor: undefined,
-  }),
-  useTrackProcessorSync: (): void => {},
-}));
+  };
+  // One observable, as the real hook keeps: a fresh one each render would
+  // rebuild the footer on every render.
+  const none$ = of(none);
+  return {
+    useBackgroundEffects: (): BackgroundEffectsState => none,
+    useBackgroundEffectsState$: (): Observable<BackgroundEffectsState> => none$,
+    useSyncBackgroundEffects: (): void => {},
+  };
+});
 
 vi.mock("react-use-measure", () => ({
   default: (): [() => void, object] => [(): void => {}, {}],

src/room/LobbyView.test.tsx

@@ -5,8 +5,10 @@ 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 { render } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { type Observable, of } from "rxjs";
 import { LeaveToHomeProvider } from "../LeaveToHomeContext";
 import { TooltipProvider } from "@vector-im/compound-web";
 import { type MatrixClient } from "matrix-js-sdk";
@@ -18,9 +20,15 @@ import {
 
 import { LobbyView } from "./LobbyView";
 import { E2eeType } from "../e2ee/e2eeType";
-import { mockMediaDevices, mockMuteStates } from "../utils/test";
+import {
+  mockMediaDevices,
+  mockMuteStates,
+  restoreAudioCapture,
+  stubAudioCapture,
+} from "../utils/test";
+import { type MediaDevices } from "../state/MediaDevices";
 import { MediaDevicesContext } from "../MediaDevicesContext";
-import { type ProcessorState } from "../livekit/TrackProcessorContext";
+import { type BackgroundEffectsState } from "../livekit/BackgroundEffectsContext";
 import { type EncryptionSystem } from "../e2ee/sharedKeyManagement";
 import lobbyStyles from "./LobbyView.module.css";
 import headerStyles from "../Header.module.css";
@@ -33,13 +41,21 @@ vi.mock("@livekit/components-react", () => ({
   usePreviewTracks: (): unknown[] => [],
 }));
 
-vi.mock("../livekit/TrackProcessorContext", () => ({
-  useTrackProcessor: (): ProcessorState => ({
+vi.mock("../livekit/BackgroundEffectsContext", async () => {
+  const { of } = await import("rxjs");
+  const none: BackgroundEffectsState = {
     supported: false,
     processor: undefined,
-  }),
-  useTrackProcessorSync: (): void => {},
-}));
+  };
+  // One observable, as the real hook keeps: a fresh one each render would
+  // rebuild the footer on every render.
+  const none$ = of(none);
+  return {
+    useBackgroundEffects: (): BackgroundEffectsState => none,
+    useBackgroundEffectsState$: (): Observable<BackgroundEffectsState> => none$,
+    useSyncBackgroundEffects: (): void => {},
+  };
+});
 
 vi.mock("react-use-measure", () => ({
   default: (): [() => void, object] => [(): void => {}, {}],
@@ -77,9 +93,10 @@ function renderLobbyView(
   props: Partial<Parameters<typeof LobbyView>[0]> = {},
   withAppBar = false,
   platform = "android",
+  devices: Partial<MediaDevices> = {},
 ): ReturnType<typeof render> {
   platformMock.mockReturnValue(platform);
-  const mediaDevices = mockMediaDevices({});
+  const mediaDevices = mockMediaDevices(devices);
   const muteStates = mockMuteStates();
   const hideHeader = withAppBar ? true : false;
   const lobbyView = (
@@ -178,3 +195,30 @@ describe("LobbyView", () => {
     expect(await axe(container)).toHaveNoViolations();
   });
 });
+
+describe("LobbyView microphone level", () => {
+  afterEach(restoreAudioCapture);
+
+  it("shows the microphone level meter", async () => {
+    const capture = stubAudioCapture();
+    capture.grant();
+    const user = userEvent.setup();
+    const { getByRole } = renderLobbyView({}, false, "desktop", {
+      requestDeviceNames: (): void => {},
+      audioInput: {
+        available$: of(
+          new Map([["mic1", { type: "name", name: "Microphone 1" }]]),
+        ),
+        selected$: of({ id: "mic1" }),
+        select: (): void => {},
+      },
+    } as unknown as Partial<MediaDevices>);
+
+    // Pre-join reaches the meter through the same chevron as a call.
+    await user.click(getByRole("button", { name: "Microphone" }));
+
+    expect(
+      await screen.findByRole("meter", { name: "Microphone level" }),
+    ).toBeInTheDocument();
+  });
+});

src/room/LobbyView.tsx

@@ -9,6 +9,7 @@ import {
   type FC,
   useCallback,
   useMemo,
+  useRef,
   useState,
   type JSX,
   useEffect,
@@ -24,7 +25,6 @@ import {
   type LocalVideoTrack,
   Track,
 } from "livekit-client";
-import { useObservableEagerState } from "observable-hooks";
 
 import inCallStyles from "./InCallView.module.css";
 import styles from "./LobbyView.module.css";
@@ -41,9 +41,10 @@ import { useMediaDevices } from "../MediaDevicesContext";
 import { ObservableScope } from "../state/ObservableScope";
 import { useInitial } from "../useInitial";
 import {
-  useTrackProcessor,
-  useTrackProcessorSync,
-} from "../livekit/TrackProcessorContext";
+  useBackgroundEffects,
+  useBackgroundEffectsState$,
+  useSyncBackgroundEffects,
+} from "../livekit/BackgroundEffectsContext";
 import { getValue } from "../utils/observable";
 import { useBehavior } from "../useBehavior";
 import { CallFooter, type FooterSnapshot } from "../components/CallFooter";
@@ -125,9 +126,7 @@ export const LobbyView: FC<Props> = ({
   );
 
   const devices = useMediaDevices();
-  const videoInputId = useObservableEagerState(
-    devices.videoInput.selected$,
-  )?.id;
+  const videoInputId = useBehavior(devices.videoInput.selected$)?.id;
 
   // Capture the audio options as they were when we first mounted, because
   // we're not doing anything with the audio anyway so we don't need to
@@ -139,9 +138,15 @@ export const LobbyView: FC<Props> = ({
       },
   );
 
-  const { processor } = useTrackProcessor();
+  const { processor, preparing } = useBackgroundEffects();
+  const backgroundEffectsState$ = useBackgroundEffectsState$();
 
-  const initialProcessor = useInitial(() => processor);
+  // Taken once it is known whether the pipeline builds, and then kept, as
+  // useInitial keeps a value: one attached later is synced below.
+  const initialProcessorRef = useRef<{ value: typeof processor }>(undefined);
+  if (!preparing) initialProcessorRef.current ??= { value: processor };
+  const initialProcessor = initialProcessorRef.current?.value;
+  const processorTaken = initialProcessorRef.current !== undefined;
   const localTrackOptions = useMemo<CreateLocalTracksOptions>(
     () => ({
       // The only reason we request audio here is to get the audio permission
@@ -151,12 +156,20 @@ export const LobbyView: FC<Props> = ({
       // We also pass in a clone because livekit mutates the object passed in,
       // which would cause the devices to be re-opened on the next render.
       audio: Object.assign({}, initialAudioOptions),
-      video: videoEnabled && {
-        deviceId: videoInputId,
-        processor: initialProcessor,
-      },
+      // Not opened before then, so that the preview never shows the room.
+      video: videoEnabled &&
+        processorTaken && {
+          deviceId: videoInputId,
+          processor: initialProcessor,
+        },
     }),
-    [initialAudioOptions, videoEnabled, videoInputId, initialProcessor],
+    [
+      initialAudioOptions,
+      videoEnabled,
+      processorTaken,
+      videoInputId,
+      initialProcessor,
+    ],
   );
 
   const onError = useCallback(
@@ -186,7 +199,7 @@ export const LobbyView: FC<Props> = ({
     }
   }, [devices, videoInputId, videoTrack]);
 
-  useTrackProcessorSync(videoTrack);
+  useSyncBackgroundEffects(videoTrack);
 
   const [footerVm, setFooterVm] = useState<ViewModel<FooterSnapshot> | null>(
     null,
@@ -198,6 +211,7 @@ export const LobbyView: FC<Props> = ({
         footerScope,
         muteStates,
         devices,
+        backgroundEffectsState$,
         openSettings,
         hangup,
         // Logo and header are connected: only show the logo in SPA with header.
@@ -207,7 +221,14 @@ export const LobbyView: FC<Props> = ({
     return (): void => {
       footerScope.end();
     };
-  }, [devices, hangup, hideHeader, muteStates, openSettings]);
+  }, [
+    devices,
+    backgroundEffectsState$,
+    hangup,
+    hideHeader,
+    muteStates,
+    openSettings,
+  ]);
 
   // TODO: Unify this component with InCallView, so we can get slick joining
   // animations and don't have to feel bad about reusing its CSS

src/room/VideoPreview.tsx

@@ -5,9 +5,9 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE in the repository root for full details.
 */
 
-import { useEffect, useMemo, useRef, type FC, type ReactNode } from "react";
+import { useMemo, type FC, type ReactNode } from "react";
 import useMeasure from "react-use-measure";
-import { facingModeFromLocalTrack, type LocalVideoTrack } from "livekit-client";
+import { type LocalVideoTrack } from "livekit-client";
 import classNames from "classnames";
 import { useTranslation } from "react-i18next";
 
@@ -15,6 +15,7 @@ import { TileAvatar } from "../tile/TileAvatar";
 import styles from "./VideoPreview.module.css";
 import { type EncryptionSystem } from "../e2ee/sharedKeyManagement";
 import videoPlaceholder from "../graphics/video-placeholder.gif";
+import { useAttachedTrack } from "../useAttachedTrack";
 
 export type MatrixInfo = {
   userId: string;
@@ -43,17 +44,7 @@ export const VideoPreview: FC<Props> = ({
   const { t } = useTranslation();
   const [previewRef, previewBounds] = useMeasure();
 
-  const videoEl = useRef<HTMLVideoElement | null>(null);
-
-  useEffect(() => {
-    // Effect to connect the videoTrack with the video element.
-    if (videoEl.current) {
-      videoTrack?.attach(videoEl.current);
-    }
-    return (): void => {
-      videoTrack?.detach();
-    };
-  }, [videoTrack]);
+  const { videoRef, mirrored } = useAttachedTrack(videoTrack);
 
   const cameraIsStarting = useMemo(
     () => videoEnabled && !videoTrack,
@@ -63,13 +54,8 @@ export const VideoPreview: FC<Props> = ({
   return (
     <div className={classNames(styles.preview)} ref={previewRef}>
       <video
-        className={
-          videoTrack &&
-          facingModeFromLocalTrack(videoTrack).facingMode === "user"
-            ? styles.mirror
-            : undefined
-        }
-        ref={videoEl}
+        className={mirrored ? styles.mirror : undefined}
+        ref={videoRef}
         muted
         playsInline
         // There's no reason for this to be focusable