acutally use fallback url

callParticipation -> rtcParticipationManager
driverCapabilites -> MatrixClientFeatures

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

@@ -14,17 +14,13 @@ on:
         description: The build mode for vite. Must be either 'development' or 'production'
         required: false
         default: production
-    secrets:
-      SENTRY_ORG:
-        required: true
-      SENTRY_PROJECT:
-        required: true
-      SENTRY_URL:
-        required: true
-      SENTRY_AUTH_TOKEN:
-        required: true
-      CODECOV_TOKEN:
-        required: false
+    # No `secrets:` block: every caller passes `secrets: inherit`, so the
+    # repository's secrets reach this workflow without each one being declared
+    # here and threaded through by name at the call sites -- the same pattern
+    # build-and-publish-docker.yaml uses. A secret this workflow starts using
+    # then needs no change to the callers. The ones read below are
+    # MATRIX_RTC_NPM_TOKEN, SENTRY_ORG, SENTRY_PROJECT, SENTRY_URL,
+    # SENTRY_AUTH_TOKEN and CODECOV_TOKEN.
 
 jobs:
   build:
@@ -42,6 +38,14 @@ jobs:
         with:
           cache: "pnpm"
           node-version-file: ".node-version"
+      - name: Authenticate to GitHub Packages
+        # The MatrixRTC SDK (@billcarsonfr/matrix-rtc, see .npmrc) is on the GitHub
+        # Packages npm registry, which needs a token with read:packages even for
+        # public packages. A workflow's GITHUB_TOKEN only reaches packages of its own
+        # repository, so this is a personal access token kept as a repository secret.
+        env:
+          NPM_REGISTRY_TOKEN: ${{ secrets.MATRIX_RTC_NPM_TOKEN }}
+        run: echo "//npm.pkg.github.com/:_authToken=${NPM_REGISTRY_TOKEN}" >> ~/.npmrc
       - 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"

.github/workflows/build.yaml

@@ -15,12 +15,7 @@ jobs:
       package: full
       vite_app_version: ${{ github.event.release.tag_name || github.sha }}
       build_mode: ${{ github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'development build') && 'development' || 'production' }}
-    secrets:
-      SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
-      SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}
-      SENTRY_URL: ${{ secrets.SENTRY_URL }}
-      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
-      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+    secrets: inherit
   deploy_develop:
     # Deploy main branch to call.element.dev after build completes
     if: github.ref == 'refs/heads/main'
@@ -65,12 +60,7 @@ jobs:
       package: embedded
       vite_app_version: ${{ github.event.release.tag_name || github.sha }}
       build_mode: ${{ github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'development build') && 'development' || 'production' }}
-    secrets:
-      SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
-      SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}
-      SENTRY_URL: ${{ secrets.SENTRY_URL }}
-      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
-      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+    secrets: inherit
 
   build_sdk_element_call:
     # Use the embedded package vite build
@@ -79,12 +69,7 @@ jobs:
       package: sdk
       vite_app_version: ${{ github.event.release.tag_name || github.sha }}
       build_mode: ${{ github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'development build') && 'development' || 'production' }}
-    secrets:
-      SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
-      SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}
-      SENTRY_URL: ${{ secrets.SENTRY_URL }}
-      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
-      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+    secrets: inherit
 
   build_storybook:
     name: Build Storybook
@@ -102,6 +87,14 @@ jobs:
         with:
           cache: "pnpm"
           node-version-file: ".node-version"
+      - name: Authenticate to GitHub Packages
+        # The MatrixRTC SDK (@billcarsonfr/matrix-rtc, see .npmrc) is on the GitHub
+        # Packages npm registry, which needs a token with read:packages even for
+        # public packages. A workflow's GITHUB_TOKEN only reaches packages of its own
+        # repository, so this is a personal access token kept as a repository secret.
+        env:
+          NPM_REGISTRY_TOKEN: ${{ secrets.MATRIX_RTC_NPM_TOKEN }}
+        run: echo "//npm.pkg.github.com/:_authToken=${NPM_REGISTRY_TOKEN}" >> ~/.npmrc
       - name: Install dependencies
         run: "pnpm install --frozen-lockfile --ignore-pnpmfile"
       - name: Build Storybook

.github/workflows/lint.yaml

@@ -17,6 +17,14 @@ jobs:
         with:
           cache: "pnpm"
           node-version-file: ".node-version"
+      - name: Authenticate to GitHub Packages
+        # The MatrixRTC SDK (@billcarsonfr/matrix-rtc, see .npmrc) is on the GitHub
+        # Packages npm registry, which needs a token with read:packages even for
+        # public packages. A workflow's GITHUB_TOKEN only reaches packages of its own
+        # repository, so this is a personal access token kept as a repository secret.
+        env:
+          NPM_REGISTRY_TOKEN: ${{ secrets.MATRIX_RTC_NPM_TOKEN }}
+        run: echo "//npm.pkg.github.com/:_authToken=${NPM_REGISTRY_TOKEN}" >> ~/.npmrc
       - 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"

.github/workflows/publish-embedded-packages.yaml

@@ -66,11 +66,7 @@ jobs:
     with:
       vite_app_version: embedded-${{ needs.versioning.outputs.PREFIXED_VERSION }}
       package: embedded
-    secrets:
-      SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
-      SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}
-      SENTRY_URL: ${{ secrets.SENTRY_URL }}
-      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+    secrets: inherit
 
   publish_tarball:
     needs: [build_element_call, versioning]

.github/workflows/publish.yaml

@@ -13,11 +13,7 @@ jobs:
     with:
       package: full
       vite_app_version: ${{ github.event.release.tag_name }} # Using ${{ env.VERSION }} here doesn't work
-    secrets:
-      SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
-      SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}
-      SENTRY_URL: ${{ secrets.SENTRY_URL }}
-      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+    secrets: inherit
 
   publish_tarball:
     needs: build_element_call

.github/workflows/test.yaml

@@ -19,6 +19,14 @@ jobs:
         with:
           cache: "pnpm"
           node-version-file: ".node-version"
+      - name: Authenticate to GitHub Packages
+        # The MatrixRTC SDK (@billcarsonfr/matrix-rtc, see .npmrc) is on the GitHub
+        # Packages npm registry, which needs a token with read:packages even for
+        # public packages. A workflow's GITHUB_TOKEN only reaches packages of its own
+        # repository, so this is a personal access token kept as a repository secret.
+        env:
+          NPM_REGISTRY_TOKEN: ${{ secrets.MATRIX_RTC_NPM_TOKEN }}
+        run: echo "//npm.pkg.github.com/:_authToken=${NPM_REGISTRY_TOKEN}" >> ~/.npmrc
       - 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"
@@ -44,9 +52,17 @@ jobs:
           flags: unittests
           fail_ci_if_error: true
   playwright:
-    name: Run end-to-end tests
+    name: Run end-to-end tests (${{ matrix.call_implementation }})
     timeout-minutes: 60
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Both MatrixRTC implementations, until matrix-rtc becomes the
+        # default and matrix-js-sdk goes (oxidation plan §5.15). The
+        # matrix-rtc run does not block until it has passed once.
+        call_implementation: [matrix-js-sdk, matrix-rtc]
+    continue-on-error: ${{ matrix.call_implementation == 'matrix-rtc' }}
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
@@ -57,6 +73,14 @@ jobs:
         with:
           cache: "pnpm"
           node-version-file: ".node-version"
+      - name: Authenticate to GitHub Packages
+        # The MatrixRTC SDK (@billcarsonfr/matrix-rtc, see .npmrc) is on the GitHub
+        # Packages npm registry, which needs a token with read:packages even for
+        # public packages. A workflow's GITHUB_TOKEN only reaches packages of its own
+        # repository, so this is a personal access token kept as a repository secret.
+        env:
+          NPM_REGISTRY_TOKEN: ${{ secrets.MATRIX_RTC_NPM_TOKEN }}
+        run: echo "//npm.pkg.github.com/:_authToken=${NPM_REGISTRY_TOKEN}" >> ~/.npmrc
       - 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
@@ -80,11 +104,12 @@ jobs:
       - name: Run Playwright tests
         env:
           USE_DOCKER: 1
+          CALL_VIEW_MODEL_IMPLEMENTATION: ${{ matrix.call_implementation }}
         run: pnpm exec playwright test
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         if: ${{ !cancelled() }}
         with:
-          name: html-report
+          name: html-report-${{ matrix.call_implementation }}
           path: playwright-report
           if-no-files-found: error
           retention-days: 4

.github/workflows/translations-download.yaml

@@ -25,6 +25,14 @@ jobs:
           cache: "pnpm"
           node-version-file: ".node-version"
 
+      - name: Authenticate to GitHub Packages
+        # The MatrixRTC SDK (@billcarsonfr/matrix-rtc, see .npmrc) is on the GitHub
+        # Packages npm registry, which needs a token with read:packages even for
+        # public packages. A workflow's GITHUB_TOKEN only reaches packages of its own
+        # repository, so this is a personal access token kept as a repository secret.
+        env:
+          NPM_REGISTRY_TOKEN: ${{ secrets.MATRIX_RTC_NPM_TOKEN }}
+        run: echo "//npm.pkg.github.com/:_authToken=${NPM_REGISTRY_TOKEN}" >> ~/.npmrc
       - name: Install Deps
         # ignore-pnpmfile should never be commited. Make CI crash if it happened (`pnpmfileChecksum` is present)
         run: "pnpm install --frozen-lockfile --ignore-pnpmfile"

.gitignore

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

.npmrc

@@ -0,0 +1,9 @@
+# The MatrixRTC SDK (`@element-hq/matrix-rtc`, aliased in package.json to the
+# name the fork's CI publishes it under) comes from the GitHub Packages npm
+# registry, which needs a token with `read:packages` even for public
+# packages. This is a stop-gap while the SDK is in flux; once it is published
+# to npmjs.com this file and the alias go away (docs/matrix_rtc_sdk.md).
+# Only the scope->registry mapping lives here; the token goes in your
+# user-level npm config (~/.npmrc), never in this file. CI writes it there
+# from a repository secret (see .github/workflows).
+@billcarsonfr:registry=https://npm.pkg.github.com

.oxlintrc.json

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

.storybook/preview.tsx

@@ -7,14 +7,17 @@ Please see LICENSE in the repository root for full details.
 
 import type { Preview } from "@storybook/react-vite";
 import { TooltipProvider } from "@vector-im/compound-web";
-import i18n from "i18next";
 import { logger } from "matrix-js-sdk/lib/logger";
 
 import EN from "../locales/en/app.json";
+import { Config } from "../src/config/Config";
 import { initReactI18next } from "react-i18next";
+import { i18n } from "../src/utils/i18n";
 import "../src/index.css";
 
-// Bare-minimum i18n config
+// Bare-minimum i18n config.
+// Unlike the app, stories register the instance as react-i18next's default
+// rather than wrapping every story in an <I18nextProvider>.
 i18n
   .use(initReactI18next)
   .init({
@@ -33,6 +36,10 @@ i18n
   })
   .catch((e) => logger.warn("Failed to init i18n for stories", e));
 
