diff --git a/.github/workflows/build-element-call.yaml b/.github/workflows/build-element-call.yaml index 908c5055c..1636ecc57 100644 --- a/.github/workflows/build-element-call.yaml +++ b/.github/workflows/build-element-call.yaml @@ -7,7 +7,7 @@ on: type: string package: type: string # This would ideally be a `choice` type, but that isn't supported yet - description: The package type to be built. Must be one of 'full', 'embedded', or 'sdk' + description: The package type to be built. Must be one of 'full', 'embedded', or 'widget-rtc-sdk' required: true build_mode: type: string # This would ideally be a `choice` type, but that isn't supported yet diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 2e24da1e3..fc9e7aba8 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -72,14 +72,12 @@ jobs: SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }} CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} - build_sdk_element_call: - # The 'sdk' package is the CallViewModel bundle that predates the sdk/ - # package (build:sdk:production, sdk-target-based-on-call-view-model/), not - # the package itself. The name is shared with pr-deploy.yaml, which always - # runs from main, so it stays until the bundle's consumers have moved over. + build_widget_rtc_sdk: + # The widget wrapper around the sdk/ package (widget-rtc-sdk/), not the + # package itself. Deployed by pr-deploy.yaml as the pr-widget-rtc-sdk preview. uses: ./.github/workflows/build-element-call.yaml with: - package: sdk + package: widget-rtc-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: diff --git a/.github/workflows/deploy-to-netlify.yaml b/.github/workflows/deploy-to-netlify.yaml index c2bfd51a0..7b97d91ce 100644 --- a/.github/workflows/deploy-to-netlify.yaml +++ b/.github/workflows/deploy-to-netlify.yaml @@ -17,7 +17,7 @@ on: package: required: true type: string - description: Which package to deploy - 'full', 'embedded', 'sdk', or 'storybook' + description: Which package to deploy - 'full', 'embedded', 'widget-rtc-sdk', or 'storybook' artifact_run_id: required: false type: string @@ -64,25 +64,27 @@ jobs: run: curl -s https://raw.githubusercontent.com/element-hq/element-call/main/config/netlify_redirects > webapp/_redirects - name: Add config file - # Not needed for storybook deployments - if: inputs.package != 'storybook' - run: | - if [ "${INPUTS_PACKAGE}" = "full" ]; then - curl -s "https://raw.githubusercontent.com/${INPUTS_PR_HEAD_FULL_NAME}/${INPUTS_PR_HEAD_REF}/config/config_netlify_preview.json" > webapp/config.json - else - curl -s "https://raw.githubusercontent.com/${INPUTS_PR_HEAD_FULL_NAME}/${INPUTS_PR_HEAD_REF}/config/config_netlify_preview_sdk.json" > webapp/config.json - fi + # Only the app reads a config.json beside it. A widget gets everything + # about the homeserver from its host. + if: inputs.package == 'full' + run: curl -s "https://raw.githubusercontent.com/${INPUTS_PR_HEAD_FULL_NAME}/${INPUTS_PR_HEAD_REF}/config/config_netlify_preview.json" > webapp/config.json env: - INPUTS_PACKAGE: ${{ inputs.package }} INPUTS_PR_HEAD_FULL_NAME: ${{ inputs.pr_head_full_name }} INPUTS_PR_HEAD_REF: ${{ inputs.pr_head_ref }} + - name: Add headers file + # A widget page on another origin imports the widget RTC SDK bundle as a + # module, which the browser only allows with CORS + if: inputs.package == 'widget-rtc-sdk' + run: | + printf '/*\n Access-Control-Allow-Origin: *\n' > webapp/_headers + - name: ☁️ Deploy to Netlify id: netlify uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0 with: publish-dir: webapp deploy-message: "Deploy from GitHub Actions" - alias: ${{ inputs.package == 'sdk' && format('pr{0}-sdk', inputs.pr_number) || inputs.package == 'storybook' && format('pr{0}-storybook', inputs.pr_number) || format('pr{0}', inputs.pr_number) }} + alias: ${{ inputs.package == 'widget-rtc-sdk' && format('pr{0}-widget-rtc-sdk', inputs.pr_number) || inputs.package == 'storybook' && format('pr{0}-storybook', inputs.pr_number) || format('pr{0}', inputs.pr_number) }} env: NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }} diff --git a/.github/workflows/pr-deploy.yaml b/.github/workflows/pr-deploy.yaml index ab6ad097c..a733a792c 100644 --- a/.github/workflows/pr-deploy.yaml +++ b/.github/workflows/pr-deploy.yaml @@ -46,7 +46,7 @@ jobs: NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }} - netlify-sdk: + netlify-widget-rtc-sdk: needs: prdetails permissions: deployments: write @@ -57,7 +57,7 @@ jobs: pr_head_full_name: ${{ github.event.workflow_run.head_repository.full_name }} pr_head_ref: ${{ needs.prdetails.outputs.pr_data_json && fromJSON(needs.prdetails.outputs.pr_data_json).head.ref }} deployment_ref: ${{ needs.prdetails.outputs.pr_data_json && fromJSON(needs.prdetails.outputs.pr_data_json).head.sha || github.ref || github.head_ref }} - package: sdk + package: widget-rtc-sdk secrets: ELEMENT_BOT_TOKEN: ${{ secrets.ELEMENT_BOT_TOKEN }} NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} diff --git a/config/config_netlify_preview_sdk.json b/config/config_netlify_preview_sdk.json deleted file mode 100644 index 77d885ea0..000000000 --- a/config/config_netlify_preview_sdk.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "default_server_config": { - "m.homeserver": { - "base_url": "https://call-unstable.ems.host", - "server_name": "call-unstable.ems.host" - } - }, - "ssla": "https://static.element.io/legal/element-software-and-services-license-agreement-uk-1.pdf", - "matrix_rtc_session": { - "membership_event_expiry_ms": 180000000, - "network_error_retry_ms": 100 - } -} diff --git a/docs/agents/architecture.md b/docs/agents/architecture.md index 71a6c8215..84c6c7f0b 100644 --- a/docs/agents/architecture.md +++ b/docs/agents/architecture.md @@ -76,11 +76,11 @@ Code that builds in only one is a bug. Packaged exactly like the component (own pnpm project, run pnpm from the repo root, types from `sdk/tsconfig.build.json`, externals checked by `pnpm lint:externals`). Interface only so far; the design is `sdk-plan.md`. -- `build:sdk-target-based-on-call-view-model` — the SDK demo that predates the - package, one bundle of the `CallViewModel`; entry - `sdk-target-based-on-call-view-model/main.ts`. CI's `sdk` package - (`build:sdk:production` / `build:sdk:development`, the Netlify `-sdk` preview) - is still this bundle, not `build:sdk`. +- `build:widget-rtc-sdk` — a single bundle for widget pages that wraps the + `sdk/` package and the widget API, nothing of `src/`; entry + `widget-rtc-sdk/main.ts`. CI builds it as the `widget-rtc-sdk` package + (`build:widget-rtc-sdk:production` / `:development`) and deploys it as the + `pr-widget-rtc-sdk` Netlify preview. - `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` / diff --git a/knip.ts b/knip.ts index fc3f240e5..1574a4a1a 100644 --- a/knip.ts +++ b/knip.ts @@ -14,7 +14,7 @@ export default { "vite-embedded.config.ts", "vite-sdk.config.ts", "vite-sdk-dev.config.ts", - "vite-sdk-target-based-on-call-view-model.config.ts", + "vite-widget-rtc-sdk.config.ts", "vite-component.config.ts", "vite-component-dev.config.ts", ], diff --git a/package.json b/package.json index 60770e19f..875f958ca 100644 --- a/package.json +++ b/package.json @@ -18,9 +18,9 @@ "build:sdk": "pnpm build:sdk:js && pnpm build:sdk:types", "build:sdk:js": "pnpm build:full --config vite-sdk.config.js", "build:sdk:types": "tsc -p sdk/tsconfig.build.json", - "build:sdk-target-based-on-call-view-model": "pnpm build:full --config vite-sdk-target-based-on-call-view-model.config.js", - "build:sdk:production": "pnpm build:sdk-target-based-on-call-view-model", - "build:sdk:development": "pnpm build:sdk-target-based-on-call-view-model --mode development", + "build:widget-rtc-sdk": "pnpm build:full --config vite-widget-rtc-sdk.config.js", + "build:widget-rtc-sdk:production": "pnpm build:widget-rtc-sdk", + "build:widget-rtc-sdk:development": "pnpm build:widget-rtc-sdk --mode development", "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", diff --git a/sdk-target-based-on-call-view-model/README.md b/sdk-target-based-on-call-view-model/README.md deleted file mode 100644 index 4b7edf30e..000000000 --- a/sdk-target-based-on-call-view-model/README.md +++ /dev/null @@ -1,68 +0,0 @@ -# SDK mode (LEGACY) - -> Superseded by the `sdk/` package (`@element-hq/matrixrtc-sdk`) and its harness in -> `sdk/dev`; see `sdk/SdkArchitecture.md`. This bundle is in production use, so it -> keeps building as a thin layer over that package until its consumers have moved -> to the package directly. It will then be removed. Its members are the package's -> `RTCMember`s now, in place of its own wrapper around the raw membership. - -EC can be build in sdk mode. This will result in a compiled js file that can be imported in very simple webapps. - -It allows to use matrixRTC in combination with livekit without relying on element call. - -This is done by instantiating the call view model and exposing some useful behaviors (observables) and methods. - -This folder contains an example index.html file that showcases the sdk in use (hosted on localhost:8123 with a webserver allowing cors (for example `npx serve -l 81234 --cors`)) as a godot engine HTML export template. - -## Getting started - -To get started run - -``` -pnpm install -pnpm build:sdk-target-based-on-call-view-model -``` - -in the repository root. (`pnpm build:sdk` builds the `sdk/` package instead.) - -CI's `sdk` package (`build:sdk:production`, `build:sdk:development`, the -`build-output-sdk` artifact and the `pr-sdk` Netlify preview) is still this -bundle, not the `sdk/` package, until its consumers have moved over. - -It will create `dist` containing the compiled js file, `matrixrtc-sdk.js`. - -This file needs to be hosted. Locally (via `npx serve -l 81234 --cors`) or on a remote server. - -Now you just need to add the widget to element web via: - -``` -/addwidget http://localhost:3000?widgetId=$matrix_widget_id&userId=$matrix_user_id&deviceId=$org.matrix.msc3819.matrix_device_id&baseUrl=$org.matrix.msc4039.matrix_base_url&roomId=$matrix_room_id -``` - -## Widgets - -The sdk mode is particularly interesting to be used in widgets. In widgets you do not need to pay attention to matrix login/cs api ... -To create a widget see the example `index.html` file in this folder. And add it to EW via: -`/addwidget ` (see **url parameters** for more details on ``) - -### url parameters - -The url parameters are needed to pass initial data to the widget. They will automatically be used -by the matrixRTCSdk to start the postmessage widget api (communication between the client (e.g. Element Web) and the widget) - -``` -widgetId = $matrix_widget_id -userId = $matrix_user_id -deviceId = $org.matrix.msc3819.matrix_device_id -baseUrl = $org.matrix.msc4039.matrix_base_url -``` - -`parentUrl = // will be inserted automatically` - -Full template use as ``: - -``` -http://localhost:3000?widgetId=$matrix_widget_id&userId=$matrix_user_id&deviceId=$org.matrix.msc3819.matrix_device_id&baseUrl=$org.matrix.msc4039.matrix_base_url&roomId=$matrix_room_id -``` - -the `$` prefixed variables will be replaced by EW on widget instantiation. (e.g. `$matrix_user_id` -> `@user:example.com` (url encoding will also be applied automatically by EW) -> `%40user%3Aexample.com`) diff --git a/sdk-target-based-on-call-view-model/main.ts b/sdk-target-based-on-call-view-model/main.ts deleted file mode 100644 index 788f8575c..000000000 --- a/sdk-target-based-on-call-view-model/main.ts +++ /dev/null @@ -1,191 +0,0 @@ -/* -Copyright 2025-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. -*/ - -/** - * LEGACY, in production use - * - * The entrypoint of `pnpm build:sdk-target-based-on-call-view-model`, a - * bundle for widgets that exposes `createMatrixRTCSdk`: join a slot and - * exchange realtime data, with the `@element-hq/matrixrtc-sdk` package and - * Element Call's call view model doing the work underneath. New consumers use - * the package directly; this bundle goes away once the existing ones have. - */ - -import { logger as rootLogger } from "matrix-js-sdk/lib/logger"; -import { EMPTY, filter, map, type Observable, of, switchMap, take } from "rxjs"; -import { - type Behavior, - createRTCSlot, - E2eeType, - type LocalRTCMember, - ObservableScope, - type RemoteRTCMember, - type RTCParticipation, -} from "@element-hq/matrixrtc-sdk"; - -import { - callViewModelOptionsFromParams, - type CallViewModel, - createCallViewModel$, - initialPublishRequests, -} from "../src/state/CallViewModel/CallViewModel"; -import { - captureSettings, - rtcParticipationOptions, - rtcSlotOptions, -} from "../src/room/InCallView"; -import { createWidgetHostBridge } from "../src/HostBridge"; -import { MediaDevices } from "../src/state/MediaDevices"; -import { MuteStates } from "../src/state/MuteStates"; -import { getUrlParams } from "../src/UrlParams"; -import { observeElementSize$ } from "../src/utils/elementSize"; -import { initializeWidget } from "../src/widget"; - -/** The data channel topic this bundle has always used, so that old and new builds talk. */ -const TOPIC = "matrixRTC"; - -export interface MatrixRTCSdk { - /** Joins the slot; `connected$` tracks the progress. A second call does nothing. */ - join: () => void; - leave: () => void; - /** Ends everything. The sdk cannot be restarted; create a new one. */ - stop: () => void; - connected$: Behavior; - /** Our own member, null until our membership has been seen in the room. */ - localMember$: Behavior; - /** The other members of the slot, with the media the participation carries for them. */ - remoteMembers$: Behavior; - /** What other members sent with `sendData`. */ - data$: Observable<{ rtcBackendIdentity: string; data: string }>; - /** Sends to every member on our transport. Rejects while not joined. */ - sendData: (data: unknown) => Promise; - sendRoomMessage: (message: string) => Promise; -} - -export async function createMatrixRTCSdk( - application = "m.call", - id = "", - sticky = false, -): Promise { - const logger = rootLogger.getChild("[MatrixRTCSdk]"); - const scope = new ObservableScope(); - const widget = initializeWidget(application, true); - if (!widget) throw new Error("No widget: this bundle only runs as a widget"); - const client = await widget.client; - const hostBridge = createWidgetHostBridge(widget); - const urlParams = getUrlParams(); - const { roomId, controlledAudioDevices, callIntent } = urlParams; - const room = roomId === null ? null : client.getRoom(roomId); - if (room === null) throw new Error("No room: the url needs a joined roomId"); - - const mediaDevices = new MediaDevices(scope, { - controlledAudioDevices, - callIntent, - }); - const muteStates = new MuteStates( - scope, - mediaDevices, - { audioEnabled: false, videoEnabled: false }, - hostBridge, - ); - const encryptionSystem = { kind: E2eeType.PER_PARTICIPANT } as const; - const capture = captureSettings(); - const slot = createRTCSlot(scope, client, room, { - ...rtcSlotOptions(encryptionSystem), - application, - id, - }); - let vm: CallViewModel | undefined; - const failed = - (what: string) => - (e: unknown): void => - logger.error(what, e); - - const over = ( - pick: (participation: RTCParticipation) => Observable, - fallback: T, - ): Behavior => - scope.behavior( - slot.participation$.pipe( - switchMap((p) => (p === null ? of(fallback) : pick(p))), - ), - ); - - return { - join: (): void => { - if (slot.participation$.value !== null) return; - if (sticky) - widget.api - .setAlwaysOnScreen(true) - .catch(failed("Failed to make the widget sticky")); - const participation = slot.join({ - ...rtcParticipationOptions(urlParams), - publish: initialPublishRequests(muteStates, mediaDevices, capture), - }); - vm = createCallViewModel$( - scope, - participation, - room, - mediaDevices, - muteStates, - { - ...callViewModelOptionsFromParams(urlParams), - encryptionSystem, - capture, - hostBridge, - // The bundle owns its page, so the body is the space it has - windowSize$: scope.behavior(observeElementSize$(document.body)), - }, - of({}), - of({}), - ); - // Once the hang-up has gone through, unstick and ask the host to close us - vm.leave$ - .pipe( - switchMap(() => - participation.state$.pipe( - filter((state) => state.kind === "left"), - take(1), - ), - ), - scope.bind(), - ) - .subscribe(() => { - hostBridge - .setAlwaysOnScreen(false) - .catch(failed("Failed to unstick the widget")) - .then(() => hostBridge.close?.()) - .catch(failed("Failed to ask the host to close")); - }); - }, - leave: (): void => vm?.leave(), - stop: (): void => scope.end(), - connected$: over( - (p) => p.state$.pipe(map((state) => state.kind === "connected")), - false, - ), - localMember$: over((p) => p.localMember$, null), - remoteMembers$: over((p) => p.remoteMembers$, []), - // Attested members only: the SDK has matched the sender - data$: slot.participation$.pipe( - switchMap((p) => p?.data$ ?? EMPTY), - filter(({ topic }) => topic === TOPIC), - map(({ member, text }) => ({ - rtcBackendIdentity: member.rtcBackendIdentity, - data: text, - })), - ), - sendData: async (data): Promise => { - const participation = slot.participation$.value; - if (participation === null) throw new Error("Not joined"); - await participation.sendData(TOPIC, JSON.stringify(data)); - }, - sendRoomMessage: async (message): Promise => { - await client.sendTextMessage(room.roomId, message); - }, - }; -} diff --git a/sdk/README.md b/sdk/README.md index b1e8252ed..9a49bdfa8 100644 --- a/sdk/README.md +++ b/sdk/README.md @@ -5,8 +5,7 @@ it joins a MatrixRTC slot in a Matrix room, writes and watches the memberships, connects to the media transport (LiveKit today), publishes the local media and exposes every member and their tracks as observables. It has no UI. Element Call's own `CallViewModel` is one consumer of it; any host can build a different -view on top. The design is in [`SdkArchitecture.md`](./SdkArchitecture.md), what -moved out of Element Call's `src/` in [`SdkMigration.md`](./SdkMigration.md). +view on top. The design is in [`SdkArchitecture.md`](./SdkArchitecture.md). **Status:** first implementation. `createRTCSlot` and `slot.join()` join the session, connect to the transport, publish the local media and expose every diff --git a/sdk/SdkArchitecture.md b/sdk/SdkArchitecture.md index e4a934de6..aaa0fface 100644 --- a/sdk/SdkArchitecture.md +++ b/sdk/SdkArchitecture.md @@ -10,8 +10,7 @@ interface. Element Call becomes one consumer of it: `CallViewModel` keeps what makes a session a _call_ (ringing, auto-leave, layout, sounds, reactions, settings, the host bridge) and takes everything else from the client. The dependency direction is -therefore `Element Call → sdk`, never the reverse. What moved out of Element -Call's `src/` to get there is listed in [`SdkMigration.md`](./SdkMigration.md). +therefore `Element Call → sdk`, never the reverse. ## The architecture @@ -777,7 +776,6 @@ sdk/ src/utils/ mapScoped, network retry, display names, test helpers dev/ the harness (below) SdkArchitecture.md this document - SdkMigration.md what moved from Element Call's src/ into the SDK ``` The lint rule `element-call/sdk-import-boundary` keeps it that way: nothing under diff --git a/sdk/SdkMigration.md b/sdk/SdkMigration.md deleted file mode 100644 index 92e8640e1..000000000 --- a/sdk/SdkMigration.md +++ /dev/null @@ -1,53 +0,0 @@ -# What moved from `src/` into the SDK - -Element Call's `CallViewModel` used to do everything; now it consumes the SDK and -keeps only what makes a session a call. This is the inventory of what moved out -of `src/` on the way, so that a reader of either side knows where to look. It -names source files, so it ages with the code; the shape they make is in -[`SdkArchitecture.md`](./SdkArchitecture.md). - -Everything in the table is gone from `src/`. Each module came with its tests; -`sdk/src/utils/test.ts` and `test-fixtures.ts` are the subset of Element Call's -test helpers they need. `Behavior`, `ObservableScope`, the observable operators, -`E2eeType`, `EncryptionSystem` and `MatrixRTCMode` are re-exported from the SDK -by their old `src/` paths, so the rest of Element Call did not have to change. - -| Was in `src/` | Is in `sdk/src/` | What changed on the way | -| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `state/Behavior.ts`, `state/ObservableScope.ts`, `utils/observable.ts` | `reactive/` | as is | -| `state/SessionBehaviors.ts` | `matrixrtc/JsRtcSessionBehaviors.ts` | the memberships and key rotation behaviors only | -| `state/CallViewModel/localMember/HomeserverConnected.ts` | `matrixrtc/HomeserverConnected.ts` | the grace period defaults to `defaultSessionTimings` instead of `Config.get()` | -| `state/CallViewModel/localMember/LocalMember.ts` | `matrixrtc/LocalMembership.ts`, `media-backend/livekit/LocalMedia.ts`, `participationState.ts` | split into the Matrix side, the media side and the state machine that combines them | -| `state/CallViewModel/localMember/LocalTransport.ts`, `RtcTransportAutoDiscovery.ts` | `matrixrtc/LocalTransport.ts`, `TransportAutoDiscovery.ts` | the override and the fallback are transports from the options, not a setting and a resolved config | -| `state/CallViewModel/remoteMembers/MatrixLivekitMembers.ts` | `media-backend/livekit/LivekitBackend.ts` (`mediaFor`) | matches participants to members inside the backend; the SDK hands out `RTCMember`s | -| `state/CallViewModel/remoteMembers/MatrixMemberMetadata.ts`, `utils/displayname.ts` | `matrixrtc/MatrixMemberMetadata.ts`, `utils/displayname.ts` | as is | -| `state/CallViewModel/remoteMembers/Connection.ts` | `media-backend/livekit/Connection.ts` | throws `MatrixRTCError`s; `ConnectionState` is a discriminated union; fetches its own token for its role | -| `state/CallViewModel/remoteMembers/ConnectionFactory.ts` | `media-backend/livekit/ConnectionFactory.ts` | `LivekitConnectionFactory` builds the room options from the publish requests and `mediaQuality`, not from settings | -| `state/CallViewModel/remoteMembers/ConnectionManager.ts` | `media-backend/livekit/ConnectionMap.ts` | keyed by `TransportLocator`; the publisher role is the local transport's | -| `state/CallViewModel/localMember/Publisher.ts` | `media-backend/livekit/Publisher.ts` | rewritten on publish requests instead of `MuteStates` | -| `livekit/openIDSFU.ts`, later `livekit/auth/` | `media-backend/livekit/auth/` | the flow is chosen by the transport's shape and our role; the delegated leave timeout is a parameter | -| `livekit/options.ts` | `media-backend/livekit/livekitOptions.ts` | `buildLiveKitOptions(mediaQuality?)` only; the `Config` singleton is gone | -| `e2ee/matrixKeyProvider.ts`, the key provider selection | `media-backend/livekit/MatrixKeyProvider.ts`, `KeyProvider.ts` | as is; selection keyed off `encryptionSystem` | -| `e2ee/e2eeType.ts`, `EncryptionSystem` from `e2ee/sharedKeyManagement.ts` | `encryption.ts` | the React hooks stayed behind | -| `MatrixRTCMode`, the timings and media quality types from `config/ConfigOptions.ts` | `config.ts` | `defaultSessionTimings` and `defaultMediaQuality` replace `DEFAULT_CONFIG` | -| `utils/errors.ts` | `errors.ts` | `MatrixRTCError` with `code` and `category` replaces `ElementCallError`; messages are plain English, the host translates by code | -| `doNetworkOperationWithRetry` from `utils/matrix.ts` | `utils/network.ts` | takes a `shouldRetry` predicate | -| the join in `CallViewModel.ts` (`enterRTCSession`) | `matrixrtc/joinJsSdkSession.ts` | the timings and the delayed leave variant are parameters | -| `livekit/MatrixAudioRenderer.tsx`, the participant reads in `state/media/` | `media-backend/livekit/LivekitMediaTrack.ts`, `LivekitMemberMedia.ts` | the view models get `MediaTrack`s with `attach`; nothing in `src/` imports a LiveKit participant any more | - -## What still binds Element Call to LiveKit - -Each is a gap in the SDK's API rather than something to rename; the import goes -away when the SDK grows the piece. The names Element Call owes to the outside -stay as they are: the `livekit.livekit_service_url` key in `config.json`, the -persisted setting keys `extended-livekit-logs` and `custom-transport`, the -Posthog fields `callBackend` and `callReconnectingCountLivekit`, the rageshake -field `call_backend`, and the translated error strings. - -| Gap | Where it shows | -| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -| Preview before `join()`: local tracks for the lobby, handed out as `MediaTrack`s | `LobbyView` (`usePreviewTracks`), `VideoPreview` (`LocalVideoTrack`, `facingModeFromLocalTrack`) | -| Device enumeration without LiveKit's helpers | `MediaDevices` (`createMediaDeviceObserver`), `CallView` (`Room.getLocalDevices`) | -| A `logging` option: log level and a sink for the transport's logs | `initializer.tsx`, the `extended-livekit-logs` setting | -| A `capabilities` field: output selection and background processors, asked of the SDK rather than of LiveKit | `CallFooterViewModel` (`supportsAudioOutputSelection`, `supportsBackgroundProcessors`) | -| Element Call's error and analytics types on the SDK's | `PosthogEvents` (`DisconnectReason`), `errors.ts` (`ConnectionError`, `LivekitConnectionError`) | diff --git a/src/room/InCallView.tsx b/src/room/InCallView.tsx index 0d34f6a9c..2a20a1cc4 100644 --- a/src/room/InCallView.tsx +++ b/src/room/InCallView.tsx @@ -748,8 +748,7 @@ export const InCallView: FC = ({ /** * How the tracks are captured and encoded, from Element Call's settings and - * configuration. Shared with the legacy SDK bundle so that a widget built from - * it behaves like the app. + * configuration. */ export function captureSettings(): CaptureSettings { const config = Config.get(); @@ -798,8 +797,7 @@ export function captureSettings(): CaptureSettings { /** * What the client needs from Element Call's configuration, settings and URL: * the SDK reads none of them itself. What to publish depends on the mute - * switches and the devices, so the caller adds that. Shared with the legacy - * SDK bundle so that a widget built from it behaves like the app. + * switches and the devices, so the caller adds that. */ export function rtcSlotOptions( encryptionSystem: EncryptionSystem, diff --git a/tsconfig.json b/tsconfig.json index 1544837ef..5956a4ca6 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -58,7 +58,7 @@ "./src/**/*.tsx", "./playwright/**/*.ts", "./sdk/**/*.ts", - "./sdk-target-based-on-call-view-model/**/*.ts", + "./widget-rtc-sdk/**/*.ts", "./component/**/*.ts", "./component/**/*.tsx" ], diff --git a/vite-sdk-target-based-on-call-view-model.config.ts b/vite-widget-rtc-sdk.config.ts similarity index 61% rename from vite-sdk-target-based-on-call-view-model.config.ts rename to vite-widget-rtc-sdk.config.ts index f5d19395c..36edf2580 100644 --- a/vite-sdk-target-based-on-call-view-model.config.ts +++ b/vite-widget-rtc-sdk.config.ts @@ -10,11 +10,9 @@ import { fileURLToPath } from "node:url"; import { defineConfig } from "vite"; import nodePolyfills from "vite-plugin-node-stdlib-browser"; -// Config for the legacy SDK bundle that predates the sdk/ package: a single -// bundle of Element Call's CallViewModel for a plain web page or widget. It is -// in production use, so it keeps building on top of the sdk/ package until its -// consumers have moved to that package directly. -export default defineConfig(() => ({ +// Config for the widget RTC SDK: a single bundle that wraps the sdk/ package for +// a widget page. CI deploys it as the `pr-widget-rtc-sdk` Netlify preview. +export default defineConfig(({ mode }) => ({ worker: { format: "es" as const }, resolve: { alias: { @@ -29,13 +27,17 @@ export default defineConfig(() => ({ // Otherwise the developer's own config.json in `public` is copied into the output publicDir: false, build: { - sourcemap: true, + // Optimised for production (`build:widget-rtc-sdk:production`): minified and + // without source maps, which nothing uploads for this bundle. Readable in + // development. + minify: mode === "production", + sourcemap: mode !== "production", manifest: true, lib: { formats: ["es" as const], - entry: "./sdk-target-based-on-call-view-model/main.ts", - name: "MatrixrtcSdk", - fileName: "matrixrtc-sdk", + entry: "./widget-rtc-sdk/main.ts", + name: "WidgetRtcSdk", + fileName: "widget-rtc-sdk", }, }, plugins: [nodePolyfills()], diff --git a/widget-rtc-sdk/README.md b/widget-rtc-sdk/README.md new file mode 100644 index 000000000..1f4c1f1c4 --- /dev/null +++ b/widget-rtc-sdk/README.md @@ -0,0 +1,91 @@ +# Widget RTC SDK + +A single JavaScript bundle for widget pages: it connects to the host (for +example Element Web) over the widget API and wraps the `sdk/` package +(`@element-hq/matrixrtc-sdk`) to join a MatrixRTC slot and exchange realtime +data. A widget needs no Matrix login of its own: the host's client does the +talking. It uses nothing of Element Call's app; a page that is not a widget +uses the `sdk/` package directly (see `sdk/README.md`). + +```ts +import { createMatrixRTCSdk } from "/widget-rtc-sdk.js"; + +const sdk = await createMatrixRTCSdk("com.example.my-app"); // the rtc application +sdk.join(); +sdk.connected$.subscribe((connected) => console.info({ connected })); +sdk.remoteMembers$.subscribe((members) => console.info(members)); +sdk.data$.subscribe(({ rtcBackendIdentity, data }) => + console.info(rtcBackendIdentity, JSON.parse(data)), +); +await sdk.sendData({ hello: "world" }); +sdk.leave(); +``` + +`createMatrixRTCSdk(application = "m.call", id = "", sticky = false)` takes the +slot's application and id, and whether to ask the host to keep the widget on +screen while joined. The participation publishes no media; `sendData` and +`data$` carry JSON over the `matrixRTC` data channel topic. When the +participation has left, the widget asks the host to close it. + +If the widget page has a `config.json` beside it, the bundle reads Element +Call's `matrix_rtc_mode`, `livekit.livekit_service_url`, +`sync_disconnect_grace_period_ms` and `matrix_rtc_session` from it. + +## Using a pull request's build + +CI builds the bundle for every pull request and deploys it to Netlify as +`pr-widget-rtc-sdk`, so a widget can import it without building anything: + +``` +https://pr-widget-rtc-sdk--element-call.netlify.app/widget-rtc-sdk.js +``` + +1. Host a page that imports it. `index.html` in this folder is one: set the + PR number in its import and serve the folder, for example with + `npx serve -l 8080`. +2. Add the page as a widget in a room in Element Web (see + [Widget url](#widget-url)): + + ``` + /addwidget http://localhost:8080?widgetId=$matrix_widget_id&userId=$matrix_user_id&deviceId=$org.matrix.msc3819.matrix_device_id&baseUrl=$org.matrix.msc4039.matrix_base_url&roomId=$matrix_room_id + ``` + +3. Open the widget and accept the capabilities it asks for: + the example joins on load. Open it from a second account to see members and + data arrive. + +## Building it yourself + +``` +pnpm install +pnpm build:widget-rtc-sdk +``` + +in the repository root writes the bundle to `dist/`, entry `widget-rtc-sdk.js`. +Serve it with CORS, so a page on another origin can import it (for example +`npx serve -l 8123 --cors dist`), and point the page's import at +`http://localhost:8123/widget-rtc-sdk.js`. + +`build:widget-rtc-sdk:production` (what CI deploys) minifies and leaves out +source maps; `build:widget-rtc-sdk:development` does neither. + +## Widget url + +The host fills the widget url's parameters in when it opens the widget; the +bundle reads them, from the query or from a query in the fragment, to start the +widget API: + +``` +widgetId = $matrix_widget_id +userId = $matrix_user_id +deviceId = $org.matrix.msc3819.matrix_device_id +baseUrl = $org.matrix.msc4039.matrix_base_url +roomId = $matrix_room_id +``` + +`parentUrl` is added by the host. `sendNotificationType` (`ring` or +`notification`) optionally notifies the room on join. + +The `$` prefixed variables are replaced by Element Web when it opens the widget +(for example `$matrix_user_id` becomes `@user:example.com`, url encoded as +`%40user%3Aexample.com`). diff --git a/sdk-target-based-on-call-view-model/index.html b/widget-rtc-sdk/index.html similarity index 84% rename from sdk-target-based-on-call-view-model/index.html rename to widget-rtc-sdk/index.html index df07f634a..42333f394 100644 --- a/sdk-target-based-on-call-view-model/index.html +++ b/widget-rtc-sdk/index.html @@ -1,11 +1,13 @@ - MatrixRTC Widget + Widget RTC SDK example