+// Stories run without a config.json; the defaults stand in, as they do for
+// a component host that passes none.
+Config.initWith({});
+
 const preview: Preview = {
   parameters: {
     layout: "centered",

AGENTS.md

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

README.md

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

backend/app-service-othersite.yaml

@@ -0,0 +1,17 @@
+id: "lk-jwt-service-othersite"
+as_token: "ec_dev_as_token_othersite_0123456789ab"
+hs_token: "ec_dev_hs_token_othersite_0123456789ab"
+sender_localpart: "_lk_jwt_service"
+namespaces:
+  users:
+    - exclusive: false
+      regex: "@.*:homeserver-1" # Cover all local users
+# Required for Synapse to call POST /_matrix/app/v1/ping on this service.
+url: "http://auth-server-1:16080"
+# Enable membership look-ups via /is_joined.
+io.element.msc4502.scopes:
+  ["urn:matrix:client:io.element.msc4502:rooms:is_joined"]
+# Route /_matrix/client/(v*|unstable/*)/rtc/livekit/* C-S and S-S requests to this
+# service.
+io.element.msc4512.proxy_prefix: "rtc/livekit"
+io.element.msc4512.proxy_url: "http://auth-server-1:16080"

backend/app-service.yaml

@@ -0,0 +1,17 @@
+id: "lk-jwt-service"
+as_token: "ec_dev_as_token_main_0123456789ab"
+hs_token: "ec_dev_hs_token_main_0123456789ab"
+sender_localpart: "_lk_jwt_service"
+namespaces:
+  users:
+    - exclusive: false
+      regex: "@.*:homeserver" # Cover all local users
+# Required for Synapse to call POST /_matrix/app/v1/ping on this service.
+url: "http://auth-server:6080"
+# Enable membership look-ups via /is_joined.
+io.element.msc4502.scopes:
+  ["urn:matrix:client:io.element.msc4502:rooms:is_joined"]
+# Route /_matrix/client/(v*|unstable/*)/rtc/livekit/* C-S and S-S requests to this
+# service.
+io.element.msc4512.proxy_prefix: "rtc/livekit"
+io.element.msc4512.proxy_url: "http://auth-server:6080"

backend/dev_homeserver-othersite.yaml

@@ -42,6 +42,13 @@ experimental_features:
   msc4354_enabled: true
   # MatrixRTC
   msc4143_enabled: true
+  # Enable membership look-up via /is_joined.
+  msc4502_enabled: true
+  # Enable C-S & S-S request proxying for application services.
+  msc4512_enabled: true
+
+app_service_config_files:
+  - /data/cfg/app-service.yaml
 
 # The maximum allowed duration by which sent events can be delayed, as
 # per MSC4140. Must be a positive value if set.  Defaults to no

backend/dev_homeserver.yaml

@@ -42,6 +42,13 @@ experimental_features:
   msc4354_enabled: true
   # MatrixRTC
   msc4143_enabled: true
+  # Enable membership look-up via /is_joined.
+  msc4502_enabled: true
+  # Enable C-S & S-S request proxying for application services.
+  msc4512_enabled: true
+
+app_service_config_files:
+  - /data/cfg/app-service.yaml
 
 # The maximum allowed duration by which sent events can be delayed, as
 # per MSC4140. Must be a positive value if set.  Defaults to no

backend/playwright_homeserver-othersite.yaml

@@ -42,6 +42,13 @@ experimental_features:
   msc4354_enabled: true
   # MatrixRTC
   msc4143_enabled: true
+  # Enable membership look-up via /is_joined.
+  msc4502_enabled: true
+  # Enable C-S & S-S request proxying for application services.
+  msc4512_enabled: true
+
+app_service_config_files:
+  - /data/cfg/app-service.yaml
 
 # The maximum allowed duration by which sent events can be delayed, as
 # per MSC4140. Must be a positive value if set.  Defaults to no

backend/playwright_homeserver.yaml

@@ -42,6 +42,13 @@ experimental_features:
   msc4354_enabled: true
   # MatrixRTC
   msc4143_enabled: true
+  # Enable membership look-up via /is_joined.
+  msc4502_enabled: true
+  # Enable C-S & S-S request proxying for application services.
+  msc4512_enabled: true
+
+app_service_config_files:
+  - /data/cfg/app-service.yaml
 
 # The maximum allowed duration by which sent events can be delayed, as
 # per MSC4140. Must be a positive value if set.  Defaults to no

component/ElementCall.module.css

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

component/build/scopeStylesToRoot.test.ts

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

component/build/scopeStylesToRoot.ts

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

component/dev/DevHostBridge.ts

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

component/dev/Harness.module.css

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

component/dev/Harness.tsx

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

component/dev/host.css

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

component/dev/index.html

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

component/dev/main.tsx

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

component/dev/session.ts

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

component/host.test.ts

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

component/host.ts

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

component/index.tsx

@@ -0,0 +1,449 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+/**
+ * EXPERIMENTAL
+ *
+ * Element Call as a React component, for an application that wants to show a
+ * call inside itself rather than in an iframe.
+ *
+ * The host supplies the client and says which room to call in; Element Call
+ * supplies the call. Everything it would otherwise take from the page it is on
+ * — the URL, the document body, a Matrix session of its own — comes from the
+ * host instead, or is confined to the container it is mounted in.
+ */
+
+// The design tokens, fonts and element defaults every Element Call stylesheet
+// builds on. Written for a page, they speak of `html`, `body` and bare
+// elements; the component build confines them, and every other stylesheet in
+// this bundle, to the root element below (see build/scopeStylesToRoot.ts), so
+// that the host's document is left as it was.
+//
+// Where these land relative to the component stylesheets is the bundler's
+// choice — the standalone app puts them first, this build puts them in the
+// middle — so nothing in base.css may depend on winning or losing against a
+// component's own rules at equal specificity. It currently does not: what it
+// declares unlayered is custom properties on Element Call's root, which
+// components inherit rather than compete with, and everything from Compound
+// sits in a `@layer`, which loses to unlayered rules either way.
+import "../src/base.css";
+
+import {
+  type FC,
+  type JSX,
+  type ReactNode,
+  type Ref,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { type MatrixClient, type Room } from "matrix-js-sdk";
+import { logger } from "matrix-js-sdk/lib/logger";
+import { I18nextProvider } from "react-i18next";
+import { TooltipProvider } from "@vector-im/compound-web";
+import { ErrorBoundary } from "@sentry/react";
+import { shouldPolyfill as shouldPolyfillSegmenter } from "@formatjs/intl-segmenter/should-polyfill";
+import { shouldPolyfill as shouldPolyfillDurationFormat } from "@formatjs/intl-durationformat/should-polyfill.js";
+
+import LanguageDetector from "i18next-browser-languagedetector";
+
+import EN from "../locales/en/app.json";
+import { CallView } from "../src/room/CallView";
+import { ErrorPage } from "../src/FullScreenView";
+import { HostBridgeProvider } from "../src/HostBridge";
+import { RootElementProvider, useRootElement } from "../src/RootElementContext";
+import {
+  configurationForIntent,
+  componentProperties,
+  type UrlConfiguration,
+  type UrlParams,
+  UrlParamsProvider,
+  type UrlProperties,
+  UserIntent,
+  useUrlParams,
+} from "../src/UrlParams";
+import { MediaDevicesContext } from "../src/MediaDevicesContext";
+import { MediaDevices } from "../src/state/MediaDevices";
+import { ObservableScope } from "../src/state/ObservableScope";
+import { ProcessorProvider } from "../src/livekit/TrackProcessorContext";
+import { Config } from "../src/config/Config";
+import { type ConfigOptions } from "../src/config/ConfigOptions";
+import { i18n } from "../src/utils/i18n";
+import { useTheme } from "../src/useTheme";
+import { useStableValue } from "../src/useStableValue";
+import { type RtcMatrixDriver } from "../src/driver/RtcMatrixDriver";
+import { type ElementCallMatrixClientDriver } from "../src/driver/ElementCallMatrixClientDriver";
+import { useJsSdkDrivers } from "../src/driver/jsSdk/useJsSdkDrivers";
+import {
+  initMatrixRtcSdk,
+  type MatrixRtcWasmSource,
+} from "../src/matrix-rtc-sdk";
+import {
+  type MatrixDrivers,
+  MatrixDriverProvider,
+} from "../src/driver/MatrixDriverContext";
+import styles from "./ElementCall.module.css";
+import {
+  type ElementCallHandle,
+  type ElementCallHostBridge,
+  useComponentHostBridge,
+} from "./host";
+import { supportedLanguages, translationsBackend } from "./localization";
+
+// The languages Element Call can be shown in
+export { supportedLanguages } from "./localization";
+
+// What a host implements to drive Element Call with its own Matrix stack, and
+// the implementations of both over a matrix-js-sdk client
+export { type RtcMatrixDriver } from "../src/driver/RtcMatrixDriver";
+export {
+  type ElementCallMatrixClientDriver,
+  type MatrixClientFeatures,
+  type RoomInfo,
+  type RoomMemberProfile,
+  type TimelineEvent,
+  type OwnProfile,
+} from "../src/driver/ElementCallMatrixClientDriver";
+export { JsSdkRtcMatrixDriver } from "../src/driver/jsSdk/JsSdkRtcMatrixDriver";
+export { JsSdkElementCallMatrixClientDriver } from "../src/driver/jsSdk/JsSdkElementCallMatrixClientDriver";
+
+// 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 MatrixRTC side of the host's Matrix stack, bound to the room to call
+   * in: what the crate needs to publish a membership, exchange keys and mint
+   * transport tokens. Element Call does not authenticate anyone or manage a
+   * session of its own; both drivers are the host's.
+   */
+  rtcDriver: RtcMatrixDriver;
+  /**
+   * Everything else Element Call asks of a Matrix client for that room: who
+   * is in it, its name and avatar, the timeline for reactions and
+   * notifications, the user's own profile.
+   */
+  clientDriver: ElementCallMatrixClientDriver;
+  /**
+   * The room to call in. Optional, and when given it must be the room the
+   * drivers are bound to (`clientDriver.roomId`). Kept for one release so
+   * that hosts written for the client-based component can move over one
+   * prop at a time; then it goes.
+   */
+  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;
+}
+
+/**
+ * {@link ElementCall} for a host with a matrix-js-sdk client: the two drivers
+ * are built here from the client and the room, so the host hands over the
+ * client as it always has.
+ */
+export type ElementCallClientBasedProps = Omit<
+  ElementCallProps,
+  "rtcDriver" | "clientDriver" | "roomId"
+> & {
+  /**
+   * 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;
+};
+
+/**
+ * Prepares the things Element Call needs before it can be shown: translations,
+ * `Intl` polyfills for older browsers, and its configuration.
+ *
+ * Await this once, before rendering {@link ElementCall}.
+ */
+export interface InitializeElementCallOptions {
+  /**
+   * Where to load the MatrixRTC SDK's wasm from, for a host that serves it
+   * from somewhere other than next to this bundle. Left out, the bundled
+   * copy is loaded when the first call needs it.
+   */
+  matrixRtcWasm?: MatrixRtcWasmSource;
+}
+
+export async function initializeElementCall(
+  config: ConfigOptions = {},
+  { matrixRtcWasm }: InitializeElementCallOptions = {},
+): Promise<void> {
+  const polyfills: Promise<unknown>[] = [];
+  // The call runs on the Rust MatrixRTC crate; its wasm is loaded up front
+  // when the host says where from, and lazily otherwise.
+  if (matrixRtcWasm !== undefined)
+    polyfills.push(initMatrixRtcSdk(matrixRtcWasm));
+  if (shouldPolyfillSegmenter())
+    polyfills.push(import("@formatjs/intl-segmenter/polyfill-force"));
+  if (shouldPolyfillDurationFormat())
+    polyfills.push(import("@formatjs/intl-durationformat/polyfill-force.js"));
+  await Promise.all(polyfills);
+
+  Config.initWith(config);
+  await i18n
+    .use(translationsBackend)
+    .use(new LanguageDetector())
+    .init({
+      fallbackLng: "en",
+      defaultNS: "app",
+      keySeparator: ".",
+      nsSeparator: false,
+      pluralSeparator: "_",
+      contextSeparator: "|",
+      supportedLngs: [...supportedLanguages],
+      interpolation: { escapeValue: false },
+      // English is bundled in, so the fallback never has to be loaded; every
+      // other language arrives from the backend when first asked for.
+      partialBundledLanguages: true,
+      resources: { en: { app: EN } },
+      detection: {
+        // The browser's language, until the host says otherwise through the
+        // `language` prop. Nothing is remembered: the choice is the host's.
+        order: ["navigator"],
+        caches: [],
+      },
+    });
+}
+
+/** Applies the theme and background to the container, before it is painted. */
+const Decoration: FC<{ children: JSX.Element }> = ({ children }) => {
+  useTheme();
+  const { background } = useUrlParams();
+  const rootElement = useRootElement();
+  useLayoutEffect(() => {
+    rootElement.setAttribute("data-background", background);
+  }, [rootElement, background]);
+  return children;
+};
+
+export const ElementCall: FC<ElementCallProps> = ({
+  rtcDriver,
+  clientDriver,
+  roomId: suppliedRoomId,
+  intent = UserIntent.JoinExistingCall,
+  config,
+  hostBridge: suppliedHostBridge,
+  ref,
+  theme,
+  language,
+}): ReactNode => {
+  const hostBridge = useComponentHostBridge(suppliedHostBridge, ref, theme);
+  const roomId = clientDriver.roomId;
+  if (suppliedRoomId !== undefined && suppliedRoomId !== roomId)
+    throw new Error(
+      `Element Call was asked to call in ${suppliedRoomId} with drivers bound to ${roomId}`,
+    );
+
+  useEffect(() => {
+    if (language !== undefined)
+      i18n
+        .changeLanguage(language)
+        .catch((e) => logger.error(`Could not switch to ${language}`, e));
+  }, [language]);
+
+  // The container is what Element Call decorates and portals into, so nothing
+  // inside can render until we have it.
+  const [container, setContainer] = useState<HTMLDivElement | null>(null);
+
+  // Element Call has no URL of its own to read any of this from, and the
+  // host's URL is not Element Call's business, so the defaults come from the
+  // intent with the host's wishes over the top.
+  //
+  // Everything downstream — the mute state, the call view model and with it
+  // the media connection — is keyed on the identity of this object, so it has
+  // to be stable for as long as its contents are. A host writing `config`
+  // inline would otherwise tear the call down on every render.
+  const stableConfig = useStableValue(config);
+  const params = useMemo(
+    (): UrlParams => ({
+      ...componentProperties,
+      roomId,
+      ...configurationForIntent(intent),
+      ...stableConfig,
+    }),
+    [roomId, intent, stableConfig],
+  );
+
+  // Created in an effect so that the scope it lives in ends when the component
+  // is unmounted (or these options change), rather than keeping its device
+  // observers running for the rest of the page's life. Null until then, which
+  // is one render.
+  const { controlledAudioDevices, callIntent } = params;
+  const [mediaDevices, setMediaDevices] = useState<MediaDevices | null>(null);
+  useEffect(() => {
+    const scope = new ObservableScope();
+    setMediaDevices(
+      new MediaDevices(scope, { controlledAudioDevices, callIntent }),
+    );
+    return (): void => {
+      setMediaDevices(null);
+      scope.end();
+    };
+  }, [controlledAudioDevices, callIntent]);
+
+  // The call runs on the Rust MatrixRTC crate over these two drivers; no
+  // matrix-js-sdk client is involved.
+  const drivers = useMemo(
+    (): MatrixDrivers => ({ rtcDriver, clientDriver }),
+    [rtcDriver, clientDriver],
+  );
+
+  // Everything the call needs is in hand once these exist, and the first
+  // render with them is where the call itself appears: the moment the host
+  // is told that Element Call has loaded, as the widget tells its client once
+  // its own initialisation is over. Once per mount, however often the pieces
+  // are later swapped out.
+  const ready = container !== null && mediaDevices !== null;
+  const announcedLoaded = useRef(false);
+  useEffect(() => {
+    if (!ready || announcedLoaded.current) return;
+    announcedLoaded.current = true;
+    hostBridge
+      .contentLoaded()
+      .catch((e) => logger.error("Could not tell the host we had loaded", e));
+  }, [ready, hostBridge]);
+
+  return (
+    <I18nextProvider i18n={i18n}>
+      <HostBridgeProvider value={hostBridge}>
+        <UrlParamsProvider value={params}>
+          <div ref={setContainer} className={styles.root}>
+            {ready && (
+              <RootElementProvider value={container}>
+                {/* Whatever goes wrong in here is shown in here. Left to
+                  propagate, an error would unmount the host's own tree. */}
+                <ErrorBoundary
+                  fallback={(error) => <ErrorPage error={error} />}
+                  // A broken call should not hold the host on screen
+                  onError={() => void hostBridge.setAlwaysOnScreen(false)}
+                >
+                  <Decoration>
+                    <TooltipProvider>
+                      <MatrixDriverProvider value={drivers}>
+                        <MediaDevicesContext value={mediaDevices}>
+                          <ProcessorProvider>
+                            <CallView
+                              isPasswordlessUser={false}
+                              confineToRoom={params.confineToRoom}
+                              preload={params.preload}
+                              skipLobby={params.skipLobby}
+                            />
+                          </ProcessorProvider>
+                        </MediaDevicesContext>
+                      </MatrixDriverProvider>
+                    </TooltipProvider>
+                  </Decoration>
+                </ErrorBoundary>
+              </RootElementProvider>
+            )}
+          </div>
+        </UrlParamsProvider>
+      </HostBridgeProvider>
+    </I18nextProvider>
+  );
+};
+
+export const ElementCallClientBased: FC<ElementCallClientBasedProps> = ({
+  client,
+  roomId,
+  ...props
+}): ReactNode => {
+  const room = client.getRoom(roomId);
+  if (room === null) {
+    logger.error(
+      `Element Call was asked to call in ${roomId}, which its host's client does not know about`,
+    );
+    return null;
+  }
+  return <ClientBasedCall client={client} room={room} {...props} />;
+};
+
+/** {@link ElementCallClientBased} once the room is known: builds the drivers. */
+const ClientBasedCall: FC<
+  Omit<ElementCallClientBasedProps, "roomId"> & { room: Room }
+> = ({ client, room, ...props }): ReactNode => {
+  const drivers = useJsSdkDrivers(client, room);
+  return <ElementCall {...props} {...drivers} />;
+};

component/localization.test.ts

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

component/localization.ts

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

component/package.json

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

component/pnpm-lock.yaml

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

component/pnpm-workspace.yaml

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

component/tsconfig.build.json

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

config/config.devenv.json

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

config/config.sample.json

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

config/config_netlify_preview.json

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

config/config_netlify_preview_sdk.json

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

docker-compose-dev.yml

@@ -3,7 +3,7 @@ networks:
 
 services:
   auth-service:
-    image: ghcr.io/element-hq/lk-jwt-service:0.4.4
+    image: ghcr.io/element-hq/lk-jwt-service:0.7.0
     pull_policy: always
     hostname: auth-server
     environment:
@@ -15,6 +15,14 @@ services:
       # a self-signed certificate
       - LIVEKIT_INSECURE_SKIP_VERIFY_TLS=YES_I_KNOW_WHAT_I_AM_DOING
       - LIVEKIT_FULL_ACCESS_HOMESERVERS=*
+      # Registers this instance as an application service on the main homeserver
+      - LIVEKIT_AS_REGISTRATION_FILE=/etc/lk-jwt-service/app-service.yaml
+      - LIVEKIT_HS_SERVER_NAME=synapse.m.localhost
+      # Neither homeserver serves /.well-known/matrix/client, so the C-S API
+      # location has to be given explicitly.
+      - LIVEKIT_CS_API_URL_OVERRIDES=synapse.m.localhost=http://homeserver:8008,synapse.othersite.m.localhost=http://homeserver-1:18008
+    volumes:
+      - ./backend/app-service.yaml:/etc/lk-jwt-service/app-service.yaml:Z
     deploy:
       restart_policy:
         condition: on-failure
@@ -25,7 +33,7 @@ services:
       - ecbackend
 
   auth-service-1:
-    image: ghcr.io/element-hq/lk-jwt-service:0.4.4
+    image: ghcr.io/element-hq/lk-jwt-service:0.7.0
     pull_policy: always
     hostname: auth-server-1
     environment:
@@ -37,6 +45,14 @@ services:
       # a self-signed certificate
       - LIVEKIT_INSECURE_SKIP_VERIFY_TLS=YES_I_KNOW_WHAT_I_AM_DOING
       - LIVEKIT_FULL_ACCESS_HOMESERVERS=*
+      # Registers this instance as an application service on the other homeserver.
+      - LIVEKIT_AS_REGISTRATION_FILE=/etc/lk-jwt-service/app-service.yaml
+      - LIVEKIT_HS_SERVER_NAME=synapse.othersite.m.localhost
+      # Neither homeserver serves /.well-known/matrix/client, so the C-S API
+      # location has to be given explicitly.
+      - LIVEKIT_CS_API_URL_OVERRIDES=synapse.m.localhost=http://homeserver:8008,synapse.othersite.m.localhost=http://homeserver-1:18008
+    volumes:
+      - ./backend/app-service-othersite.yaml:/etc/lk-jwt-service/app-service.yaml:Z
     deploy:
       restart_policy:
         condition: on-failure
@@ -94,7 +110,10 @@ services:
 
   synapse:
     hostname: homeserver
-    image: ghcr.io/element-hq/synapse:latest
+    # develop (not latest) is required for application service C-S/S-S proxying
+    # (MSC4512) and membership look-ups (MSC4502), which are not in a stable
+    # release yet.
+    image: ghcr.io/element-hq/synapse:develop
     pull_policy: always
     environment:
       - SYNAPSE_CONFIG_PATH=/data/cfg/homeserver.yaml
@@ -107,12 +126,16 @@ services:
     volumes:
       - ./backend/synapse_tmp:/data:Z
       - ./backend/dev_homeserver.yaml:/data/cfg/homeserver.yaml:Z
+      - ./backend/app-service.yaml:/data/cfg/app-service.yaml:Z
     networks:
       - ecbackend
 
   synapse-1:
     hostname: homeserver-1
-    image: ghcr.io/element-hq/synapse:latest
+    # develop (not latest) is required for application service C-S/S-S proxying
+    # (MSC4512) and membership look-ups (MSC4502), which are not in a stable
+    # release yet.
+    image: ghcr.io/element-hq/synapse:develop
     pull_policy: always
     environment:
       - SYNAPSE_CONFIG_PATH=/data/cfg/homeserver.yaml
@@ -125,6 +148,7 @@ services:
     volumes:
       - ./backend/synapse_tmp_othersite:/data:Z
       - ./backend/dev_homeserver-othersite.yaml:/data/cfg/homeserver.yaml:Z
+      - ./backend/app-service-othersite.yaml:/data/cfg/app-service.yaml:Z
     networks:
       - ecbackend
 

docker-compose-playwright.yml

@@ -3,12 +3,18 @@
 services:
   synapse:
     # Pin to a SHA so that upstream cannot break our tests. Renovate handles regular updates.
-    image: ghcr.io/element-hq/synapse:latest@sha256:da325af40104051923899e5f5a2f1d537e6e3ccf2f0f38285689ae9bbfdb190a
+    # develop (not latest) is required for application service C-S/S-S proxying
+    # (MSC4512) and membership look-ups (MSC4502), which are not in a stable
+    # release yet.
+    image: ghcr.io/element-hq/synapse:develop@sha256:337921fd22be310d453344b2265f6c9942315446595df3cf81866f71ca2055a7
     volumes:
       - ./backend/playwright_homeserver.yaml:/data/cfg/homeserver.yaml:Z
   synapse-1:
     # Pin to a SHA so that upstream cannot break our tests. Renovate handles regular updates.
-    image: ghcr.io/element-hq/synapse:latest@sha256:da325af40104051923899e5f5a2f1d537e6e3ccf2f0f38285689ae9bbfdb190a
+    # develop (not latest) is required for application service C-S/S-S proxying
+    # (MSC4512) and membership look-ups (MSC4502), which are not in a stable
+    # release yet.
+    image: ghcr.io/element-hq/synapse:develop@sha256:337921fd22be310d453344b2265f6c9942315446595df3cf81866f71ca2055a7
     volumes:
       - ./backend/playwright_homeserver-othersite.yaml:/data/cfg/homeserver.yaml:Z
   element-web:

docs/README.md

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

docs/agents/architecture.md

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

docs/agents/code-style.md

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

docs/agents/testing.md

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

docs/agents/workflow.md

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

docs/embedded_standalone.md

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

docs/linking.md

@@ -29,6 +29,9 @@ Instead, create a file named `.links.cjs` in the Element Call project directory
 module.exports = {
   "matrix-js-sdk": "../your/path/matrix-js-sdk",
   "matrix-widget-api": "../your/path/matrix-widget-api",
+  // The MatrixRTC SDK: run `npm run build` in that directory first
+  "@element-hq/matrix-rtc":
+    "../your/path/matrix-rust-rtc/MatrixSdkArchitectureDraft/web-test-app",
 };
 ```
 

docs/matrix_rtc_sdk.md

@@ -0,0 +1,135 @@
+# The MatrixRTC SDK package
+
+Element Call's MatrixRTC logic (session membership, keep-alive, transport
+tokens, media key exchange) runs in the Rust `matrix-rtc` crate, compiled to
+WebAssembly and shipped as the npm package `@element-hq/matrix-rtc`. The
+package is built and published by the
+[`npm-web-bindings.yml`](https://github.com/element-hq/matrix-rust-rtc/blob/main/.github/workflows/npm-web-bindings.yml)
+workflow of the `matrix-rust-rtc` repository, from its
+`MatrixSdkArchitectureDraft/web-test-app` directory. Element Call loads it in
+`src/matrix-rtc-sdk/index.ts`, the only module that imports the package
+directly.
+
+## Where the package comes from
+
+For now the package lives on the **GitHub Packages** npm registry
+(`https://npm.pkg.github.com`), not on npmjs.com. **This is a stop-gap** for
+the phase in which the crate's API still changes with every push: publishing
+from the crate's CI into a registry that comes with the repository needs no
+account or secret upstream, and nothing else consumes the package yet. Once
+the SDK is ready for consumers beyond Element Call, it should be published to
+**npmjs.com** as `@element-hq/matrix-rtc`, which makes everything in this
+document about tokens and scopes go away: `pnpm install` works anonymously
+again, forks and Renovate can install, component hosts need no setup, and the
+alias in `package.json` and the scope line in `.npmrc` are deleted.
+
+Until then, two properties of GitHub Packages shape the setup below:
+
+- **Every request needs a token**, including reads of public packages. There
+  is no anonymous install.
+- **A package is scoped to the owner of the repository whose CI published
+  it.** While the crate is developed on the `BillCarsonFr` fork, the package is
+  published as `@billcarsonfr/matrix-rtc`; once it is published from
+  `element-hq/matrix-rust-rtc` it becomes `@element-hq/matrix-rtc`.
+
+So that the code does not have to change when that happens, `package.json`
+installs the fork's package under the final name:
+
+```json
+"@element-hq/matrix-rtc": "npm:@billcarsonfr/matrix-rtc@next"
+```
+
+and the repository's `.npmrc` maps only the scope to the registry:
+
+```ini
+@billcarsonfr:registry=https://npm.pkg.github.com
+```
+
+When the package moves to `element-hq`, change the alias to the plain package
+and the scope line in `.npmrc` accordingly; nothing else in the repository
+refers to the fork's name.
+
+## Setting up your machine
+
+1. Create a **personal access token (classic)** at
+   <https://github.com/settings/tokens> with only the `read:packages` scope.
+   Fine-grained tokens do not work with GitHub Packages.
+2. Add it to your **user-level** npm config. Never put it in the repository's
+   `.npmrc`:
+
+   ```sh
+   echo "//npm.pkg.github.com/:_authToken=<your token>" >> ~/.npmrc
+   ```
+
+3. Run `pnpm install` as usual.
+
+Without the token, `pnpm install` fails while resolving
+`@billcarsonfr/matrix-rtc` with a `401` or `404` from `npm.pkg.github.com`;
+that error always means "no or wrong token", never "the package does not
+exist".
+
+## CI and other consumers
+
+A workflow's built-in `GITHUB_TOKEN` can only read packages owned by the
+repository's own owner, so element-hq's workflows cannot read a package owned
+by the `BillCarsonFr` user. The workflows that run `pnpm install` therefore
+write a personal access token from the repository secret
+`MATRIX_RTC_NPM_TOKEN` (scope `read:packages`) to `~/.npmrc` before installing.
+Keep in mind:
+
+- **Pull requests from forks and from Renovate do not receive secrets**, so
+  their installs fail until the package is readable with the built-in token.
+- **Hosts of the [component](../README.md#element-call-as-a-component-experimental)**
+  install it as a git dependency whose `prepare` script runs
+  `pnpm install --frozen-lockfile` in this repository, so they need the same
+  token in their `~/.npmrc` or CI.
+
+Publishing from `element-hq/matrix-rust-rtc` (and granting the Element Call
+repository access to the package) would let the built-in token work for
+element-hq's own workflows, but that only patches the CI case. The intended end
+state is the npmjs.com publication described above, which removes the token
+requirement for everyone.
+
+## Versions
+
+The package version tracks the crate's `Cargo.toml`. Every push to the tracked
+branches of `matrix-rust-rtc` publishes a `next` pre-release named
+`<version>-next.<run number>.<short sha>`, and a `matrix-rtc-v<version>` tag
+publishes `latest`. Element Call follows `next`; `pnpm install` picks up a new
+pre-release only when the lockfile is updated, e.g. with
+`pnpm update @element-hq/matrix-rtc`.
+
+The publish job runs only after the crate's own `cargo test` job passed on a
+_push_ (pull-request runs never publish). If a `next` build you expect is
+missing, check that workflow's push runs for a failed crate job and re-run it;
+its tests are known to be timing-sensitive.
+
+## Developing against a local crate checkout
+
+To run Element Call against a crate you are changing, build the package there
+and link it, instead of waiting for CI:
+
+```sh
+cd ../matrix-rust-rtc/MatrixSdkArchitectureDraft/web-test-app
+npm install && npm run build      # produces dist/
+```
+
+then add it to `.links.cjs` in this repository and run `pnpm links:on`, as
+described in [Developing with linked packages](./linking.md):
+
+```cjs
+"@element-hq/matrix-rtc": "../matrix-rust-rtc/MatrixSdkArchitectureDraft/web-test-app",
+```
+
+`pnpm links:off` restores the registry package before committing.
+
+## How the wasm is loaded
+
+`initMatrixRtcSdk()` in `src/matrix-rtc-sdk/index.ts` is the single entry
+point: it awaits the package's `initAsync`, then installs the log sink that
+routes the crate's logs into Element Call's logger. The wasm is imported as
+`@element-hq/matrix-rtc/wasm?url`, so the app builds emit it as an asset next
+to the other `.wasm` files and the component build inlines it. Unit tests read
+the bytes from the installed package instead (`src/utils/test-matrix-rtc.ts`),
+since vitest has no server to fetch from. A component host can point at a copy
+it serves itself through `initializeElementCall(config, { matrixRtcWasm })`.

element-call-oxidation-plan.md

@@ -0,0 +1,977 @@
+# Element Call oxidation plan
+
+Move Element Call's MatrixRTC participation logic off `matrix-js-sdk`'s
+`MatrixRTCSession` and onto the Rust `matrix-rtc` crate
+(`~/Projects/matrix-rust-rtc/MatrixSdkArchitectureDraft`), consumed through its
+uniffi wasm bindings. The Element Call **component** then depends on one
+host-supplied object, a `MatrixDriver`, and never on a `MatrixClient`. The
+standalone app and the widget become hosts like any other: they build a
+`MatrixDriver` from their `matrix-js-sdk` client and hand it to the component.
+
+Revision 2 — incorporates the independent review (§10 lists what changed and
+the assumptions taken where only the user can decide).
+
+Status legend: ☐ todo · ◐ in progress · ☑ done.
+
+**Where things stand (2026-09-14):** S0a, S0b, S1a, S1b and S2 are
+implemented and green (`pnpm lint`, `pnpm format:check`, `pnpm test:unit`:
+101 files / 785 tests). Nothing is committed yet, in either repository: the
+crate changes C2–C12 (C1 reverted in favour of slot opening) are done; C2–C8,
+C11 and C12 are committed in the draft repo as `a8e21b3`, C5 (final form), C9
+and C10 are still uncommitted there. In Element Call everything sits
+uncommitted in
+`~/Projects/matrix-rust-rtc/MatrixSdkArchitectureDraft`, and Element Call's
+branch `toger5/oxidation` holds the vendored bindings, the driver layer
+(`src/driver/**`), the participation layer (`src/state/rtc/**`) and the
+config/lint changes. S3a is the next slice; its design is in §6 and the
+files it touches are listed there.
+
+---
+
+## 1. Goals and non-goals
+
+**Goals**
+
+1. `ElementCall` (component) takes `driver: MatrixDriver` instead of
+   `client: MatrixClient`. Nothing rendered under `CallView` imports
+   `MatrixClient`, `Room`, `RoomMember`, `MatrixEvent` or
+   `matrix-js-sdk/lib/matrixrtc`.
+2. All MatrixRTC participation logic (session projection, own membership
+   join/leave/keep-alive, transport tokens, media key exchange) comes from the
+   crate's `FfiParticipationManager`. Element Call keeps only what the crate
+   deliberately leaves to the host: the LiveKit media plane, tiles, room
+   metadata, reactions, notifications, UI.
+3. The standalone SPA, widget mode and `sdk/main.ts` construct a
+   `JsSdkMatrixDriver` (a port of the draft's `web-test-app/src/jsSdkDriver.ts`
+   that also works on js-sdk's `RoomWidgetClient`, extended with what Element
+   Call needs beyond RTC) and stop using `client.matrixRTC`.
+4. Every existing gate stays green: `pnpm lint` (tsc, oxlint, knip, component
+   externals), `pnpm format:check`, `pnpm test` (unit + storybook),
+   `pnpm i18n:check`, all four builds, Playwright (standalone, widget,
+   component).
+
+**Non-goals**
+
+- Replacing `matrix-js-sdk` in the standalone shell (login, registration, room
+  creation, home page, crypto bootstrap). The shell keeps its client and wraps
+  it. `src/home/useGroupCallRooms.ts` stays on `client.matrixRTC` for now.
+- Removing `matrix-js-sdk/lib/logger`. It is isolated behind
+  `src/utils/logger.ts` (S6) so a later swap is one line.
+- Writing a matrix-rust-sdk-backed driver (Element X). The interface is shaped
+  so one can be written; none is written here.
+- Publishing the crate as an npm package: done upstream (`@element-hq/matrix-rtc`,
+  built and published by `npm-web-bindings.yml` in matrix-rust-rtc; consumed
+  here since 2026-09-16, §5.1).
+- Turning on MSC4153 (cross-signed sender) enforcement. Parity first (§5.8).
+
+---
+
+## 2. Where the code is today (inventory)
+
+Entry: `component/index.tsx` → `src/room/CallView.tsx` → `LobbyView` |
+`ActiveCall` (`src/room/InCallView.tsx`) | `CallEndedView`. `ActiveCall`
+builds the view model with
+`createCallViewModel$(scope, rtcSession, matrixRoom, mediaDevices, muteStates, options, raisedHands$, reactions$, trackProcessorState$)`.
+
+| Concern                          | Files                                                                                                                                                                                                                                              | js-sdk surface used                                                                                                                                                                                            |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Session memberships              | `src/state/SessionBehaviors.ts`, `src/useMatrixRTCSessionMemberships.ts`                                                                                                                                                                           | `rtcSession.memberships`, `MembershipsChanged`, `membership.getTransport`, `isKeyRotationSuppressed`                                                                                                           |
+| Own membership                   | `localMember/LocalMember.ts` (`enterRTCSession`), `localMember/HomeserverConnected.ts`                                                                                                                                                             | `joinRTCSession`, `leaveRoomSession(1000)`, `updateCallIntent`, `MembershipManagerEvent.*`, `ClientEvent.Sync`; delegation probe at `LocalMember.ts:298-313`, delegation through the JWT service at `:731-756` |
+| SFU / JWT                        | `src/livekit/openIDSFU.ts`, `localMember/LocalTransport.ts`, `localMember/RtcTransportAutoDiscovery.ts`, `remoteMembers/Connection.ts`, `ConnectionFactory.ts`, `ConnectionManager.ts`                                                             | `getOpenIdToken`, `_unstable_getRTCTransports`, `POST /get_token` (+ `delay_id`, `delay_timeout`, `delay_cs_api_url`), legacy `/sfu/get`                                                                       |
+| Remote member ↔ LiveKit identity | `remoteMembers/MatrixLivekitMembers.ts`                                                                                                                                                                                                            | `rtcBackendIdentity`, `userId`, `deviceId`, `memberId`                                                                                                                                                         |
+| E2EE media keys                  | `src/e2ee/matrixKeyProvider.ts`, `src/e2ee/sharedKeyManagement.ts`                                                                                                                                                                                 | `EncryptionKeyChanged`, `reemitEncryptionKeys`, `room.hasEncryptionStateEvent`                                                                                                                                 |
+| Room metadata                    | `remoteMembers/MatrixMemberMetadata.ts`, `src/utils/displayname.ts`, `src/room/useRoomName.ts`, `useRoomState.ts`, `useRoomAvatar.ts`, `useJoinRule.ts`, `InviteModal.tsx`, `CallView.tsx`                                                         | `getMembersWithMembership`, `RoomStateEvent.Members`, `room.name`, `getMxcAvatarUrl`, `getJoinRule`, `getCanonicalAlias`                                                                                       |
+| Own profile / avatars            | `src/profile/useProfile.ts`, `src/Avatar.tsx`                                                                                                                                                                                                      | `getUser`, `UserEvent.*`, `setDisplayName`, `setAvatarUrl`, `uploadContent`, `mxcUrlToHttp`, `getAccessToken`                                                                                                  |
+| Reactions / hand raise           | `src/reactions/ReactionsReader.ts`, `useReactionsSender.tsx`, `src/reactions/index.ts`                                                                                                                                                             | `RoomEvent.Timeline/Redaction/LocalEchoUpdated`, `MatrixEventEvent.Decrypted`, `relations.getChildEventsForEvent`, `sendEvent`, `redactEvent`, membership `eventId`, `RelationType`                            |
+| Call notifications               | `CallViewModel/CallNotificationLifecycle.ts`                                                                                                                                                                                                       | `DidSendCallNotification`, `RoomEvent.Timeline` + `EventType.RTCDecline`                                                                                                                                       |
+| Rageshake / dev settings         | `src/settings/submit-rageshake.ts`, `rageshake.ts`, `FeedbackSettingsTab.tsx`, `DeveloperSettingsTab.tsx`                                                                                                                                          | `getCrypto`, `sendEvent(org.matrix.rageshake_request)`, `ClientEvent.Event`, `secureRandomString`, `doesServerSupportUnstableFeature`, `getSFUConfigWithOpenID`                                                |
+| Analytics                        | `src/analytics/PosthogEvents.ts`, `PosthogAnalytics.ts`                                                                                                                                                                                            | `rtcSession.statistics`, account data                                                                                                                                                                          |
+| Types only                       | `src/UrlParams.ts`, `src/state/MediaDevices.ts`, `AndroidControlledAudioOutput.ts`, `IOSControlledAudioOutput.ts`, `initialMuteState.ts`, `state/media/RingingMediaViewModel.ts` (`RTCCallIntent`), `src/useEvents.ts` (`TypedEventEmitter` types) | replaced by a local `CallIntent` type / kept as generic emitter typing                                                                                                                                         |
+| Runtime misc                     | `src/useLocalStorage.ts` (`TypedEventEmitter`), `src/room/GroupCallErrorBoundary.tsx` (`MatrixError`), `src/room/KnockLobbyView.tsx` (shell)                                                                                                       | see S6                                                                                                                                                                                                         |
+| Context                          | `src/ClientContext.tsx`                                                                                                                                                                                                                            | `useClient`/`useClientState` used by `Avatar`, `sharedKeyManagement`, `useReactionsSender`, `submit-rageshake`                                                                                                 |
+
+Hosts: `component/index.tsx:291`, `src/room/useLoadGroupCall.ts:335`,
+`sdk/main.ts:128` (own `MatrixRTCSessionManager`; waits on
+`MatrixRTCSessionEvent.JoinStateChanged` at `:292`). Test kit:
+`src/utils/test.ts` (`MockRTCSession`, `mockRtcMembership`, `mockMatrixRoom`),
+`src/utils/test-viewmodel.ts`, `CallViewModelTestUtils.ts`. Baseline on
+`main` (fe911628): tsc green, 97 unit files / 757 tests green.
+
+Component build: `vite-component.config.ts` (single string `fileName`,
+externals list with 18 `matrix-js-sdk/lib/*` subpaths), `pnpm lint:externals`,
+`component/package.json` (`matrix-js-sdk: "*"` peer, `exports` without a
+wildcard).
+
+---
+
+## 3. What the crate gives us, what it does not, and what must change in it
+
+Verified against `src/uniffi_api/mod.rs`, `src/participation/mod.rs`,
+`src/session/state.rs`, `src/own_membership/machine.rs`,
+`src/encryption/matrix_encryption_event.rs` and the generated
+`web-test-app/src/generated/matrix_rtc.ts` (acceptance suites: 32 pass).
+
+**Provided** (`FfiParticipationManager`, one per `(room, slot)`, any number
+share one `FfiMatrixDriver`):
+
+- `join(FfiTransportIntent, FfiJoinParams)` / `leave(code?, reason?)`; a
+  `Publish` intent with a bare LiveKit transport triggers discovery through
+  `driver.getRtcTransports()` (`connections/mod.rs:470-499`); a driver _error_
+  there is `NoTransport`, not a fallback.
+- `memberships()` + listener: `FfiMembership { member { memberId, userId,
+deviceId, displayName?, avatarUrl?, intent?, applicationType?,
+publishedTransports, canSubscribe }, state: Joined | LeftWithKeys,
+connections: serviceUrl[] (the FFI doc comment saying ws urls is wrong),
+transportIdentity?, mediaKey? }`. `transportIdentity` is today's
+  `rtcBackendIdentity`. `LeftWithKeys` entries have empty `connections`.
+- `connections()` + listener: `{ connection { serviceUrl, wsUrl, jwtToken,
+expiresAtTs }, members }[]`; tokens re-minted a minute before `exp`.
+- `keyMap()` + `setKeyMapListener(map, change)`: `FfiMediaKey { memberId, key:
+ArrayBuffer, index, creationTsMs: bigint }`, inbound keys **and our own**
+  (`encryption/inbound.rs:251-257`).
+- `status()` + listener: `Disconnected{cause} | Joining | Connected{keepAlive,
+membership, roster, encryption, impairments} | Leaving`.
+- `session()`, `ownMemberId()` (available as soon as `join()` starts),
+  `ownMembership()`, `connectionProblems()`, `debugSnapshot()`.
+- Member display names and avatars, from the room's `m.room.member` state
+  (C8): the session keeps them current, so a rename is a memberships change.
+- Slots are required: once the seed has read slot state, a slot with no event
+  is closed, so a room without an `m.rtc.slot` has no call, in every dialect.
+  `openSlot(application, encrypted)` / `closeSlot()` send the state event;
+  the slot id `m.call#ROOM` matches js-sdk's default.
+- `FfiElementCallCompat.{Off, StateEvents}`: spec MSC4143, or MSC3401 state
+  events for the clients that predate sticky events (C9 removed the never
+  deployed 2025 sticky dialect).
+- All `u64` fields are `bigint` in TypeScript; `Vec<u8>` is `ArrayBuffer`.
+- Listener callbacks arrive one timer tick after the emitting call (pumps
+  sleep through `setTimeout`, `executor.rs:86`); getters are fresh.
+
+**Not provided — Element Call keeps it, through the driver** (§4.1 slices):
+
+| Need                                                                           | Why not in the crate                                 | Where it goes                                                                                                                            |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Room name, alias, avatar, join rule, encryption flag                           | room metadata                                        | `RoomDriver.getRoomInfo`                                                                                                                 |
+| Profiles of room members who are not in the call (ringing, name-tag threshold) | not RTC                                              | `RoomDriver.subscribeRoomMembers`                                                                                                        |
+| Reactions, hand raise, `org.matrix.rageshake_request`                          | application events                                   | `TimelineDriver`                                                                                                                         |
+| MSC4075 notification + decline                                                 | out of scope (only `wire_event_type` knows the type) | `TimelineDriver.sendRoomEvent`, decided in `CallNotificationLifecycle` (§4.3)                                                            |
+| Own profile read/write                                                         | not RTC                                              | `ProfileDriver`                                                                                                                          |
+| `mxc://` thumbnails with auth                                                  | not RTC                                              | `MediaDriver.thumbnailUrl`                                                                                                               |
+| Homeserver sync connectivity                                                   | needed by the crate too                              | `RtcMatrixDriver` (`isHomeserverConnected`, `subscribeConnectivity`, C12); reaches Element Call as `HomeserverUnreachable` in the status |
+| Sticky-events support probe                                                    | capability probe                                     | `MatrixDriver.getMatrixClientFeatures()`                                                                                                 |
+
+**Must change in the crate (S0a) — each blocks a later slice:**
+
+| #   | Problem                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Change                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| C1  | A successful `read_state("m.rtc.slot")` returning `[]` marks slot state supplied and every slot other than the legacy `""` resolves `Closed` (`session/state.rs`); `join()` then fails with `SlotClosed` and every MSC4143 peer is excluded. Element Call never sent `m.rtc.slot`.                                                                                                                                                                      | **Kept as the crate has it: no slot means no call.** Element Call opens the slot when nobody has (`RtcParticipationManager.join` with a `SlotPolicy`: `openSlot("m.call", encrypted)`, then wait for the echo), which needs the power level to send `org.matrix.msc4143.rtc.slot`; without it the join fails with `NoOpenSlotError`. Existing rooms keep working because the first call in a room opens its slot. A compat-mode relaxation was tried and reverted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| C2  | `manage_media_keys`, `require_cross_signed_sender`, `use_key_delay_ms` are not settable over the FFI; defaults are `true`, `true`, 1000 ms.                                                                                                                                                                                                                                                                                                             | New record `FfiParticipationConfig { compat, manage_media_keys, require_cross_signed_sender, use_key_delay_ms }` as the constructor argument (replaces the bare `compat`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| C3  | `StickyEvents` compat sent keys as `org.matrix.msc4143.rtc.encryption_key` while deployed clients read only `io.element.call.encryption_keys`.                                                                                                                                                                                                                                                                                                          | Made moot by C9 and reverted with it: the sticky dialect goes away entirely, so `Off` sends the spec key message and `StateEvents` the legacy one, with no middle case.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| C4  | `FfiMember` has no membership `event_id`; reactions relate to it (§4.3).                                                                                                                                                                                                                                                                                                                                                                                | `Member.event_id: Option<String>` threaded through `session/dispatch.rs` → `convert/*` → `state.rs` (currently dropped at `state.rs:402`) → `FfiMember.event_id`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| C5  | **Done.** Delegating the delayed leave (MSC4195) is split between the crate and the host: the draft's driver method makes the _adapter_ perform the whole delegation, its demo adapter calls a homeserver endpoint that 401s on a widget client, and Element Call today does it differently (probe, then the authorisation service's `get_token` with `delay_id`/`delay_timeout`/`delay_cs_api_url`). Nothing of this exists in the real `crates/` yet. | **The crate owns the policy; the driver keeps two primitives.** (a) `delegate_delayed_leave_via_homeserver(room, slot, member, delay_id)`: one authenticated POST to the CS API endpoint (`/_matrix/client/unstable/io.element.msc4195/rtc/livekit/delegate_delayed_leave`, the spelling Element Call probes today; a widget client answers `Unsupported`). (b) `LivekitTokenRequest.delegation: Option<{ delay_id, delay_timeout_ms }>`: the adapter appends `delay_id`, `delay_timeout` and `delay_cs_api_url` (its own homeserver URL) to the `get_token` / `sfu/get` body it already sends. The own-membership machine tries (a) first and, on `Unsupported` or any failure, (b) against the transport we publish on, i.e. Element Call's OpenID → JWT → scheduled-event path; only if both fail does it keep restarting the switch itself. **Arm-after-confirm:** the short delayed leave stays armed through the join; delegation arms a second, ≥ 1 h delayed leave, delegates _that_, and cancels the short one on success (or the long one on failure), so no moment is left without an armed leave and a failed delegation costs nothing. `KeepAlive::Delegated` says which route succeeded. The interim C5 (service URL and delay on the request) and Element Call's driver-side probe and JWT delegation are replaced by this. **Real-backend check (2026-09-15):** both routes send the MSC4195 `member` _claims_ (`{ id, claimed_user_id, claimed_device_id }`), not the member block of the event. The homeserver route body is what lk-jwt-service 0.7 accepts behind a Synapse that proxies `rtc/livekit/*` to it (MSC4512, `backend/app-service.yaml`): `{ url, room_id, slot_id, member, delay_id, delay_timeout }`, where `url` is the SFU websocket URL the transport's token named (the service checks it is its own). The transport resolver therefore returns `ResolvedTransport { transport, sfu_url }` and the machine carries the url into `Action::DelegateViaHomeserver`; without an SFU url it goes straight to the service route, and a receive-only member (no transport) delegates nothing. Verified end to end against `pnpm backend`: the homeserver route takes the 1 h leave (`KeepAlive::Delegated { via: Homeserver }`, one delayed event of 3 600 000 ms on the server). |
+| C6  | The transport identity is a pure function (`connections/mod.rs:116-135`) but not exported; the own identity is needed before our membership echo to set our own media key.                                                                                                                                                                                                                                                                              | Export `FfiParticipationManager.own_transport_identity(): Option<String>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| C7  | Doc comment on `FfiMembership.connections` says `ws_url`s.                                                                                                                                                                                                                                                                                                                                                                                              | Fix the comment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| C8  | Both converters set `display_name` / `avatar_url` to `None`, so every host would re-derive them from room members.                                                                                                                                                                                                                                                                                                                                      | The session records each `m.room.member` profile (whether or not the roster condition is enforced) and stamps it on members at projection time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| C9  | `ElementCallCompat::StickyEvents` models the 2025 Element Call sticky dialect (`member: {user_id, device_id, id}`, flat `rtc_transports`, `versions`, legacy key message). No deployment uses it: sticky-event calls have not shipped.                                                                                                                                                                                                                  | **Done.** Removed: `own_membership/compat_2025.rs`, the 2025 block in `session/convert/msc4143.rs` and its dispatch arm, the `StickyEvents` variants of `ElementCallCompat` / `FfiElementCallCompat`, and their tests and acceptance tests; `outbound_event_type` / `build_content` keep two arms (`Off`, `StateEvents`). Element Call then maps `Matrix_2_0 → Off`: spec MSC4143 sticky events with slots (which Element Call opens, C1) and the spec key message.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| C10 | `MediaKeyState` has `holds_our_key`, `have_their_key` and `rejection`, so a tile learns about an unsigned sender only when `require_cross_signed_sender` is on (the key is discarded, `rejection: NotCrossSigned`). With the check off the verdict is dropped on accept and the tile cannot show an unverified sender.                                                                                                                                  | **Done.** The inbound key store keeps the MSC4153 verdict of the accepted key per member and exposes it as `FfiMediaKeyState.sender_cross_signed: Option<bool>` (`None` when the host could not tell). Element Call runs with the check off (§5.8) and wants to show the state on the tile until it is turned on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| C11 | No way to change `application["m.call.intent"]` while joined; Element Call flips it between `audio` and `video` when the camera is toggled (`updateCallIntent`).                                                                                                                                                                                                                                                                                        | `update_application(intent)` on the own-membership manager, facade and FFI: while connected the membership is re-published at once on the refresh path (a failure retries like a refresh); during a join the join event carries it; refused with `NotJoined` otherwise.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| C12 | Homeserver connectivity lived only in Element Call's driver; the crate could not tell a dead homeserver from a quiet one, and a participation's status said nothing about it.                                                                                                                                                                                                                                                                           | **Done.** `ConnectivityDriver` (`is_homeserver_connected`, `subscribe_connectivity`) joins the `MatrixDriver` sum; the FFI adds `ConnectivitySink`, the two callback methods and `FfiParticipationManager.is_homeserver_connected()`; the facade pump consumes the stream and reports `Impairment::HomeserverUnreachable { since_ts }` (Critical, sorted first) in every non-disconnected status until the driver reports the homeserver back. The web-test-app mock and js-sdk driver implement it. A matrix-rust-sdk adapter implements the same two methods later.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| C13 | `session()` moved (seed done, slot opened by somebody else) without any listener firing, so a host's `session$` stayed stale until a membership or status change happened to refresh it. Found by the real-backend check.                                                                                                                                                                                                                               | **Done.** `SessionListener` / `set_session_listener` on the FFI manager (`on_session_change` on the facade), fired publish-on-change from `refresh_outputs`; `RtcParticipationManager.session$` is fed from it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| C14 | The crate logs through the `log` facade (104 call sites) but installed no logger, so in wasm every line was dropped: seeding, joins, delegation fallbacks and key rotation left no trace in a rageshake.                                                                                                                                                                                                                                                | **Done (2026-09-16).** `LogSink` foreign trait (`log(level, target, message)`), `FfiLogLevel`, and `set_log_sink(sink, max_level)`, which installs a `log::Log` forwarding to the sink (a host that already installed a Rust logger keeps it). Element Call installs `matrixRtcLogSink` under `[matrix-rtc]` on the js-sdk root logger from `initMatrixRtcSdk()` at debug; the web-test-app installs a console sink (warn in tests).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+
+No crate work is deferred: `update_application` is C11.
+
+---
+
+## 4. Target architecture
+
+```text
+host (SPA · widget · sdk · a third-party page)
+  ├─ RtcMatrixDriver             = the crate's MatrixDriverCallback, verbatim
+  │                                (events, to-device, tokens, sinks, connectivity)
+  └─ ElementCallMatrixClientDriver = RoomDriver + TimelineDriver + ProfileDriver
+                                     + MediaDriver + capabilities
+        │
+        ▼  component/index.tsx  <ElementCall rtcDriver clientDriver …/>
+  ┌─ MatrixDriverProvider (src/driver/MatrixDriverContext.tsx) ─────────────┐
+  │  CallView owns one RtcParticipationManager for lobby → call → ended               │
+  │  RtcParticipationManager (src/state/rtc/RtcParticipationManager.ts)                          │
+  │    FfiMatrixDriver(driver) → FfiParticipationManager(room, slot, me, cfg)│
+  │    memberships$ · connections$ · keyChanges$ · status$ · session$        │
+  │    ownMemberId$ · ownMembership$ · ownTransportIdentity$                 │
+  │    join(intent, params) · leave(reason)                                  │
+  │        │                                                                 │
+  │        ▼                                                                 │
+  │  createCallViewModel$(scope, callParticipation, roomInfo, mediaDevices, …)   │
+  │    ConnectionManager  ← connections$ (wsUrl + jwt; no OpenID in EC)      │
+  │    RemoteMembers      ← memberships$ (transportIdentity ↔ LK participant)│
+  │    MatrixKeyProvider  ← keyChanges$ (memberId → transportIdentity)        │
+  │    LocalMember        ← status$, ownMembership; join/leave → participation│
+  │    MemberMetadata     ← driver.room members                              │
+  │    Notifications      ← driver.timeline + memberships$                   │
+  │  React: Lobby / InCall / Settings / Avatar / Reactions                   │
+  │    read the driver via useMatrixDriver(), never a client                 │
+  └──────────────────────────────────────────────────────────────────────────┘
+```
+
+### 4.1 The two drivers (host-facing, framework-neutral)
+
+Two files, two objects. `src/driver/RtcMatrixDriver.ts` is one line: the
+crate's `MatrixDriverCallback`, re-exported. Everything MatrixRTC, including
+homeserver connectivity (C12), goes through it and is consumed by the crate.
+`src/driver/ElementCallMatrixClientDriver.ts` is what a call needs beyond
+MatrixRTC. Plain TypeScript: async methods and
+`subscribeX(listener) → unsubscribe` pairs, mirroring the crate's sink style.
+No RxJS crosses this boundary; Element Call wraps subscriptions into
+`Behavior`s internally (`src/driver/observe.ts`).
+
+```ts
+export interface ElementCallMatrixClientDriver
+  extends RoomDriver, TimelineDriver, ProfileDriver, MediaDriver {
+  readonly userId: string;
+  readonly deviceId: string;
+  /** The room this driver is bound to (one driver per room, as in the crate). */
+  readonly roomId: string;
+  getMatrixClientFeatures(): Promise<MatrixClientFeatures>;
+  /** Free-form diagnostics for rageshakes (crypto version, sync state, …). */
+  getDiagnostics?(): Promise<Record<string, string>>;
+}
+export interface MatrixClientFeatures {
+  stickyEvents: boolean;
+  /** The host's events carry decryption metadata (false on a widget client). */
+  verifiedEventOrigins: boolean;
+  /** The host can evaluate MSC4153 cross-signing of senders. */
+  crossSigningVerdicts: boolean;
+}
+
+// src/driver/RtcMatrixDriver.ts
+export type RtcMatrixDriver = MatrixDriverCallback;
+
+export interface RoomInfo {
+  name: string;
+  canonicalAlias: string | null;
+  avatarUrl: string | null;
+  joinRule: string | null;
+  encrypted: boolean;
+}
+export interface RoomMemberProfile {
+  userId: string;
+  displayName: string | null;
+  avatarUrl: string | null;
+  membership: "join" | "invite";
+}
+export interface RoomDriver {
+  getRoomInfo(): RoomInfo;
+  subscribeRoomInfo(listener: (info: RoomInfo) => void): () => void;
+  getRoomMembers(): RoomMemberProfile[];
+  subscribeRoomMembers(
+    listener: (members: RoomMemberProfile[]) => void,
+  ): () => void;
+}
+
+export interface TimelineEvent {
+  eventId: string;
+  type: string;
+  sender: string;
+  content: Record<string, unknown>;
+  originServerTs: number;
+  redacts?: string;
+}
+export interface TimelineDriver {
+  sendRoomEvent(
+    eventType: string,
+    content: unknown,
+  ): Promise<{ eventId: string }>;
+  redactEvent(eventId: string): Promise<void>;
+  /** Decrypted live room events (not sticky), incl. redactions; no local echoes. */
+  subscribeTimeline(listener: (event: TimelineEvent) => void): () => void;
+  /** Events already known that relate to `eventId` (hand-raise catch-up). */
+  getRelatedEvents(
+    eventId: string,
+    relType: string,
+    eventType: string,
+  ): TimelineEvent[];
+}
+
+export interface OwnProfile {
+  displayName: string | null;
+  avatarUrl: string | null;
+}
+export interface ProfileDriver {
+  getOwnProfile(): OwnProfile;
+  subscribeOwnProfile(listener: (profile: OwnProfile) => void): () => void;
+  /** Absent when the host does not allow profile changes. */
+  setDisplayName?(name: string): Promise<void>;
+  setAvatar?(file: Blob): Promise<void>;
+}
+
+export interface MediaDriver {
+  /** An `<img>`-usable URL for an mxc thumbnail (may be a blob: URL), or null. */
+  thumbnailUrl(
+    mxcUrl: string,
+    width: number,
+    height: number,
+    resizeMethod: "crop" | "scale",
+  ): Promise<string | null>;
+}
+```
+
+The client driver is a union of capability slices, the way the crate splits
+its own driver; the RTC driver is the crate's contract untouched, so a host
+with a crate-side adapter (matrix-rust-sdk) implements nothing extra for
+MatrixRTC.
+
+### 4.2 `RtcParticipationManager` (Element Call's RxJS view of the manager)
+
+Naming: _participation_ is the crate's FFI concept (`FfiParticipationManager`,
+`FfiParticipationConfig`); `RtcParticipationManager` is Element Call's RxJS wrapper
+over it.
+
+`src/state/rtc/RtcParticipationManager.ts`, a class taking the scope in its constructor:
+
+```ts
+new RtcParticipationManager(scope, driver, {
+  slotId: "m.call#ROOM", compat, manageMediaKeys, requireCrossSignedSender,
+  useKeyDelayMs, transportFallbackUrl?, logger })
+  memberships$: Behavior<Epoch<FfiMembership[]>>   // Joined only; LeftWithKeys filtered (v1)
+  connections$: Behavior<FfiConnectionWithMembers[]>
+  keyChanges$:  Observable<FfiMediaKey>             // one changed key per emission
+  keyMap$:      Behavior<FfiMediaKey[]>
+  status$:      Behavior<FfiStatus>
+  session$:     Behavior<FfiSessionSnapshot>
+  ownMemberId$: Behavior<string | null>
+  ownTransportIdentity$: Behavior<string | null>
+  ownMembership$: Behavior<FfiMembership | null>
+  join(intent: FfiTransportIntent, params: FfiJoinParams): Promise<void>
+  leave(code?: string, reason?: string): Promise<void>
+```
+
+- Wraps `new FfiMatrixDriver(driver)` and `new FfiParticipationManager(...)`;
+  `uniffiDestroy()` on scope end (leave first unless `Disconnected`).
+- `transportFallbackUrl` decorates `getRtcTransports`: when the host's call
+  **throws or returns no LiveKit transport**, answer with
+  `Config.get().livekit.livekit_service_url` (today's precedence,
+  `RtcTransportAutoDiscovery.ts:72-94`).
+- Lives at `CallView` level (the lobby reads memberships for the participant
+  count, auto-mute threshold and notification decision, `CallView.tsx:164-413`;
+  `useReactionsSender` needs the own membership). `join()` after `leave()` on
+  one manager is supported and mints a fresh member id.
+- Behaviors are seeded from the getters and updated by the listeners.
+
+### 4.3 `createCallViewModel$` after the change
+
+```ts
+createCallViewModel$(
+  scope,
+  participation,
+  roomInfo,
+  mediaDevices,
+  muteStates,
+  options,
+  handsRaised$,
+  reactions$,
+  trackProcessorState$,
+);
+// roomInfo: { roomId, userId, deviceId, members$: Behavior<RoomMemberProfile[]>,
+//             homeserverConnected$: Behavior<boolean>, timeline: TimelineDriver }
+```
+
+| Today                                                               | After                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createMemberships$(scope, rtcSession)`                             | `callParticipation.memberships$`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `membershipsAndTransports$` (`getTransport(oldest)`)                | `membership.connections[]` (service urls)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `createLocalTransport$` + `RtcTransportAutoDiscovery` + `openIDSFU` | deleted; `join(Publish(custom url or bare))`; own transport = `ownMembership.member.publishedTransports[0]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `Connection.start()` fetching a JWT                                 | `Connection` takes `{ wsUrl, jwt, expiresAtTs }` from `connections$`, keyed by `serviceUrl`, holds `token$`; a refreshed token is used on the next full (re)connect; `expiresAtTs` logged on connect; `livekitAlias` decoded from the JWT stays                                                                                                                                                                                                                                                                                                                             |
+| `createRemoteMatrixLivekitMembers$` on `rtcBackendIdentity`         | matches `membership.transportIdentity`; key = `member.memberId`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `MatrixKeyProvider.setRTCSession`                                   | `MatrixKeyProvider.attach(participation)`: `keyChanges$` × `memberships$` × `ownTransportIdentity$` → `onSetEncryptionKey(material, identity, index)`; keys whose member has no identity yet are held per member id and replayed                                                                                                                                                                                                                                                                                                                                            |
+| `enterRTCSession` (`joinRTCSession(...)`)                           | `callParticipation.join(intent, joinParamsFromConfig(...), { encrypted: roomInfo.encrypted, canOpen: roomInfo.canOpenSlot })` in the same `scope.reconcile`: opens the room's slot first when none is open (power level permitting, otherwise `NoOpenSlotError`), then joins; cleanup calls `callParticipation.leave()`                                                                                                                                                                                                                                                     |
+| `createHomeserverConnected$`                                        | `status$` alone: `Impairment::HomeserverUnreachable` (C12) = disconnected; `Connected` with `keepAlive` `Armed`/`Delegated`/`Unavailable` = connected; `RestartFailing`/`Expired` = reconnecting (**behaviour change**: local media pauses in that window, today it does not). Outside a participation, `RtcParticipationManager.homeserverConnected$` from the manager's getter                                                                                                                                                                                            |
+| `delayId$` + JWT-service delegation                                 | gone from Element Call. `FfiJoinParams.delegateDelayedLeave` is always `true`; the crate tries the CS API, then the authorisation service's token endpoint (with `delay_id`, `delay_timeout`, `delay_cs_api_url`), then falls back to its own restarts (C5). `config.matrix_rtc_session.delegated_delayed_leave.delay_ms` becomes `FfiJoinParams.delegatedDelayMs` (default 1 h)                                                                                                                                                                                            |
+| `createMatrixMemberMetadata$(scope, matrixRoom)`                    | tiles read `member.displayName` / `avatarUrl` from the crate; disambiguation runs over the call's members; `roomInfo.members$` remains only for the ringing name and the name-tag threshold                                                                                                                                                                                                                                                                                                                                                                                 |
+| `createSentCallNotification$` / `createReceivedDecline$`            | `CallNotificationLifecycle`: after **our own membership echo** (`ownMembership$` non-null) and when no other member was in the session before our join, send `m.rtc.notification` (wire `org.matrix.msc4075.rtc.notification`) via `driver.sendRoomEvent` with the fields js-sdk sends today (`m.mentions`, `notification_type`, `sender_ts`, `lifetime` 90 s, `m.call.intent`, `m.relates_to: m.reference → own membership event id`, `MatrixRTCSession.ts:725-756`); decline from `driver.subscribeTimeline` on both `org.matrix.msc4310.rtc.decline` and `m.rtc.decline` |
+| `updateCallIntent` on camera toggle                                 | `callParticipation.updateApplication(videoEnabled ? "video" : "audio")` (C11); Element X's room-header intent keeps following the camera                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `createKeyRotationSuppressed$` + `key_rotation_participant_limit`   | dropped (the crate has no participant limit; the indicator has no equivalent)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `rtcSession.statistics` (PostHog)                                   | counts of `keyChanges$` (sent = own member id, received = others)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `MembershipManagerError` → `StickyEventsRequiredError`              | `status$` `Disconnected{cause: JoinFailed{error: Driver/Unsupported}}` → `StickyEventsRequiredError`; `NoTransport` → `MatrixRTCTransportMissingError`; `ManagerStopped`/`SlotClosed` → `ConnectionLostError`                                                                                                                                                                                                                                                                                                                                                               |
+| `impairments`                                                       | fed into the inert `src/state/ServiceInterruptionsViewModel.ts` (S6)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+
+Join parameters (`joinParamsFromConfig`, from `Config.get().matrix_rtc_session`):
+`stickyDurationMs = BigInt(Math.min(membership_event_expiry_ms ?? 4 h, 1 h))`
+(js-sdk caps sticky at 1 h, the crate clamps to 1 h; the config default is
+undefined today); `keepAliveTimeoutMs = BigInt(delayed_leave.delay_ms)`;
+`degradedLifetimeMs = undefined`; `applicationType = "m.call"`;
+`intent = options.callIntent`. Config keys that stop having an effect and are
+documented as such in `docs/`: `delayed_leave.restart_ms`,
+`restart_timeout_ms`, `network_error_retry_ms`,
+`key_rotation_participant_limit`, `delegated_delayed_leave.*` (the crate arms
+1 h when delegating). `wait_for_key_rotation_ms` maps to
+`FfiParticipationConfig.useKeyDelayMs`.
+
+Compat: `MatrixRTCMode.Compatibility → StateEvents`, `Matrix_2_0 → Off` (spec
+MSC4143: sticky member events, slots, the spec key message), in
+`compatForMode`.
+
+### 4.4 React tree
+
+- `src/driver/MatrixDriverContext.tsx`: `MatrixDriverProvider` holding both
+  drivers, `useRtcMatrixDriver()` / `useClientDriver()`; replaces every
+  `useClient()`/`useClientState()` under `CallView`. `ClientContext` stays for the shell.
+- `CallView` props: `{ driver, isPasswordlessUser, confineToRoom, preload, skipLobby }`.
+  It creates the `RtcParticipationManager` (scope tied to its mount) and hands it to
+  `LobbyView`, `ActiveCall`, `useReactionsSender`. `MatrixInfo` comes from
+  `driver.getRoomInfo()` / `driver.getOwnProfile()`.
+- `InCallView`'s own id becomes `${driver.userId}:${driver.deviceId}`.
+- `Avatar` → `driver.thumbnailUrl` (host bridge `downloadMedia` first).
+- `useProfile(client)` → `useOwnProfile()`; `ProfileSettingsTab` hides editing
+  when `setDisplayName` is absent.
+- `ReactionsReader(scope, participation, driver)`, `useReactionsSender` over
+  `TimelineDriver`. Relation target stays the **current own membership event
+  id** (`member.eventId`, C4) — protocol status quo; the reader keys raised
+  hands by `memberId` and re-resolves the event id on re-send instead of
+  dropping the hand.
+- `useRoomEncryptionSystem` reads `getRoomInfo().encrypted`.
+- `submit-rageshake`: `useMatrixDriver()` for ids and `getDiagnostics?()`;
+  rageshake requests via `subscribeTimeline`.
+- `DeveloperSettingsTab`: sticky probe → `getMatrixClientFeatures()`; custom LiveKit
+  URL validation → `driver.getLivekitToken(...)`.
+- `window.rtcSession` debug handle → `window.matrixRtc = { participation }`.
+
+### 4.5 Hosts
+
+- **Component**: `ElementCallProps.rtcDriver: RtcMatrixDriver` and
+  `clientDriver: ElementCallMatrixClientDriver`; `roomId` stays as an
+  **optional** prop for one release and must equal `clientDriver.roomId` when given
+  (assertion), then goes. `initializeElementCall(config, { matrixRtcWasm? })`
+  awaits `initMatrixRtcSdk()`. Externals shrink to `react*`, `livekit-client`,
+  `matrix-js-sdk/lib/logger`. `JsSdkRtcMatrixDriver` and `JsSdkElementCallMatrixClientDriver` are
+  exported from a second entry `@element-hq/element-call-component/matrix-js-sdk` (needs
+  `lib.fileName` as a function and a new `exports` key); only that entry has
+  `matrix-js-sdk` as a peer.
+- **SPA / widget**: `useLoadGroupCall` returns the `Room`; `RoomPage` memoises
+  the two js-sdk drivers and renders `<CallView rtcDriver clientDriver>`. The
+  widget capability list in `src/widget.ts` grows by: send and receive state
+  `m.rtc.slot` and `org.matrix.msc4143.rtc.slot` (opening the slot), `m.room.avatar`,
+  `m.room.canonical_alias`, `m.room.join_rules`; send/receive to-device
+  `org.matrix.msc4143.rtc.encryption_key` and `m.rtc.encryption_key`
+  (alongside `io.element.call.encryption_keys`); events `m.rtc.decline`.
+- **`sdk/main.ts`**: builds the driver from the widget client, a
+  `RtcParticipationManager`, and waits on `status$` instead of `JoinStateChanged`.
+- **`component/dev` harness**: the two js-sdk drivers per pane.
+
+### 4.6 The js-sdk drivers — two classes, two clients each
+
+`src/driver/jsSdk/JsSdkRtcMatrixDriver.ts` (the crate seam, a port of the
+draft's `jsSdkDriver.ts`, connectivity from `ClientEvent.Sync`) and
+`JsSdkElementCallMatrixClientDriver.ts` (the §4.1 slices), both written so
+that they work on a full `MatrixClient`
+**and** on js-sdk's `RoomWidgetClient` (`node_modules/matrix-js-sdk/src/embedded.ts`).
+Differences from the draft, all required by the widget client:
+
+- to-device inbound: listen on `ClientEvent.ToDeviceEvent` (the widget client
+  never emits `ReceivedToDeviceMessage`, `embedded.ts:788-802`); on a full
+  client use `ReceivedToDeviceMessage` for the `encryptionInfo`.
+- to-device outbound: always `encryptAndSendToDevice` (works without a crypto
+  backend on the widget client, `embedded.ts:598-612`; plain `sendToDevice`
+  there is **unencrypted**, `:614-619`).
+- transports: `client._unstable_getRTCTransports()` (the widget override,
+  `embedded.ts:641-646`), never a raw `http.authedRequest`; `.well-known`
+  fallback only on a full client.
+- event origins: on a full client from decryption metadata (as the draft); on
+  a widget client events arrive decrypted without metadata, so the driver
+  reports `Encrypted{ senderDeviceId: content.member.device_id }` for member
+  events and `Encrypted{ senderDeviceId: content.device_id }` for key
+  events, i.e. the _claimed_ trust level js-sdk applies today
+  (`ToDeviceKeyTransport.ts:133-140`). `getMatrixClientFeatures().verifiedEventOrigins`
+  says which.
+- cross-signing verdict: `undefined` on a widget client
+  (`crossSigningVerdicts: false`); Element Call then forces
+  `requireCrossSignedSender = false`.
+- delegation: two primitives and no policy. `delegateDelayedLeaveViaHomeserver`
+  is one `authedRequest` on a full client and `Unsupported` on a widget
+  client; `getLivekitToken` appends `delay_id`, `delay_timeout` and
+  `delay_cs_api_url` (`client.baseUrl`) when the request carries a
+  delegation. The crate decides when to call which (C5). Element Call carries no
+  delegation probe or policy.
+- sticky listener attached after `startClient()` resolves (the widget room
+  only exists then, `embedded.ts:326`).
+- `getLivekitToken` reuses today's request shapes (`slot_id: "m.call#ROOM"`,
+  legacy `/sfu/get`), errors mapped to `RtcError` incl. `M_LIMIT_EXCEEDED →
+RateLimited`, 403 → `Rejected`, 404/`M_UNRECOGNIZED` → `Unsupported`.
+
+---
+
+## 5. Decisions and assumptions
+
+1. **The SDK is an npm package.** `@element-hq/matrix-rtc` (the draft's
+   `web-test-app/`, built by `npm-web-bindings.yml`: uniffi bindings, the
+   wasm-bindgen glue, a `wasm-opt`'d ~760 KB wasm, `.d.ts`, and `@ubjs/core`
+   as its own dependency) is a devDependency, aliased in `package.json` to
+   `@billcarsonfr/matrix-rtc@next` while it is published from the fork, so
+   the imports already say `@element-hq/matrix-rtc`. It lives on the GitHub
+   Packages registry: `.npmrc` maps the scope, a `read:packages` token goes
+   in `~/.npmrc` (CI: the `MATRIX_RTC_NPM_TOKEN` secret). **The GitHub
+   Packages registry is a stop-gap** for the phase in which the crate's API
+   moves with every push; once the SDK is ready for consumers beyond Element
+   Call it belongs on npmjs.com as `@element-hq/matrix-rtc`, which drops the
+   alias, `.npmrc`, the CI secret and every token requirement
+   (`docs/matrix_rtc_sdk.md`). `src/matrix-rtc-sdk/`
+   keeps only the loader (`initMatrixRtcSdk`: package `initAsync` + our log
+   sink, wasm via `@element-hq/matrix-rtc/wasm?url`) and the curated
+   re-exports. _History:_ until 2026-09-16 the bindings were vendored under
+   `src/matrix-rtc-sdk/generated/` by `scripts/sync-matrix-rtc-sdk.sh`; local
+   crate work now goes through `pnpm links:on` (`docs/linking.md`).
+2. **Wasm loading.** Verified: Vite 8 library mode inlines `?url` and
+   `new URL(…, import.meta.url)` assets as base64 regardless of
+   `assetsInlineLimit`; `?url&no-inline` emits a file. App builds use `?url`;
+   the component build uses `?url&no-inline` plus an `exports` entry for
+   `./dist/assets/*`, and `initializeElementCall(config, { matrixRtcWasm })`
+   lets a host point elsewhere. Wasm boot is **lazy** everywhere: in the app
+   `useRtcParticipationManager` awaits `initMatrixRtcSdk()` before constructing
+   the participation (so the js-sdk path never fetches it, §5.15), not the
+   `Initializer`; vitest reads the file from disk and only suites that need
+   it call `initMatrixRtcSdk()`, never in
+   `src/vitest.setup.ts`; Storybook boots it in `.storybook/preview.tsx`
+   `beforeAll`. Suites using `vi.useFakeTimers` never share a file with
+   real-wasm tests (pumps sleep on `setTimeout`).
+3. **Own identity via the driver.** `userId`/`deviceId` are properties of the
+   driver, not props.
+4. **One driver per room**, as in the crate.
+5. **`matrix-js-sdk/lib/logger` stays** behind `src/utils/logger.ts`.
+6. **`updateCallIntent` stays**, through the crate's `update_application` (C11).
+7. **Reactions relate to the current own membership event id** (status quo);
+   reader keys by `memberId`. Alternatives (stable join event id, or
+   `memberId` as relation target) are protocol changes left to the user.
+8. **MSC4153 default off** (`requireCrossSignedSender = false`) for every
+   host, confirmed: js-sdk performs no such check today, and a passwordless
+   SPA peer would otherwise be inaudible to everyone. The intent is to turn
+   it on; the default carries a TODO (`src/state/rtc/joinParams.ts`), and C10
+   puts the sender's verdict on the tile so the UI can show it meanwhile.
+9. **Delegation is the crate's alone.** Element Call always asks for it; the
+   crate tries the CS API, then the authorisation service's token endpoint,
+   then its own restarts, and arms the long delegated leave only once
+   delegation is confirmed (C5, done). Element Call keeps no probe and no
+   delegation code; `delegated_delayed_leave.delay_ms` feeds
+   `FfiJoinParams.delegatedDelayMs`.
+10. **Widget trust model:** origins synthesised from claimed device ids equal
+    today's js-sdk trust level; the crate records them as
+    `DeviceAttribution::Verified` because it cannot tell. Documented in the
+    driver; a `Claimed` attribution flag on the sink is a follow-up crate ask.
+11. **Scratch files** go to `agent-workspace/oxidation/`; this plan lives at
+    the repo root because it was asked for by name.
+12. **Branch** `toger5/oxidation`, one commit per slice.
+13. **Compatibility mode has no slot.** Under `StateEvents` the crate projects
+    the session from the MSC3401 state events alone and requires the legacy
+    slot id `""` (`LEGACY_SLOT_ID` in `src/state/rtc/slot.ts`,
+    `slotIdForCompat`); `RtcParticipationManager` picks it from the config and skips
+    the slot check and the slot open. Found by the real-backend check: with
+    `m.call#ROOM` the crate saw its own legacy membership as a candidate but
+    never projected it. Element Call's own rooms already let every member send
+    the legacy member state event (`state_default: 0`); a plain room does not,
+    which the backend test reproduces.
+14. **Member events in encrypted rooms are Megolm-encrypted** by matrix-js-sdk
+    (sticky events are timeline events; the SDK exempts only reactions and
+    redactions), as they are with the js-sdk MatrixRTC code today. The driver
+    decrypts them on the way in; the sticky marker (`msc4354_sticky`) stays in
+    the clear. To cross-check against Element X before relying on it.
+15. **The two view models stay switchable for one release.** A developer
+    setting, `callViewModelImplementation` (`"matrix-js-sdk"` |
+    `"matrix-rtc"`, `src/settings/settings.ts`, next to `matrixRTCMode`),
+    picks between `createJsClientCallViewModel$` and the driver-based
+    `createCallViewModel$` in the same build. Like `matrixRTCMode` it is
+    shown in the Developer Settings tab, sampled when the call is joined
+    (switching mid-call needs a rejoin), and a deployment can pin it through
+    `config.json` (`call_view_model_implementation`), which overrides the
+    user's choice and greys the control out. The default is
+    `"matrix-js-sdk"` when the setting lands (S4a) and flips to
+    `"matrix-rtc"` once the S5 gate is green; S6 removes the setting together
+    with the js-sdk path. The point is that a broken call can be compared
+    against the old path in the same session, and that Playwright can run
+    both paths from one build. Everything the js-sdk path needs (the client,
+    the `MatrixRTCSession`, `ReactionsReader` over the session) therefore
+    stays reachable from `CallView` until S6, and the `RtcParticipationManager` is
+    created only when the crate path is selected, so neither path pays for
+    the other.
+
+---
+
+## 6. Work breakdown
+
+Each slice is independently green (`pnpm lint && pnpm test:unit` at least).
+
+### S0a — crate changes ☑ (in `MatrixSdkArchitectureDraft`)
+
+C2–C12 from §3 (C1 reverted), each with a Rust unit test; acceptance tests in
+`web-test-app/test/`: a slot-less room refuses joins until `openSlot`, in every dialect;
+`FfiParticipationConfig` with `manageMediaKeys: false` exchanges no keys;
+no `StickyEvents` variant left anywhere (C9); `member.eventId` present;
+delegation tries the homeserver first, then the token endpoint with the delay fields, and keeps the short leave armed until one succeeds;
+`ownTransportIdentity()` equals the joined membership's `transportIdentity`.
+Gate: `cargo test --features uniffi`, `cargo clippy --all-targets --features uniffi -- -D warnings`,
+`npm run ubrn:web && npm test`.
+
+### S0b — SDK intake ☑
+
+- ~~`scripts/sync-matrix-rtc-sdk.sh`, `src/matrix-rtc-sdk/generated/**`~~
+  (replaced by the `@element-hq/matrix-rtc` package on 2026-09-16, §5.1),
+  `src/matrix-rtc-sdk/index.ts` (loader + curated re-exports),
+  `src/matrix-rtc-sdk/index.test.ts` (boot, one join round-trip against the
+  TS mock driver).
+- `package.json` (~~`@ubjs/core`~~ now `@element-hq/matrix-rtc`; the
+  `generated/**` carve-outs in `knip.ts`, `.oxlintrc.json`, `.oxfmtrc.json`,
+  `vitest.config.ts` and `.gitattributes` went with the vendored files),
+  `vite.config.ts` (nothing needed for `?url`; verified `vite-plugin-wasm`
+  ignores it), `tsconfig.json` untouched thanks to the `.d.ts`.
+- Gate: `pnpm lint && pnpm format:check && pnpm test:unit`.
+
+### S1a — driver interface, mock driver ☑
+
+- `src/driver/RtcMatrixDriver.ts`, `src/driver/ElementCallMatrixClientDriver.ts`,
+  `src/driver/observe.ts`, `MockRtcMatrixDriver.ts` (port of
+  `web-test-app/src/mockDriver.ts`) and `MockElementCallMatrixClientDriver.ts`
+  (in-memory room info, members, timeline, profile), with a test each.
+- `knip.ts` `ignore` for `src/driver/**` until consumed, with the reason.
+
+### S1b — `JsSdkMatrixDriver` ☑
+
+- `src/driver/jsSdk/JsSdkRtcMatrixDriver.ts` and
+  `JsSdkElementCallMatrixClientDriver.ts` (§4.6) + tests against **two**
+  fakes: a `MatrixClient`-shaped one (`mockMatrixRoom`) and a
+  `RoomWidgetClient`-shaped one (`ToDeviceEvent`, no crypto,
+  `_unstable_getRTCTransports`, sticky updates after `startClient`).
+  Asserts request shapes of `_unstable_sendStickyEvent`,
+  `_unstable_sendStickyDelayedEvent`, `_unstable_updateDelayedEvent`,
+  `encryptAndSendToDevice`, `/get_token` body with and without the delegation fields, `delegateDelayedLeaveViaHomeserver` on both clients,
+  sink emission and origin synthesis, room-info/member updates.
+
+### S2 — `RtcParticipationManager` ☑
+
+- `src/state/rtc/RtcParticipationManager.ts`, `joinParams.ts`, `transportIntent.ts`,
+  `errors.ts` (cause → `ElementCallError`).
+- `RtcParticipationManager.test.ts` through the real wasm + `MockMatrixDriver`:
+  memberships follow a remote join/leave; `LeftWithKeys` filtered; join →
+  `Connected`; `connections$` carries the token; `keyChanges$` fires for a
+  peer key; `ownTransportIdentity$` set before the echo; leave →
+  `Disconnected{LeftByHost}`; join → leave → join; scope end destroys the
+  manager; fallback transport when the host throws or advertises none.
+
+### S3 — view model, four slices ☑ (side by side with the js-sdk view model)
+
+- **Shape (2026-09-15):** the existing factory is renamed
+  `createJsClientCallViewModel$` and the new `createCallViewModel$(scope,
+participation, clientDriver, …)` sits next to it; both build a
+  `CallViewModelCore` and hand it to the shared `assembleCallViewModel`, so
+  the layout/tile half is one piece of code and the two Matrix sides can be
+  reviewed side by side. `MatrixLivekitMember.membership$` is a neutral
+  `CallMember` (`userId`, `deviceId`, `memberId`, `rtcBackendIdentity`) that
+  js-sdk's `CallMembership` satisfies; `CallNotificationLifecycle` takes a
+  neutral `DeclineEvent`. Nothing js-sdk is deleted yet (that is S6).
+- **S3a** `remoteMembers/ParticipationConnections.ts`: one `Connection` per
+  service URL in `participation.connections$`, started with the crate's
+  token; a refreshed token keeps the connection (used on the next
+  (re)connect). `Connection`/`ECConnectionFactory` accept a `null` client.
+  Test fakes live in `src/utils/test-participation.ts`
+  (`FakeParticipation`, `fakeMembership`, `fakeConnection`, `fakeMediaKey`).
+- **S3b** `remoteMembers/ParticipationMembers.ts` (remote members matched by
+  `transportIdentity`, keyed by `memberId`; `callMemberOf`) and
+  `e2ee/participationKeyProvider.ts` (`keyMap$` × `memberships$` ×
+  `ownTransportIdentity$` → `onSetEncryptionKey`, once per (member, index,
+  identity); a key that arrives before the identity waits for the roster).
+- **S3c** `localMember/LocalMedia.ts` is the LiveKit half extracted from
+  `LocalMember.ts` (publisher, tracks, screen share, upstream pausing, host
+  notify) and shared; `localMember/ParticipationLocalMember.ts` joins and
+  leaves through the participation (slot policy from `roomInfo`, custom
+  LiveKit URL as a `Publish` intent, `updateApplication` on camera toggle),
+  derives connected / reconnecting / `probablyLeft` from `status$`
+  (`HomeserverUnreachable` → "sync", `RestartFailing`/`Expired` →
+  "probablyLeft") and the fatal error from `errorForStatus`. Deletions
+  (`LocalTransport.ts`, `RtcTransportAutoDiscovery.ts`,
+  `HomeserverConnected.ts`, `openIDSFU.ts`, `enterRTCSession`) wait for S6.
+- **S3d** `ParticipationCallNotification.ts` sends `org.matrix.msc4075.rtc.notification`
+  after our own echo when nobody was in the session before us (resets on
+  leave) and reads declines from the `TimelineDriver`;
+  `remoteMembers/ParticipationMemberMetadata.ts` adapts the client driver's
+  roster to `RoomMemberMap` so `createMatrixMemberMetadata$` and the ringing
+  name work unchanged. Still open: `ReactionsReader` on `participation` +
+  `TimelineDriver` (the new factory takes the hands/reactions observables
+  as inputs like the old one; S4b), `keyRotationSuppressed$` is `constant(false)`,
+  and the js-sdk test kit stays until S6. Tests:
+  `CallViewModel.participation.test.ts` (real wasm, mock drivers, mocked
+  LiveKit: join → connection → own tile → peer → leave; transport-missing →
+  `fatalError$`), plus one file per module.
+
+### S4 — React tree, two slices ☑ (2026-09-16)
+
+- **S4a-0, the switch (§5.15) ☑:** `CallViewModelImplementation` enum,
+  `callViewModelImplementation` setting (`src/settings/settings.ts`),
+  `call_view_model_implementation` pin (`ConfigOptions.ts`, validated in
+  `Config.ts`), the radio group in `DeveloperSettingsTab.tsx`, the
+  implementation logged at join and sent as `call_view_model_implementation`
+  in rageshakes, `effectiveCallViewModelImplementation()` in
+  `src/state/rtc/implementation.ts`. `CallView` samples it once per mount;
+  with `matrix-rtc` and no drivers it warns and lets matrix-js-sdk carry the
+  call. Still open from this item: the Playwright helper and the second CI
+  run.
+- **S4a done so far:** `MatrixDriverProvider` / `useMatrixDrivers()`
+  (`src/driver/MatrixDriverContext.tsx`), provided by the component from its
+  props and by `RoomPage` through `useJsSdkDrivers(client, room)`;
+  `useRtcParticipationManager(drivers, config)` owned by `CallView`, created only
+  when the crate path is selected; `ActiveCall` takes `participation` and
+  builds either view model; the lobby's member count, the big-call auto-mute
+  and the error boundary's "were we joined" read from whichever side carries
+  the call; `window.matrixRtc = { participation }` next to `window.rtcSession`.
+- (The original S4a-0 description follows for reference.) `callViewModelImplementation` setting and
+  `config.json` pin (`ConfigOptions.ts`, validated at load like
+  `matrix_rtc_mode`); a radio group in `DeveloperSettingsTab.tsx` beside the
+  MatrixRTC mode; `ActiveCall` reads the sampled value and calls either
+  factory — for `"matrix-rtc"` it takes the drivers from the
+  `MatrixDriverProvider` and the `RtcParticipationManager` from `CallView`, for
+  `"matrix-js-sdk"` it keeps `rtcSession`/`matrixRoom` as today. The chosen
+  implementation is logged at join and added to the rageshake fields so a
+  report says which path it came from. Playwright gets a helper that sets
+  the setting (local storage) before the call so every call spec can run
+  under both values; CI runs the suite twice until the default flips.
+  Lands first in S4a, before anything else in the tree moves, so that every
+  later S4 change is verifiable against the old path.
+- **S4a** views/hooks/settings on the driver: `CallView.tsx` (owns
+  `RtcParticipationManager` when the crate path is selected), `InCallView.tsx`, `LobbyView.tsx`, `CallEndedView.tsx`,
+  `VideoPreview.tsx`, `useRoomInfo()` (replaces `useRoomName/Avatar/JoinRule/State`),
+  `InviteModal.tsx`, `Avatar.tsx`, `useOwnProfile.ts`, `ProfileSettingsTab.tsx`,
+  `SettingsModal.tsx`, `DeveloperSettingsTab.tsx`, `submit-rageshake.ts`,
+  `analytics/PosthogEvents.ts`, `controls.ts`, and a
+  first `CallView.stories.tsx` (lobby, in call, ended) driven by
+  `MockMatrixDriver`.
+- **S4b ☑ (2026-09-16):** `ReactionsSenderProvider` takes `ownIdentifier`,
+  `ownMembershipEventId` and a `ReactionsTimeline` (`jsSdkReactionsTimeline`
+  over a client, or the client driver); `ParticipationReactionsReader`
+  (`src/reactions/`) reads hands and reactions from the participation and
+  the timeline driver, keyed by the member's media id
+  (`memberMediaId`, `src/state/rtc/mediaId.ts`), and re-resolves a hand on a
+  re-sent membership instead of dropping it blindly. Notifications went
+  through the driver in S3d. Tests: `ParticipationReactionsReader.test.ts`,
+  `useRtcParticipationManager.test.tsx`, three `CallView.test.tsx` cases for the
+  switch.
+- **S4a views on the drivers (2026-09-16):** `CallView` now requires the
+  drivers (`useMatrixDrivers()`; both hosts provide them) and reads the
+  room through `useRoomInfo()` (`src/room/useRoomInfo.ts`; `useRoomAvatar`,
+  `useJoinRule`, `useRoomState` deleted, `useRoomName` stays for `RoomPage`),
+  our own profile through `useOwnProfile()` (`src/profile/useOwnProfile.ts`)
+  and the encryption system through `useEncryptionSystemFor(roomId,
+roomInfo.encrypted)` (`useRoomEncryptionSystem` keeps the client for the
+  home page). `MatrixInfo` is built from those. `InviteModal` takes
+  `roomId`/`roomName`/`e2eeSystem`; `CallEndedView` lost its `client` prop;
+  `Avatar` resolves thumbnails through `clientDriver.thumbnailUrl` when
+  drivers are provided (host `downloadMedia` first, client fallback for the
+  shell); rageshakes carry the driver's `getDiagnostics()` as `driver_*`
+  fields and the crate's `matrix_rtc_snapshot`.
+- **The component is client-free (2026-09-16):** `CallView`'s `client` and
+  `rtcSession` are optional; without them the crate carries the call
+  whatever the setting says (`useMatrixRtc = setting || no session`), and
+  every js-sdk-only piece (the `MembershipManagerError` listener, the room
+  sanity check, `ReactionsReader`, `mediaKeyStatisticsOf`) is skipped.
+  `ActiveCall`/`InCallView` take `roomId` instead of `matrixRoom`, and
+  `client`/`rtcSession` optionally. `ProfileSettingsTab` edits through the
+  client driver's optional `setDisplayName`/`setAvatar(file | null)` and
+  shows read-only fields without them; `DeveloperSettingsTab` reads the
+  sticky probe from `getMatrixClientFeatures()`, the crypto version from
+  `getDiagnostics()` and validates a custom LiveKit URL through
+  `rtcDriver.getLivekitToken` when there is no client; the rageshake request
+  event goes through the client driver's timeline; reactions are supported
+  unless a client state forbids them. `ElementCall` renders no
+  `ClientProvider` and no shim — it hands its two drivers down and nothing
+  below asks for a client; `initializeElementCall(config, { matrixRtcWasm })`
+  can preload the wasm. `PosthogEvents.eventCallEnded.track` takes
+  `MediaKeyStatistics` (from the session on the js-sdk path, zero on the
+  crate path until the crate counts). `useTypedEventEmitter` and the js-sdk
+  client driver's public `client`/`room` are gone. **Consequence:** the
+  component and its dev harness (`ElementCallClientBased`) now run every
+  call on the crate.
+- **Banner dropped (2026-09-17):** the disconnected banner, its
+  `useHomeserverConnected` hook and the client state's `disconnected` flag
+  are gone. The local membership already carries the connection state, so
+  the reconnecting overlay covers the in-call case where it matters; in the
+  lobby the banner added little. `HomeserverConnected` in
+  `state/CallViewModel/localMember/` remains the one consumer of
+  `rtcDriver.isHomeserverConnected()` / `subscribeConnectivity` and of
+  `sync_disconnect_grace_period_ms`. The mock RTC driver keeps several
+  connectivity sinks (the crate's and the UI's).
+- **S4 closed (2026-09-16):** `CallView.stories.tsx` (Lobby with a peer,
+  NoTransport as the error path, Ended) over the mock drivers, no client;
+  `.storybook/preview.tsx` initialises the config; the Storybook vitest
+  project passes. The Playwright switch is `CALL_VIEW_MODEL_IMPLEMENTATION`
+  read by `playwright.config.ts` into `use.storageState` (the developer
+  setting in local storage for every context), and the CI Playwright job is
+  a matrix over both implementations (`matrix-rtc` non-blocking until it
+  has passed once). `RtcParticipationManager.mediaKeyStatistics()` counts sent
+  and received keys and their age from the crate's key changes for the
+  ended-call event. Found on the way: `CallView` rendered `ActiveCall`
+  before the participation existed (wasm loads on first use) — it now waits;
+  and `onLeft` had gained the member count as a dependency, which rebuilt
+  the view model on every roster change on both paths — read through
+  `useLatest` now. `create-call.spec.ts` passes in Chromium on both
+  implementations with two view model creations each (StrictMode): the
+  crate path's first full call in a browser.
+
+### S5 — hosts ☐ (component props done 2026-09-15)
+
+- **Done:** `ElementCallProps` takes `rtcDriver` + `clientDriver` (`roomId`
+  optional, asserted equal); `ElementCallClientBased` takes `client` +
+  `roomId` and builds the two js-sdk drivers (the dev harness uses it); the
+  driver types and the js-sdk drivers are exported from the component index.
+  **Temporary:** until S4 the tree under `CallView` still runs on the
+  client, so `ElementCall` requires the client driver to be
+  `JsSdkElementCallMatrixClientDriver` (its `client`/`room` are public for
+  this) and throws for any other driver.
+- `component/matrix-js-sdk.ts`, `component/package.json`
+  (`exports`, peers), `vite-component.config.ts` (two entries, `fileName`
+  function, externals shrink, `?url&no-inline`), `component/tsconfig.build.json`,
+  `component/dev/Harness.tsx`, `README.md`.
+- `src/room/useLoadGroupCall.ts`, `RoomPage.tsx`, `src/widget.ts`
+  (capabilities, §4.5), `sdk/main.ts`, `playwright/spa-helpers.ts`
+  (delegation route helper), `docs/` config notes.
+- Gate: all four builds; Playwright standalone + widget + component against
+  `pnpm backend`; a widget media-key round trip and `reconnect.spec.ts`
+  re-checked under the new delegation path.
+
+### S6 — fence and cleanup ☐
+
+- `src/utils/logger.ts`; local `CallIntent` type for the six `RTCCallIntent`
+  users; `useLocalStorage.ts` on a local emitter; oxlint
+  `no-restricted-imports` scoped to the call tree (allow-list: `src/home`,
+  `src/auth`, `src/utils/spa.ts`, `src/utils/matrix.ts`, `src/driver/jsSdk/**`,
+  `src/ClientContext.tsx`, `src/widget.ts`, `src/initializer.tsx`,
+  `src/IndexedDBWorker.ts`, `src/room/KnockLobbyView.tsx`, `src/settings/rageshake.ts`)
+  banning `matrix-js-sdk` except `matrix-js-sdk/lib/logger`.
+- `ServiceInterruptionsViewModel` fed from `status$.impairments`.
+- `callViewModelImplementation` setting, its `config.json` pin and the
+  Developer Settings control removed with `createJsClientCallViewModel$`
+  (§5.15); Playwright runs the suite once again.
+- `docs/agents/architecture.md`, `docs/matrix_rtc_modes.md` updated;
+  `src/@types/matrix-js-sdk.d.ts` removed if nothing merges into js-sdk types.
+
+---
+
+## 7. Risks and mitigations
+
+| Risk                                                                           | Mitigation                                                                                 |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| A user without the power level to open a slot, in a room that never had a call | `NoOpenSlotError` names the remedy; a room admin opens the slot by starting the first call |
+| A client on the removed sticky dialect (none is deployed)                      | Not supported: `Off` and `StateEvents` are the only dialects (C9)                          |
+| Component bundle size / wasm delivery                                          | `?url&no-inline` + `exports` wildcard + `matrixRtcWasm` override; verified in S0b and S5   |
+| Token refresh vs LiveKit reconnect                                             | `Connection.token$`; full reconnect uses the latest token; `expiresAtTs` logged            |
+| Own identity before the echo                                                   | C6 export; JWT `sub` only as a logged cross-check                                          |
+| Keys before identity                                                           | key provider buffers per member id and replays                                             |
+| Widget mode regressions (origins, to-device event, capabilities)               | S1b tests against a `RoomWidgetClient` fake; S5 widget e2e adds a media-key round trip     |
+| Delegation fails after the long leave was armed                                | Arm-after-confirm (C5): the short leave stays armed until delegation is confirmed          |
+| Behaviour drift in keep-alive (6 s vs 4 s restarts) and dropped config keys    | documented in `docs/`                                                                      |
+| Test time: wasm per file                                                       | lazy boot in the suites that need it only                                                  |
+
+---
+
+## 8. Verification matrix
+
+| Check                                                                        | S0a | S0b | S1  | S2  | S3  | S4  | S5  | S6  |
+| ---------------------------------------------------------------------------- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `cargo test/clippy`, `web-test-app` suites                                   | ●   |     |     |     |     |     |     |     |
+| `pnpm lint` + `format:check`                                                 |     | ●   | ●   | ●   | ●   | ●   | ●   | ●   |
+| `pnpm test:unit`                                                             |     | ●   | ●   | ●   | ●   | ●   | ●   | ●   |
+| `pnpm test:storybook`                                                        |     |     |     |     |     | ●   | ●   | ●   |
+| four builds                                                                  |     | ●   |     |     |     |     | ●   | ●   |
+| Playwright standalone + widget + component                                   |     |     |     |     |     |     | ●   | ●   |
+| Manual: two harness panes hear each other, E2EE, hand raise, reaction, leave |     |     |     |     |     |     | ●   |     |
+| Real backend (`RtcParticipationManager.backend.test.ts`, opt-in, both modes) |     |     |     | ●   |     |     | ●   |     |
+
+---
+
+## 9. Open questions for the user (answered by the assumptions in §5 until told otherwise)
+
+1. Slot semantics, **answered**: no slot means no call; Element Call opens the
+   slot on the first call in a room, power level permitting.
+2. Delegation, **answered**: CS API endpoint first, then Element Call's
+   OpenID → JWT → scheduled-event path, all inside the crate and invisible to
+   Element Call (C5).
+3. Media-key type under the sticky compat, **answered**: there are no deployed
+   sticky-event clients, so the compat mode is removed (C9) and the question
+   with it.
+4. MSC4153, **answered**: off everywhere for now, with a TODO to turn it on
+   and C10 so tiles show unverified senders in the meantime.
+5. Reactions relation target: current membership event id (taken), stable join
+   event id, or `memberId`?
+6. Committing the 6.5 MB wasm (taken) vs a build-time fetch.
+7. `roomId` prop: optional for one release (taken) vs removed outright.
+8. `updateCallIntent`, **answered**: added to the crate as `update_application`
+   (C11); Element Call keeps the behaviour.
+
+---
+
+## 10. Review log
+
+Independent review findings incorporated in this revision: slot enforcement
+blocker (C1); delegation protocol and 1 h arm (C5, §5.9; later redefined as crate-only with arm-after-confirm); `StickyEvents` key
+type interop (C3, then made moot by removing the mode, C9); MSC4153 default (§5.8); widget-client differences for the
+js-sdk drivers (§4.6) and missing widget capabilities (§4.5); own identity
+export (C6); `RtcParticipationManager` lifetime at `CallView` (§4.2); notification
+timing and content (§4.3); reactions/event-id semantics (§5.7); config mapping
+defaults and dropped keys (§4.3); `bigint`/`ArrayBuffer` types; inventory
+gaps (§2); knip `ignore` vs `ignoreFiles`, oxlint/oxfmt ignores, `.d.ts` for
+the glue, lazy wasm boot, Storybook `beforeAll`; slice re-cut (S0a/b, S1a/b,
+S3a–d, S4a/b, temporary `CallView` shim); `sdk/main.ts` status wiring and the
+Playwright delegation helper.
+
+**Real-backend check (2026-09-15), `pnpm backend` + `src/state/rtc/RtcParticipationManager.backend.test.ts`**
+(`MATRIX_RTC_BACKEND=1 NODE_TLS_REJECT_UNAUTHORIZED=0 pnpm vitest run --project unit src/state/rtc/RtcParticipationManager.backend.test.ts`;
+two registered users with rust crypto in an encrypted room, `matrix_2_0` and
+`compatibility`): passes end to end — transport discovery from
+`/rtc/transports`, slot open + echo, sticky member event with `msc4354_sticky`,
+delayed leave, delegation via the homeserver, roster with display names,
+Olm-encrypted media keys both ways with `senderCrossSigned`, leave cancelling
+the delayed event, and `HomeserverUnreachable` raised and cleared across a
+simulated network outage. Fixed on the way: MSC4195 `member` claims and the
+homeserver route's body (`url`, `delay_timeout`; C5), the missing session
+listener (C13), the legacy slot id under compatibility mode (§5.13). Noted:
+`vite-plugin-node-polyfills` shadows `process`, so tests read the environment
+through `node:process`; Synapse develop already proxies the MSC4195 endpoint
+to lk-jwt-service; member events are Megolm-encrypted in encrypted rooms
+(§5.14). Not verified here: the widget host path (Element Web) and the
+authorisation-service route (the homeserver route is taken first on this
+stack; it is covered by unit tests only).
+
+**S3 (2026-09-15):** the driver-based `createCallViewModel$` landed next to
+the renamed `createJsClientCallViewModel$` (shared `assembleCallViewModel`,
+neutral `CallMember`/`DeclineEvent`, `LocalMedia.ts` extracted); component
+props moved to the two drivers with `ElementCallClientBased` on top. Gates:
+`pnpm lint`, `format:check`, `test:unit` (803), `i18n:check`,
+`build:component` green. Open from this slice: reactions reader on the
+participation (S4b), the `?url&no-inline` wasm asset for the component build
+(the wasm is loaded lazily and inlined into the component bundle today), and
+the S6 deletions.
+
+**S4 (2026-09-16):** the implementation switch (§5.15) is in with its
+config pin, developer control and rageshake field; `CallView` owns a
+`RtcParticipationManager` when the crate path is selected and `ActiveCall` builds
+the matching view model; the reactions reader and sender have participation
+and driver counterparts. Both paths run in the same build. Gates: `pnpm
+lint`, `format:check`, `i18n:check`, `test:unit` (815), `build:component`
+green. Not verified: a real call on the crate path through the UI (the
+`pnpm backend` check covers the view model's Matrix side; the browser run is
+the S5 gate).
+
+**Logging (2026-09-16):** C14 — the crate's log lines reach the host through
+a `LogSink`; Element Call routes them to its rageshake logger under
+`[matrix-rtc]`, the web-test-app to the console. Verified by a unit test that
+sees the crate's "session created" line through the sink.
+
+**S4 views (2026-09-16):** room info, own profile, encryption system,
+avatars, the invite and ended views and the rageshake fields read the
+drivers; `CallView` requires drivers. Three room hooks deleted. Gates:
+`pnpm lint`, `format:check`, `test:unit` (819), `build:component` green.
+
+**Client-free component (2026-09-16):** `CallView` and everything under it
+run without a matrix-js-sdk client on the crate path; the component passes
+only its drivers. Gates: `pnpm lint`, `format:check`, `test:unit` (819),
+`build:component` green. Not yet done: a browser run of the component on
+the crate path (the dev harness now is that run).
+
+**S4 done (2026-09-16):** stories, Playwright switch and CI matrix, key
+statistics. `create-call.spec.ts` green on `matrix-js-sdk` and `matrix-rtc`
+in Chromium against the dev server; the rest of the suite under
+`matrix-rtc` is the S5 gate. Gates: `pnpm lint`, `format:check`,
+`test:unit` (822), `test:storybook` (28), `build:component` green.

knip.ts

@@ -9,7 +9,13 @@ import { type KnipConfig } from "knip";
 
 export default {
   vite: {
-    config: ["vite.config.ts", "vite-embedded.config.ts", "vite-sdk.config.ts"],
+    config: [
+      "vite.config.ts",
+      "vite-embedded.config.ts",
+      "vite-sdk.config.ts",
+      "vite-component.config.ts",
+      "vite-component-dev.config.ts",
+    ],
   },
   entry: ["src/main.tsx", "eslint/index.js", "i18next.config.ts"],
   ignoreBinaries: [
@@ -20,6 +26,12 @@ export default {
     // This is a shell built-in.
     "printf",
   ],
+  ignore: [
+    // The host-facing driver seam, landed ahead of its consumers (the
+    // `CallParticipation` layer and the hosts, see element-call-oxidation-plan.md)
+    "src/driver/**",
+    "src/state/rtc/**",
+  ],
   ignoreFiles: [
     "scripts/.pnpmfile.cjs",
     // Deliberately added prior to any component or business logic

locales/en/app.json

@@ -58,6 +58,18 @@
   },
   "developer_mode": {
     "always_show_iphone_earpiece": "Show iPhone earpiece option on all platforms",
+    "callViewModelImplementation": {
+      "forced": "Your deployment pins the call implementation.",
+      "matrix_js_sdk": {
+        "description": "The MatrixRTC session of matrix-js-sdk carries the call, as before",
+        "label": "matrix-js-sdk"
+      },
+      "matrix_rtc": {
+        "description": "The Rust matrix-rtc crate carries the call through the host's drivers",
+        "label": "matrix-rtc (Rust)"
+      },
+      "title": "Call implementation"
+    },
     "crypto_version": "Crypto version: {{version}}",
     "custom_livekit_url": {
       "current_url": "Currently set to: ",
@@ -90,7 +102,6 @@
     "show_connection_stats": "Show connection statistics",
     "url_params": "URL parameters"
   },
-  "disconnected_banner": "Connectivity to the server has been lost.",
   "error": {
     "call_is_not_supported": "Call is not supported",
     "call_not_found": "Call not found",
@@ -110,6 +121,8 @@
     "membership_manager": "Membership Manager Error",
     "membership_manager_description": "The Membership Manager had to shut down. This is caused by many consecutive failed network requests.",
     "no_matrix_2_authorization_service": "The authorization service for your media server (SFU) is out of date.",
+    "no_open_slot": "No call to join here",
+    "no_open_slot_description": "Nobody has started a call in this room yet, and you do not have permission to start one. Ask a room admin to start the call, or to allow you to start calls.",
     "open_elsewhere": "Opened in another tab",
     "open_elsewhere_description": "{{brand}} has been opened in another tab. If that doesn't sound right, try reloading the page.",
     "peer_connection_timeout": "Connection timeout",

package.json

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

playwright.config.ts

@@ -11,12 +11,40 @@ import { join } from "path";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { COMPONENT_HARNESS_URL } from "./playwright/component/harness.ts";
+
 const baseURL = process.env.USE_DOCKER
   ? "http://localhost:8080"
   : "https://localhost:3000";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+/**
+ * Which MatrixRTC implementation carries the calls under test, `matrix-js-sdk`
+ * or `matrix-rtc` (see `CallViewModelImplementation` in
+ * src/config/ConfigOptions.ts). Unset, Element Call's default applies. Set,
+ * every browser context starts with the developer setting in local storage,
+ * so the whole suite runs on that implementation.
+ */
+const callViewModelImplementation = process.env.CALL_VIEW_MODEL_IMPLEMENTATION;
+const storageState =
+  callViewModelImplementation === undefined
+    ? undefined
+    : {
+        cookies: [],
+        origins: [
+          {
+            origin: baseURL,
+            localStorage: [
+              {
+                name: "matrix-setting-call-view-model-implementation",
+                value: JSON.stringify(callViewModelImplementation),
+              },
+            ],
+          },
+        ],
+      };
+
 // Needed by the synapse admin API called in fixtures
 process.env.NODE_EXTRA_CA_CERTS = join(
   __dirname,
@@ -42,6 +70,7 @@ export default defineConfig({
   use: {
     /* Base URL to use in actions like `await page.goto('/')`. */
     baseURL,
+    storageState,
 
     /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
     trace: "on-first-retry",
@@ -84,6 +113,11 @@ export default defineConfig({
             // enumerateDevices work on CI runners without real hardware.
             "media.navigator.streams.fake": true,
             "media.navigator.permission.disabled": true,
+            // Vite serves HTTPS over HTTP/2, and Firefox intermittently stalls
+            // on Node's HTTP/2 server with a page that never finishes loading
+            // (one run in five or so, locally). Every server in the suite
+            // still speaks HTTP/1.1, so nothing is lost by insisting on it.
+            "network.http.http2.enabled": false,
           },
         },
       },
@@ -115,14 +149,29 @@ export default defineConfig({
   ],
 
   /* Run your local dev server before starting the tests */
-  webServer: {
-    command: "./scripts/playwright-webserver-command.sh",
-    url: baseURL,
-    reuseExistingServer: !process.env.CI,
-    ignoreHTTPSErrors: true,
-    gracefulShutdown: {
-      signal: "SIGTERM",
-      timeout: 500,
+  webServer: [
+    {
+      command: "./scripts/playwright-webserver-command.sh",
+      url: baseURL,
+      reuseExistingServer: !process.env.CI,
+      ignoreHTTPSErrors: true,
+      gracefulShutdown: {
+        signal: "SIGTERM",
+        timeout: 500,
+      },
     },
-  },
+    {
+      // The harness that embeds Element Call as a component. Always a Vite dev
+      // server, whether or not the app itself is being served from Docker,
+      // since there is nothing to build: it is a development page only.
+      command: "pnpm dev:component",
+      url: COMPONENT_HARNESS_URL,
+      reuseExistingServer: !process.env.CI,
+      ignoreHTTPSErrors: true,
+      gracefulShutdown: {
+        signal: "SIGTERM",
+        timeout: 500,
+      },
+    },
+  ],
 });

playwright/component/component-call.spec.ts

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

playwright/component/harness.ts

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

playwright/reconnect.spec.ts

@@ -7,6 +7,8 @@ Please see LICENSE in the repository root for full details.
 
 import { expect, test } from "@playwright/test";
 
+import { SpaHelpers } from "./spa-helpers";
+
 // Skip test for Firefox, due to page.keyboard.press("Tab") not reliable on headless mode
 test.skip(
   ({ browserName }) => browserName === "firefox",
@@ -17,6 +19,12 @@ test("can only interact with header and footer while reconnecting", async ({
   page,
 }) => {
   await page.goto("/");
+
+  // The reconnecting state is entered via the probablyLeft timer, which
+  // mirrors the delayed leave event's timeout. With delegation that timeout
+  // is one hour, putting it out of reach of the clock fast-forward below.
+  // Keep the leave client-managed so its short timeout applies.
+  await SpaHelpers.disableLeaveDelegation(page);
   await page.getByTestId("home_callName").click();
   await page.getByTestId("home_callName").fill("Test call");
   await page.getByTestId("home_displayName").click();

playwright/spa-call-sticky.spec.ts

@@ -19,6 +19,7 @@ async function setupTwoUserSpaCall(
   browser: Browser,
   page: Page,
   browserName: string,
+  opts: { disableGuestLeaveDelegation?: boolean } = {},
 ): Promise<{ guestPage: Page }> {
   test.skip(
     browserName === "firefox",
@@ -52,6 +53,9 @@ async function setupTwoUserSpaCall(
 
   await guestPage.goto("/");
 
+  if (opts.disableGuestLeaveDelegation)
+    await SpaHelpers.disableLeaveDelegation(guestPage);
+
   let pevaraHasSentStickyEvent = false;
 
   const pevaraResolver = Promise.withResolvers<void>();
@@ -102,7 +106,13 @@ test("One to One rejoin after improper leave does not crash EC", async ({
   page,
   browserName,
 }) => {
-  const { guestPage } = await setupTwoUserSpaCall(browser, page, browserName);
+  // With delegation, the backend sends the guest's delayed leave event within
+  // moments of the improper leave, so the stale membership this test needs
+  // would be cleaned up before the rejoin. Keep the guest's leave
+  // client-managed so the stale membership lingers.
+  const { guestPage } = await setupTwoUserSpaCall(browser, page, browserName, {
+    disableGuestLeaveDelegation: true,
+  });
 
   await SpaHelpers.expectVideoTilesCount(page, 2);
   await SpaHelpers.expectVideoTilesCount(guestPage, 2);

playwright/spa-helpers.ts

@@ -111,6 +111,24 @@ async function setRtcModeFromSettings(
   await page.getByTestId("modal_close").click();
 }
 
+/**
+ * Makes the delayed-leave delegation support probes fail so that the client
+ * manages its delayed leave event itself instead of delegating it to the
+ * backend.
+ *
+ * Must be installed before the page joins a call.
+ */
+async function disableLeaveDelegation(page: Page): Promise<void> {
+  // Covers both the transport probe (<livekit_service_url>/delegate_delayed_leave)
+  // and the homeserver probe (MSC4195, .../rtc/livekit/delegate_delayed_leave).
+  await page.route("**/delegate_delayed_leave", async (route) =>
+    route.fulfill({
+      status: 404,
+      headers: { "Access-Control-Allow-Origin": "*" },
+    }),
+  );
+}
+
 /**
  * Expect a certain number of video tiles to be present and visible.
  */
@@ -133,5 +151,6 @@ export const SpaHelpers = {
   createCall,
   getCallInviteLink,
   joinCallFromInviteLink,
+  disableLeaveDelegation,
   expectVideoTilesCount,
 };

pnpm-workspace.yaml

@@ -1,4 +1,10 @@
+supportedArchitectures:
+  os: [current, linux]
+  cpu: [current, arm64]
+  libc: [current, glibc]
 minimumReleaseAgeExclude:
+  # The MatrixRTC SDK is consumed as `next` pre-releases straight from its CI
+  - "@billcarsonfr/matrix-rtc"
   - "@vector-im/compound-design-tokens"
   - "@vector-im/compound-web"
   - matrix-js-sdk

scripts/check-component-externals.mjs

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

sdk/main.ts

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

src/App.tsx

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

src/AppBar.module.css

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

src/Avatar.test.tsx

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

src/Avatar.tsx

@@ -14,10 +14,10 @@ import {
 } from "react";
 import { Avatar as CompoundAvatar } from "@vector-im/compound-web";
 import { type MatrixClient } from "matrix-js-sdk";
-import { type WidgetApi } from "matrix-widget-api";
 
 import { useClientState } from "./ClientContext";
-import { widget } from "./widget";
+import { useOptionalMatrixDrivers } from "./driver/MatrixDriverContext";
+import { useHostBridge } from "./HostBridge";
 
 export enum Size {
   XS = "xs",
@@ -76,6 +76,10 @@ export const Avatar: FC<Props> = ({
   ...props
 }) => {
   const clientState = useClientState();
+  const hostBridge = useHostBridge();
+  // Under a call the host's client driver resolves media; the shell outside
+  // a call still has only the client.
+  const drivers = useOptionalMatrixDrivers();
 
   const sizePx = useMemo(
     () =>
@@ -87,23 +91,38 @@ export const Avatar: FC<Props> = ({
 
   const [avatarUrl, setAvatarUrl] = useState<string | undefined>(undefined);
 
-  // In theory, a change in `clientState` or `sizePx` could run extra getAvatarFromWidgetAPI calls, but in practice they should be stable long before this code runs.
+  // In theory, a change in `clientState` or `sizePx` could run extra media
+  // downloads, but in practice they should be stable long before this code runs.
   useEffect(() => {
     if (!src) {
       setAvatarUrl(undefined);
       return;
     }
 
-    let blob: Promise<Blob>;
+    let url: Promise<string | null>;
 
-    if (widget?.api) {
-      blob = getAvatarFromWidgetAPI(widget.api, src);
+    if (hostBridge.downloadMedia) {
+      url = hostBridge
+        .downloadMedia(src)
+        .then((blob) => URL.createObjectURL(blob));
+    } else if (drivers !== null) {
+      const px = Math.floor(sizePx * window.devicePixelRatio);
+      url = drivers.clientDriver.thumbnailUrl(
+        src,
+        px,
+        px,
+        sizePx <= 96 ? "crop" : "scale",
+      );
     } else if (
       clientState?.state === "valid" &&
       clientState.authenticated?.client &&
       sizePx
     ) {
-      blob = getAvatarFromServer(clientState.authenticated.client, src, sizePx);
+      url = getAvatarFromServer(
+        clientState.authenticated.client,
+        src,
+        sizePx,
+      ).then((blob) => URL.createObjectURL(blob));
     } else {
       setAvatarUrl(undefined);
       return;
@@ -111,13 +130,14 @@ export const Avatar: FC<Props> = ({
 
     let objectUrl: string | undefined;
     let stale = false;
-    blob
-      .then((blob) => {
-        if (stale) {
+    url
+      .then((resolved) => {
+        if (stale || resolved === null) {
           return;
         }
-        objectUrl = URL.createObjectURL(blob);
-        setAvatarUrl(objectUrl);
+        // Only what we created (or the driver created for us) is ours to revoke.
+        if (resolved.startsWith("blob:")) objectUrl = resolved;
+        setAvatarUrl(resolved);
       })
       .catch((ex) => {
         if (stale) {
@@ -132,7 +152,7 @@ export const Avatar: FC<Props> = ({
         URL.revokeObjectURL(objectUrl);
       }
     };
-  }, [clientState, src, sizePx]);
+  }, [clientState, hostBridge, drivers, src, sizePx]);
 
   return (
     <CompoundAvatar
@@ -172,24 +192,3 @@ async function getAvatarFromServer(
 
   return blob;
 }
-
-// export for testing
-export async function getAvatarFromWidgetAPI(
-  api: WidgetApi,
-  src: string,
-): Promise<Blob> {
-  const response = await api.downloadFile(src);
-  const file = response.file;
-
-  // element-web sends a Blob, and the MSC4039 is considering changing the spec to strictly Blob, so only handling that
-  if (file instanceof Blob) {
-    return file;
-  } else if (typeof file === "string") {
-    // it is a base64 string
-    const bytes = Uint8Array.from(atob(file), (c) => c.charCodeAt(0));
-    return new Blob([bytes]);
-  }
-  throw new Error(
-    "Downloaded file format is not supported: " + typeof file + "",
-  );
-}

src/ClientContext.test.tsx

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

src/ClientContext.tsx

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

src/DisconnectedBanner.module.css

@@ -1,18 +0,0 @@
-/*
-Copyright 2023, 2024 New Vector Ltd.
-
-SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
-Please see LICENSE in the repository root for full details.
-*/
-
-.banner {
-  position: absolute;
-  padding: 29px;
-  background-color: var(--cpd-color-bg-subtle-primary);
-  vertical-align: middle;
-  font-size: var(--font-size-body);
-  text-align: center;
-  z-index: 1;
-  top: 76px;
-  width: calc(100% - 58px);
-}

src/DisconnectedBanner.tsx

@@ -1,44 +0,0 @@
-/*
-Copyright 2023, 2024 New Vector Ltd.
-
-SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
-Please see LICENSE in the repository root for full details.
-*/
-
-import classNames from "classnames";
-import { type FC, type HTMLAttributes, type ReactNode } from "react";
-import { useTranslation } from "react-i18next";
-
-import styles from "./DisconnectedBanner.module.css";
-import { type ValidClientState, useClientState } from "./ClientContext";
-
-interface Props extends HTMLAttributes<HTMLElement> {
-  children?: ReactNode;
-  className?: string;
-}
-
-export const DisconnectedBanner: FC<Props> = ({
-  children,
-  className,
-  ...rest
-}) => {
-  const { t } = useTranslation();
-  const clientState = useClientState();
-  let shouldShowBanner = false;
-
-  if (clientState?.state === "valid") {
-    const validClientState = clientState as ValidClientState;
-    shouldShowBanner = validClientState.disconnected;
-  }
-
-  return (
-    <>
-      {shouldShowBanner && (
-        <div className={classNames(styles.banner, className)} {...rest}>
-          {children}
-          {t("disconnected_banner")}
-        </div>
-      )}
-    </>
-  );
-};

src/ErrorView.tsx

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

src/FullScreenView.tsx

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

src/Header.module.css

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

src/Header.tsx

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

src/HostBridge.test.ts

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

src/HostBridge.ts

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

src/LeaveToHomeContext.ts

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

src/Modal.module.css

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

src/Modal.tsx

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

src/QrCode.tsx

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

src/RichError.tsx

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

src/RootElementContext.ts

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

src/Toast.tsx

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

src/UrlParams.test.ts

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

src/UrlParams.ts

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

src/analytics/PosthogAnalytics.test.ts

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

src/analytics/PosthogAnalytics.ts

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

src/analytics/PosthogEvents.test.ts

@@ -19,6 +19,7 @@ import { type MatrixRTCSession } from "matrix-js-sdk/lib/matrixrtc";
 
 import { PosthogAnalytics } from "./PosthogAnalytics";
 import {
+  mediaKeyStatisticsOf,
   CallEndedTracker,
   CallReconnectingTracker,
   type CallReconnectingReason,
@@ -67,7 +68,7 @@ describe("CallEnded", () => {
     const tracker = new CallEndedTracker();
     const mockSession = createMockRtcSession();
 
-    tracker.track("test-call-id", 2, false, mockSession);
+    tracker.track("test-call-id", 2, false, mediaKeyStatisticsOf(mockSession));
 
     expect(warnSpy).toHaveBeenCalledWith(
       "[PosthogEvents] Failed to send posthog callEnded event due to missing startTime",
@@ -81,7 +82,7 @@ describe("CallEnded", () => {
 
     tracker.cacheStartCall(new Date(Date.now() - 60000));
     tracker.cacheParticipantCountChanged(5);
-    tracker.track("test-call-id", 3, true, mockSession);
+    tracker.track("test-call-id", 3, true, mediaKeyStatisticsOf(mockSession));
 
     expect(PosthogAnalytics.instance.trackEvent).toHaveBeenCalledWith(
       {
@@ -111,7 +112,7 @@ describe("CallEnded", () => {
     tracker.cacheParticipantCountChanged(3);
     tracker.cacheParticipantCountChanged(7);
     tracker.cacheParticipantCountChanged(2);
-    tracker.track("test-call-id", 1, false, mockSession);
+    tracker.track("test-call-id", 1, false, mediaKeyStatisticsOf(mockSession));
 
     expect(PosthogAnalytics.instance.trackEvent).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -128,7 +129,7 @@ describe("CallEnded", () => {
     });
 
     tracker.cacheStartCall(new Date());
-    tracker.track("test-call-id", 1, false, mockSession);
+    tracker.track("test-call-id", 1, false, mediaKeyStatisticsOf(mockSession));
 
     expect(PosthogAnalytics.instance.trackEvent).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -146,7 +147,7 @@ describe("CallEnded", () => {
     });
 
     tracker.cacheStartCall(new Date());
-    tracker.track("test-call-id", 1, false, mockSession);
+    tracker.track("test-call-id", 1, false, mediaKeyStatisticsOf(mockSession));
 
     expect(PosthogAnalytics.instance.trackEvent).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -161,7 +162,7 @@ describe("CallEnded", () => {
     const mockSession = createMockRtcSession();
 
     tracker.cacheStartCall(new Date());
-    tracker.track("test-call-id", 1, false, mockSession);
+    tracker.track("test-call-id", 1, false, mediaKeyStatisticsOf(mockSession));
 
     expect(PosthogAnalytics.instance.trackEvent).toHaveBeenCalledWith(
       expect.anything(),
@@ -178,7 +179,7 @@ describe("CallEnded", () => {
     tracker.cacheReconnecting("sync");
     tracker.cacheReconnecting("livekit");
     tracker.cacheReconnecting("membership");
-    tracker.track("test-call-id", 1, false, mockSession);
+    tracker.track("test-call-id", 1, false, mediaKeyStatisticsOf(mockSession));
 
     expect(PosthogAnalytics.instance.trackEvent).toHaveBeenCalledWith(
       expect.objectContaining({

src/analytics/PosthogEvents.ts

@@ -15,6 +15,34 @@ import {
   RegistrationType,
 } from "./PosthogAnalytics";
 
+/** How many media keys went out and came in over a call, for the ended event. */
+export interface MediaKeyStatistics {
+  sent: number;
+  received: number;
+  /** Sum of the ages of the received keys, in ms; averaged on send. */
+  receivedTotalAge: number;
+}
+
+/** No key statistics (the Rust crate does not count them yet). */
+export const NO_MEDIA_KEY_STATISTICS: MediaKeyStatistics = {
+  sent: 0,
+  received: 0,
+  receivedTotalAge: 0,
+};
+
+/** {@link MediaKeyStatistics} from a matrix-js-sdk session. */
+export function mediaKeyStatisticsOf(
+  rtcSession: MatrixRTCSession,
+): MediaKeyStatistics {
+  const { counters, totals } = rtcSession.statistics;
+  return {
+    sent: counters.roomEventEncryptionKeysSent,
+    received: counters.roomEventEncryptionKeysReceived,
+    // Only meaningful with received keys; a mocked session may not carry it.
+    receivedTotalAge: totals?.roomEventEncryptionKeysReceivedTotalAge ?? 0,
+  };
+}
+
 interface CallEnded extends IPosthogEvent {
   eventName: "CallEnded";
   // the callId posthog key is essentially a Matrix roomId
@@ -80,7 +108,7 @@ export class CallEndedTracker {
     callId: string,
     callParticipantsNow: number,
     sendInstantly: boolean,
-    rtcSession: MatrixRTCSession,
+    keys: MediaKeyStatistics,
   ): void {
     if (this.cache.startTime) {
       PosthogAnalytics.instance.trackEvent<CallEnded>(
@@ -90,16 +118,10 @@ export class CallEndedTracker {
           callParticipantsMax: this.cache.maxParticipantsCount,
           callParticipantsOnLeave: callParticipantsNow,
           callDuration: (Date.now() - this.cache.startTime.getTime()) / 1000,
-          roomEventEncryptionKeysSent:
-            rtcSession.statistics.counters.roomEventEncryptionKeysSent,
-          roomEventEncryptionKeysReceived:
-            rtcSession.statistics.counters.roomEventEncryptionKeysReceived,
+          roomEventEncryptionKeysSent: keys.sent,
+          roomEventEncryptionKeysReceived: keys.received,
           roomEventEncryptionKeysReceivedAverageAge:
-            rtcSession.statistics.counters.roomEventEncryptionKeysReceived > 0
-              ? rtcSession.statistics.totals
-                  .roomEventEncryptionKeysReceivedTotalAge /
-                rtcSession.statistics.counters.roomEventEncryptionKeysReceived
-              : 0,
+            keys.received > 0 ? keys.receivedTotalAge / keys.received : 0,
           callReconnectingCount: this.cache.reconnectingCount,
           callReconnectingCountSync: this.cache.reconnectingCountByReason.sync,
           callReconnectingCountMembership:

src/auth/useInteractiveRegistration.ts

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

src/auth/useRegisterPasswordlessUser.ts

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

src/base.css

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

src/button/LeaveToHomeLink.tsx

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

src/button/ReactionToggleButton.module.css

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

src/button/ReactionToggleButton.test.tsx

@@ -17,7 +17,10 @@ import { type CallViewModel } from "../state/CallViewModel/CallViewModel";
 import { getBasicCallViewModelEnvironment } from "../utils/test-viewmodel";
 import { alice, local, localRtcMember } from "../utils/test-fixtures";
 import { type MockRTCSession } from "../utils/test";
-import { ReactionsSenderProvider } from "../reactions/useReactionsSender";
+import {
+  jsSdkReactionsTimeline,
+  ReactionsSenderProvider,
+} from "../reactions/useReactionsSender";
 import { initializeWidget } from "../widget";
 initializeWidget();
 vi.mock("livekit-client/e2ee-worker?worker");
@@ -35,7 +38,12 @@ function TestComponent({
     <TooltipProvider>
       <ReactionsSenderProvider
         vm={vm}
-        rtcSession={rtcSession.asMockedSession()}
+        ownIdentifier={localIdent}
+        ownMembershipEventId={localRtcMember.eventId}
+        timeline={jsSdkReactionsTimeline(
+          rtcSession.room.client,
+          rtcSession.room.roomId,
+        )}
       >
         <ReactionToggleButton
           reactionData={{

src/components/CallFooter.module.css

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