(initialOptions: DialogOptions, dialog: ComponentType>, props: P): DialogHandle;
+}
+
+// @public
+export type DialogHandle = {
+ finished: Promise<{
+ ok: boolean;
+ model: M | null;
+ }>;
+ close(): void;
+};
+
+// @public
+export interface DialogOptions {
+ title: string;
+}
+
+// @public
+export type DialogProps = {
+ onSubmit(model: M): void;
+ onCancel(): void;
+};
+
+// @alpha @deprecated (undocumented)
+export interface DirectoryCustomisations {
+ // (undocumented)
+ requireCanonicalAliasAccessToPublish?(): boolean;
+}
+
+// @alpha
+export type ExtendablePropsRenderFunction = (
+props: P,
+originalComponent: (props: P) => JSX.Element) => JSX.Element;
+
+// @alpha
+export interface ExtrasApi {
+ addRoomHeaderButtonCallback(cb: RoomHeaderButtonsCallback): void;
+ getVisibleRoomBySpaceKey(spaceKey: string, cb: () => string[]): void;
+ setSpacePanelItem(spaceKey: string, props: SpacePanelItemProps): void;
+}
+
+// @public
+export interface I18nApi {
+ humanizeTime(this: void, timeMillis: number): string;
+ get language(): string;
+ register(this: void, translations: Partial): void;
+ translate(this: void, key: keyof Translations, variables?: Variables): string;
+ translate(this: void, key: keyof Translations, variables: Variables | undefined, tags: Tags): ReactNode;
+}
+
+// @alpha
+export type IdentityApprover = (widget: WidgetDescriptor) => MaybePromise;
+
+// @alpha @deprecated (undocumented)
+export type LegacyCustomisations = (customisations: T) => void;
+
+// @alpha @deprecated (undocumented)
+export interface LegacyCustomisationsApiExtension {
+ // @deprecated (undocumented)
+ readonly _registerLegacyAliasCustomisations: LegacyCustomisations;
+ // @deprecated (undocumented)
+ readonly _registerLegacyChatExportCustomisations: LegacyCustomisations>;
+ // @deprecated (undocumented)
+ readonly _registerLegacyComponentVisibilityCustomisations: LegacyCustomisations;
+ // @deprecated (undocumented)
+ readonly _registerLegacyDirectoryCustomisations: LegacyCustomisations;
+ // @deprecated (undocumented)
+ readonly _registerLegacyLifecycleCustomisations: LegacyCustomisations;
+ // @deprecated (undocumented)
+ readonly _registerLegacyMediaCustomisations: LegacyCustomisations>;
+ // @deprecated (undocumented)
+ readonly _registerLegacyRoomListCustomisations: LegacyCustomisations>;
+ // @deprecated (undocumented)
+ readonly _registerLegacyUserIdentifierCustomisations: LegacyCustomisations;
+ // @deprecated (undocumented)
+ readonly _registerLegacyWidgetPermissionsCustomisations: LegacyCustomisations>;
+ // @deprecated (undocumented)
+ readonly _registerLegacyWidgetVariablesCustomisations: LegacyCustomisations;
+}
+
+// @alpha @deprecated (undocumented)
+export interface LegacyModuleApiExtension {
+ // @deprecated
+ _registerLegacyModule(LegacyModule: RuntimeModuleConstructor): Promise;
+}
+
+// @alpha @deprecated (undocumented)
+export interface LifecycleCustomisations {
+ // (undocumented)
+ onLoggedOutAndStorageCleared?(): void;
+}
+
+// @alpha
+export type LocationRenderFunction = () => JSX.Element;
+
+// @alpha
+export interface MatrixEvent {
+ content: Record;
+ eventId: string;
+ originServerTs: number;
+ roomId: string;
+ sender: string;
+ stateKey?: string;
+ type: string;
+ unsigned: Record;
+}
+
+// @public
+export type MaybePromise = T | PromiseLike;
+
+// @alpha @deprecated (undocumented)
+export interface Media {
+ // (undocumented)
+ downloadSource(): Promise;
+ // (undocumented)
+ getSquareThumbnailHttp(dim: number): string | null;
+ // (undocumented)
+ getThumbnailHttp(width: number, height: number, mode?: "scale" | "crop"): string | null;
+ // (undocumented)
+ getThumbnailOfSourceHttp(width: number, height: number, mode?: "scale" | "crop"): string | null;
+ // (undocumented)
+ readonly hasThumbnail: boolean;
+ // (undocumented)
+ readonly isEncrypted: boolean;
+ // (undocumented)
+ readonly srcHttp: string | null;
+ // (undocumented)
+ readonly srcMxc: string;
+ // (undocumented)
+ readonly thumbnailHttp: string | null;
+ // (undocumented)
+ readonly thumbnailMxc: string | null | undefined;
+}
+
+// @alpha @deprecated (undocumented)
+export interface MediaContructable {
+ // (undocumented)
+ new (prepared: PreparedMedia): Media;
+}
+
+// @alpha @deprecated (undocumented)
+export interface MediaCustomisations {
+ // (undocumented)
+ readonly Media: MediaContructable;
+ // (undocumented)
+ mediaFromContent(content: Content, client?: Client): Media;
+ // (undocumented)
+ mediaFromMxc(mxc?: string, client?: Client): Media;
+}
+
+// @public
+export interface Module {
+ // (undocumented)
+ load(): Promise;
+}
+
+// @public
+export interface ModuleFactory {
+ // (undocumented)
+ new (api: Api): Module;
+ // (undocumented)
+ readonly moduleApiVersion: string;
+ // (undocumented)
+ readonly prototype: Module;
+}
+
+// @public
+export class ModuleIncompatibleError extends Error {
+ constructor(pluginVersion: string);
+}
+
+// @public
+export class ModuleLoader {
+ constructor(api: Api);
+ // Warning: (ae-forgotten-export) The symbol "ModuleExport" needs to be exported by the entry point index.d.ts
+ //
+ // (undocumented)
+ load(moduleExport: ModuleExport): Promise;
+ // (undocumented)
+ start(): Promise;
+}
+
+// @public
+export interface NavigationApi {
+ openRoom(roomIdOrAlias: string, opts?: OpenRoomOptions): void;
+ // @alpha
+ registerLocationRenderer(path: string, renderer: LocationRenderFunction): void;
+ toMatrixToLink(link: string, join?: boolean): Promise;
+}
+
+// @public
+export interface OpenRoomOptions {
+ autoJoin?: boolean;
+ viaServers?: string[];
+}
+
+// @alpha
+export type OriginalMessageComponentProps = {
+ showUrlPreview?: boolean;
+};
+
+// @alpha
+export type PreloadApprover = (widget: WidgetDescriptor) => MaybePromise;
+
+// @public
+export interface Profile {
+ displayName?: string;
+ isGuest?: boolean;
+ userId?: string;
+}
+
+// @public
+export interface ProfileApiExtension {
+ readonly profile: Watchable;
+}
+
+// @public
+export interface Room {
+ getLastActiveTimestamp: () => number;
+ id: string;
+ name: Watchable;
+}
+
+// @alpha
+export type RoomHeaderButtonsCallback = (roomId: string) => JSX.Element | undefined;
+
+// @alpha @deprecated (undocumented)
+export interface RoomListCustomisations {
+ isRoomVisible?(room: Room): boolean;
+}
+
+// @public
+export interface RoomListStoreApi {
+ getRooms(): Watchable;
+ waitForReady(): Promise;
+}
+
+// @alpha
+export interface RoomViewProps {
+ enableReadReceiptsAndMarkersOnActivity?: boolean;
+ hideComposer?: boolean;
+ hideHeader?: boolean;
+ hidePinnedMessageBanner?: boolean;
+ hideRightPanel?: boolean;
+ hideWidgets?: boolean;
+}
+
+// @alpha @deprecated (undocumented)
+export type RuntimeModuleConstructor = new (api: ModuleApi) => RuntimeModule;
+
+// @alpha
+export interface SpacePanelItemProps {
+ className?: string;
+ icon?: JSX.Element;
+ label: string;
+ onSelected: () => void;
+ style?: React.CSSProperties;
+ tooltip?: string;
+}
+
+// @public
+export interface StoresApi {
+ roomListStore: RoomListStoreApi;
+}
+
+// @public
+export type SubstitutionValue = number | string | ReactNode | ((sub: string) => ReactNode);
+
+// @public
+export type Tags = Record;
+
+// @public
+export type Translations = Record;
+
+// @alpha
+export const enum UIComponent {
+ AddIntegrations = "UIComponent.addIntegrations",
+ CreateRooms = "UIComponent.roomCreation",
+ CreateSpaces = "UIComponent.spaceCreation",
+ ExploreRooms = "UIComponent.exploreRooms",
+ FilterContainer = "UIComponent.filterContainer",
+ InviteUsers = "UIComponent.sendInvites",
+ RoomOptionsMenu = "UIComponent.roomOptionsMenu"
+}
+
+// @alpha @deprecated (undocumented)
+export interface UserIdentifierCustomisations {
+ getDisplayUserIdentifier(userId: string, opts: {
+ roomId?: string;
+ withDisplayName?: boolean;
+ }): string | null;
+}
+
+// @public
+export function useWatchable(watchable: Watchable): T;
+
+// @public
+export type Variables = {
+ count?: number;
+ [key: string]: SubstitutionValue;
+};
+
+// @public
+export class Watchable {
+ constructor(currentValue: T);
+ // Warning: (ae-forgotten-export) The symbol "WatchFn" needs to be exported by the entry point index.d.ts
+ //
+ // (undocumented)
+ protected readonly listeners: Set>;
+ protected onFirstWatch(): void;
+ protected onLastWatch(): void;
+ // (undocumented)
+ unwatch(listener: (value: T) => void): void;
+ get value(): T;
+ set value(value: T);
+ // (undocumented)
+ watch(listener: (value: T) => void): void;
+}
+
+// @alpha
+export interface WidgetApi {
+ getAppAvatarUrl(app: IWidget, width?: number, height?: number, resizeMethod?: string): string | null;
+ getWidgetsInRoom(roomId: string): IWidget[];
+ isAppInContainer(app: IWidget, container: Container, roomId: string): boolean;
+ moveAppToContainer(app: IWidget, container: Container, roomId: string): void;
+}
+
+// @alpha
+export type WidgetDescriptor = {
+ id: string;
+ templateUrl: string;
+ creatorUserId: string;
+ type: string;
+ origin: string;
+ roomId?: string;
+};
+
+// @alpha
+export interface WidgetLifecycleApi {
+ registerCapabilitiesApprover(approver: CapabilitiesApprover): void;
+ registerIdentityApprover(approver: IdentityApprover): void;
+ registerPreloadApprover(approver: PreloadApprover): void;
+}
+
+// @alpha @deprecated (undocumented)
+export interface WidgetPermissionsCustomisations {
+ preapproveCapabilities?(widget: Widget, requestedCapabilities: Set): Promise>;
+}
+
+// @alpha @deprecated (undocumented)
+export interface WidgetVariablesCustomisations {
+ isReady?(): Promise;
+ provideVariables?(): {
+ currentUserId: string;
+ userDisplayName?: string;
+ userHttpAvatarUrl?: string;
+ clientId?: string;
+ clientTheme?: string;
+ clientLanguage?: string;
+ deviceId?: string;
+ baseUrl?: string;
+ };
+}
+
+// (No @packageDocumentation comment for this package)
+
+```
diff --git a/packages/module-api/package.json b/packages/module-api/package.json
new file mode 100644
index 0000000000..167e4232b0
--- /dev/null
+++ b/packages/module-api/package.json
@@ -0,0 +1,69 @@
+{
+ "name": "@element-hq/element-web-module-api",
+ "type": "module",
+ "version": "1.13.0",
+ "description": "Module API surface for element-web",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/element-hq/element-modules.git",
+ "directory": "packages/element-web-module-api"
+ },
+ "author": "element-hq",
+ "license": "SEE LICENSE IN README.md",
+ "engines": {
+ "node": ">=20.0.0"
+ },
+ "types": "./lib/element-web-module-api-alpha.d.ts",
+ "exports": {
+ ".": {
+ "types": "./lib/element-web-module-api-alpha.d.ts",
+ "import": "./lib/element-web-plugin-engine.js",
+ "require": "./lib/element-web-plugin-engine.umd.cjs"
+ }
+ },
+ "files": [
+ "lib"
+ ],
+ "scripts": {
+ "prepack": "nx build",
+ "lint:types": "nx lint:types",
+ "test:unit": "vitest"
+ },
+ "devDependencies": {
+ "@matrix-org/react-sdk-module-api": "^2.5.0",
+ "@microsoft/api-extractor": "^7.49.1",
+ "@types/node": "^22.10.7",
+ "@types/react": "^19",
+ "@types/react-dom": "^19.0.4",
+ "@types/semver": "^7.5.8",
+ "@vitest/coverage-v8": "^4.0.0",
+ "matrix-widget-api": "^1.17.0",
+ "rollup-plugin-external-globals": "^0.13.0",
+ "semver": "^7.6.3",
+ "typescript": "^5.7.3",
+ "vite": "^7.3.2",
+ "vite-plugin-dts": "^4.5.0",
+ "vitest": "^4.0.0",
+ "vitest-sonar-reporter": "^3.0.0"
+ },
+ "peerDependencies": {
+ "@matrix-org/react-sdk-module-api": "*",
+ "@types/react": "*",
+ "@types/react-dom": "*",
+ "matrix-widget-api": "*",
+ "matrix-web-i18n": "*",
+ "react": "^19"
+ },
+ "peerDependenciesMeta": {
+ "@matrix-org/react-sdk-module-api": {
+ "optional": true
+ },
+ "matrix-widget-api": {
+ "optional": true
+ },
+ "matrix-web-i18n": {
+ "optional": true
+ }
+ },
+ "dependencies": {}
+}
diff --git a/packages/module-api/project.json b/packages/module-api/project.json
new file mode 100644
index 0000000000..56f41507ae
--- /dev/null
+++ b/packages/module-api/project.json
@@ -0,0 +1,22 @@
+{
+ "$schema": "../../node_modules/nx/schemas/project-schema.json",
+ "projectType": "library",
+ "root": "packages/module-api",
+ "targets": {
+ "build": {
+ "cache": true,
+ "executor": "nx:run-commands",
+ "inputs": ["src"],
+ "outputs": ["{projectRoot}/lib"],
+ "options": {
+ "commands": ["vite build", "api-extractor run"],
+ "parallel": false,
+ "cwd": "packages/module-api"
+ }
+ },
+ "lint:types": {
+ "command": "pnpm exec tsc --noEmit",
+ "options": { "cwd": "packages/module-api" }
+ }
+ }
+}
diff --git a/packages/module-api/src/@types/global.d.ts b/packages/module-api/src/@types/global.d.ts
new file mode 100644
index 0000000000..82ae781eb5
--- /dev/null
+++ b/packages/module-api/src/@types/global.d.ts
@@ -0,0 +1,13 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+declare global {
+ // eslint-disable-next-line no-var
+ var __VERSION__: string; // injected by vite
+}
+
+export {};
diff --git a/packages/module-api/src/api/auth.ts b/packages/module-api/src/api/auth.ts
new file mode 100644
index 0000000000..5ecdcd3c25
--- /dev/null
+++ b/packages/module-api/src/api/auth.ts
@@ -0,0 +1,45 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+/**
+ * Interface for account authentication information, used for overwriting the current account's authentication state.
+ * @public
+ */
+export interface AccountAuthInfo {
+ /**
+ * The user ID.
+ */
+ userId: string;
+ /**
+ * The device ID.
+ */
+ deviceId: string;
+ /**
+ * The access token belonging to this device ID and user ID.
+ */
+ accessToken: string;
+ /**
+ * The refresh token belonging to this device ID and user ID.
+ */
+ refreshToken?: string;
+ /**
+ * The homeserver URL where the credentials are valid.
+ */
+ homeserverUrl: string;
+}
+
+/**
+ * Methods to manage authentication in the application.
+ * @public
+ */
+export interface AccountAuthApiExtension {
+ /**
+ * Overwrite the current account's authentication state with the provided account information.
+ * @param accountInfo - The account authentication information to overwrite the current state with.
+ */
+ overwriteAccountAuth(accountInfo: AccountAuthInfo): Promise;
+}
diff --git a/packages/module-api/src/api/builtins.ts b/packages/module-api/src/api/builtins.ts
new file mode 100644
index 0000000000..d4c461d098
--- /dev/null
+++ b/packages/module-api/src/api/builtins.ts
@@ -0,0 +1,74 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+/**
+ * The props that must be passed to a RoomView component.
+ * @alpha Subject to change.
+ */
+export interface RoomViewProps {
+ /**
+ * If true, the room header will be hidden.
+ */
+ hideHeader?: boolean;
+ /**
+ * If true, the message composer will be hidden.
+ */
+ hideComposer?: boolean;
+ /**
+ * If true, the right panel will be hidden.
+ */
+ hideRightPanel?: boolean;
+ /**
+ * If true, the pinned message banner will be hidden.
+ */
+ hidePinnedMessageBanner?: boolean;
+ /**
+ * If true, the widgets will be hidden.
+ */
+ hideWidgets?: boolean;
+ /**
+ * If true, enable sending read receipts and markers on user activity in the room view. When the user interacts with the room view, read receipts and markers are sent.
+ * If false, the read receipts and markers are only send when the room view is focused. The user has to focus the room view in order to clear any unreads and to move the unread marker to the bottom of the view.
+ * @defaultValue true
+ */
+ enableReadReceiptsAndMarkersOnActivity?: boolean;
+}
+
+/**
+ * Exposes components and classes that are part of Element Web to allow modules to
+ * render the components as part of their custom components or use the classes
+ * (because they can't import the components from Element Web since it would cause
+ * a dependency cycle)
+ * @alpha
+ */
+export interface BuiltinsApi {
+ /**
+ * Render room avatar component from element-web.
+ *
+ * @alpha
+ * @param roomId - Id of the room
+ * @param size - Size of the avatar to render
+ */
+ renderRoomAvatar(roomId: string, size?: string): React.ReactNode;
+
+ /**
+ * Render room view component from element-web.
+ *
+ * @alpha
+ * @param roomId - Id of the room
+ * @param props - Additional props to pass to the room view
+ */
+ renderRoomView(roomId: string, props?: RoomViewProps): React.ReactNode;
+
+ /**
+ * Render notification decoration component from element-web.
+ *
+ * @alpha
+ * @param roomId - Id of the room
+ */
+ renderNotificationDecoration(roomId: string): React.ReactNode;
+}
diff --git a/packages/module-api/src/api/client.ts b/packages/module-api/src/api/client.ts
new file mode 100644
index 0000000000..64e2274e89
--- /dev/null
+++ b/packages/module-api/src/api/client.ts
@@ -0,0 +1,46 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import type { Room } from "../models/Room";
+import { type Watchable } from "./watchable";
+
+/**
+ * Modify account data stored on the homeserver.
+ * @public
+ */
+export interface AccountDataApi {
+ /**
+ * Returns a watchable with account data for this event type.
+ */
+ get(eventType: string): Watchable;
+ /**
+ * Set account data on the homeserver.
+ */
+ set(eventType: string, content: unknown): Promise;
+ /**
+ * Changes the content of this event to be empty.
+ */
+ delete(eventType: string): Promise;
+}
+
+/**
+ * Access some limited functionality from the SDK.
+ * @public
+ */
+export interface ClientApi {
+ /**
+ * Use this to modify account data on the homeserver.
+ */
+ accountData: AccountDataApi;
+
+ /**
+ * Fetch room by id from SDK.
+ * @param id - Id of the room to get
+ * @returns Room object from SDK
+ */
+ getRoom: (id: string) => Room | null;
+}
diff --git a/packages/module-api/src/api/config.ts b/packages/module-api/src/api/config.ts
new file mode 100644
index 0000000000..5f708b4983
--- /dev/null
+++ b/packages/module-api/src/api/config.ts
@@ -0,0 +1,28 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+/**
+ * The configuration for the application.
+ * Should be extended via declaration merging.
+ * @public
+ */
+export interface Config {
+ // The branding name of the application
+ brand: string;
+ // Other config options are available but not specified in the types as that would make it difficult to change for element-web
+ // they are accessible at runtime all the same, see list at https://github.com/element-hq/element-web/blob/develop/docs/config.md
+}
+
+/**
+ * API for accessing the configuration.
+ * @public
+ */
+export interface ConfigApi {
+ get(): Config;
+ get(key: K): Config[K];
+ get(key?: K): Config | Config[K];
+}
diff --git a/packages/module-api/src/api/custom-components.ts b/packages/module-api/src/api/custom-components.ts
new file mode 100644
index 0000000000..0265c9c63d
--- /dev/null
+++ b/packages/module-api/src/api/custom-components.ts
@@ -0,0 +1,227 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import type { JSX, ReactNode } from "react";
+import type { MatrixEvent } from "../models/event";
+import type { AccountAuthInfo } from "./auth.ts";
+
+/**
+ * Properties for all message components.
+ * @alpha Subject to change.
+ */
+export type CustomMessageComponentProps = {
+ /**
+ * The Matrix event for this textual body.
+ * @alpha
+ */
+ mxEvent: MatrixEvent;
+};
+
+/**
+ * Properties to alter the render function of the original component.
+ * @alpha Subject to change.
+ */
+export type OriginalMessageComponentProps = {
+ /**
+ * Should previews be shown for this event.
+ * This may be overriden by user preferences.
+ */
+ showUrlPreview?: boolean;
+};
+
+/**
+ * Hints to specify to Element when rendering events.
+ * @alpha Subject to change.
+ */
+export type CustomMessageRenderHints = {
+ /**
+ * Should the event be allowed to be edited in the client. This should
+ * be set to false if you override the render function, as the module
+ * API has no way to display message editing at the moment.
+ * Default is true.
+ */
+ allowEditingEvent?: boolean;
+ /**
+ * If an event contains media, this function will be called to check
+ * if the media can be prompted to be downloaded as a file.
+ * If this function is not supplied, media downloads are allowed.
+ */
+ allowDownloadingMedia?: (mxEvent: MatrixEvent) => Promise;
+};
+
+/**
+ * Function used to render a message component.
+ * @alpha Subject to change.
+ */
+export type CustomMessageRenderFunction = (
+ /**
+ * Properties for the message to be renderered.
+ */
+ props: CustomMessageComponentProps,
+ /**
+ * Render function for the original component. This may be omitted if the message would not normally be rendered.
+ */
+ originalComponent?: (props?: OriginalMessageComponentProps) => React.JSX.Element,
+) => JSX.Element;
+
+/**
+ * Properties for all message components.
+ * @alpha Subject to change.
+ */
+export type CustomRoomPreviewBarComponentProps = {
+ roomId?: string;
+ roomAlias?: string;
+};
+
+/**
+ * Function used to render a room preview bar component.
+ * @alpha Unlikely to change
+ */
+export type CustomRoomPreviewBarRenderFunction = (
+ /**
+ * Properties for the room preview bar to be rendered.
+ */
+ props: CustomRoomPreviewBarComponentProps,
+ /**
+ * Render function for the original component.
+ */
+ originalComponent: (props: CustomRoomPreviewBarComponentProps) => JSX.Element,
+) => JSX.Element;
+
+/**
+ * Authentication server config object.
+ * @alpha Subject to change.
+ */
+export interface CustomLoginComponentPropsServerConfig {
+ /**
+ * The URL of the homeserver's client-server API
+ */
+ hsUrl: string;
+ /**
+ * The name of the homeserver to present to the user
+ */
+ hsName: string;
+}
+
+/**
+ * Properties for login component.
+ * @alpha Subject to change.
+ */
+export type CustomLoginComponentProps = {
+ /**
+ * The details of the currently chosen Matrix homeserver
+ */
+ serverConfig: CustomLoginComponentPropsServerConfig;
+ /**
+ * The URL fragment to send the user to after authentication is complete
+ */
+ fragmentAfterLogin?: string;
+ /**
+ * Additional components to render as children
+ */
+ children?: ReactNode;
+ /**
+ * Function to complete login
+ * @param data - the data to authenticate the user with
+ */
+ onLoggedIn(data: AccountAuthInfo): void;
+ /**
+ * Function to change the selected server
+ * @param config - new server configuration details
+ */
+ onServerConfigChange(config: CustomLoginComponentPropsServerConfig): void;
+};
+
+/**
+ * Function used to render a component with a superset of the known props.
+ * @alpha Unlikely to change
+ */
+export type ExtendablePropsRenderFunction = (
+ /**
+ * Properties for the component to be rendered.
+ */
+ props: P,
+ /**
+ * Render function for the original component.
+ */
+ originalComponent: (props: P) => JSX.Element,
+) => JSX.Element;
+
+/**
+ * Function used to render a login component.
+ * @alpha Unlikely to change
+ */
+export type CustomLoginRenderFunction = ExtendablePropsRenderFunction;
+
+/**
+ * API for inserting custom components into Element.
+ * @alpha Subject to change.
+ */
+export interface CustomComponentsApi {
+ /**
+ * Register a renderer for a message type in the timeline.
+ *
+ * The render function should return a rendered component.
+ *
+ * Multiple render function may be registered for a single event type, however the first matching
+ * result will be used. If no events match or are registered then the originalComponent is rendered.
+ *
+ * @param eventTypeOrFilter - The event type this renderer is for. Use a function for more complex filtering.
+ * @param renderer - The render function.
+ * @param hints - Hints that alter the way the tile is handled.
+ * @example
+ * ```
+ * customComponents.registerMessageRenderer("m.room.message", (props, originalComponent) => {
+ * return ;
+ * });
+ * customComponents.registerMessageRenderer(
+ * (mxEvent) => mxEvent.getType().matches(/m\.room\.(topic|name)/) && mxEvent.isState(),
+ * (props, originalComponent) => {
+ * return ;
+ * }
+ * );
+ * ```
+ */
+ registerMessageRenderer(
+ eventTypeOrFilter: string | ((mxEvent: MatrixEvent) => boolean),
+ renderer: CustomMessageRenderFunction,
+ hints?: CustomMessageRenderHints,
+ ): void;
+
+ /**
+ * Register a renderer for the room preview bar.
+ *
+ * The render function should return a rendered component.
+ *
+ * @param renderer - The render function for the room preview bar.
+ * @example
+ * ```
+ * customComponents.registerRoomPreviewBar((props, OriginalComponent) => {
+ * if (props.roomId === "!some_special_room_id:server") {
+ * return ;
+ * }
+ * return ;
+ * });
+ * ```
+ */
+ registerRoomPreviewBar(renderer: CustomRoomPreviewBarRenderFunction): void;
+
+ /**
+ * Register a renderer for the login component.
+ *
+ * The render function should return a rendered component.
+ *
+ * @param renderer - The render function for the login component.
+ * @example
+ * ```
+ * customComponents.registerLoginComponent((props, OriginalComponent) => {
+ * return ;
+ * });
+ * ```
+ */
+ registerLoginComponent(renderer: CustomLoginRenderFunction): void;
+}
diff --git a/packages/module-api/src/api/customisations.ts b/packages/module-api/src/api/customisations.ts
new file mode 100644
index 0000000000..1a02c68ed0
--- /dev/null
+++ b/packages/module-api/src/api/customisations.ts
@@ -0,0 +1,65 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+/**
+ * Enum of UI components which can have their behaviour tweaked
+ * @alpha
+ */
+export const enum UIComponent {
+ /**
+ * Components that lead to a user being invited.
+ */
+ InviteUsers = "UIComponent.sendInvites",
+
+ /**
+ * Components that lead to a room being created that aren't already
+ * guarded by some other condition (ie: "only if you can edit this
+ * space" is *not* guarded by this component, but "start DM" is).
+ */
+ CreateRooms = "UIComponent.roomCreation",
+
+ /**
+ * Components that lead to a Space being created that aren't already
+ * guarded by some other condition (ie: "only if you can add subspaces"
+ * is *not* guarded by this component, but "create new space" is).
+ */
+ CreateSpaces = "UIComponent.spaceCreation",
+
+ /**
+ * Components that lead to the public room directory.
+ */
+ ExploreRooms = "UIComponent.exploreRooms",
+
+ /**
+ * Components that lead to the user being able to easily add widgets
+ * and integrations to the room, such as from the room information card.
+ */
+ AddIntegrations = "UIComponent.addIntegrations",
+
+ /**
+ * Component that lead to the user being able to search, dial, explore rooms
+ */
+ FilterContainer = "UIComponent.filterContainer",
+
+ /**
+ * Components that lead the user to room options menu.
+ */
+ RoomOptionsMenu = "UIComponent.roomOptionsMenu",
+}
+
+/**
+ * API for customising Element Web's components
+ * @alpha Subject to change.
+ */
+export interface CustomisationsApi {
+ /**
+ * Method to register a callback which can affect whether a given component is drawn or not.
+ * @param fn - the callback, if it returns true the component will be rendered, if false it will not be.
+ * If undefined will defer to next callback, ultimately falling through to `true` if none return false.
+ */
+ registerShouldShowComponent(fn: (this: void, component: UIComponent) => boolean | void): void;
+}
diff --git a/packages/module-api/src/api/dialog.ts b/packages/module-api/src/api/dialog.ts
new file mode 100644
index 0000000000..cd9a2c867c
--- /dev/null
+++ b/packages/module-api/src/api/dialog.ts
@@ -0,0 +1,68 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { type ComponentType } from "react";
+
+/**
+ * Options for {@link Api#openDialog}.
+ * @public
+ */
+export interface DialogOptions {
+ /**
+ * The title of the dialog.
+ */
+ title: string;
+}
+
+/**
+ * Handle returned by {@link Api#openDialog}.
+ * @public
+ */
+export type DialogHandle = {
+ /**
+ * Promise that resolves when the dialog is finished.
+ */
+ finished: Promise<{ ok: boolean; model: M | null }>;
+ /**
+ * Method to close the dialog.
+ */
+ close(): void;
+};
+
+/**
+ * Props passed to the dialog body component.
+ * @public
+ */
+export type DialogProps = {
+ /**
+ * Callback to submit the dialog.
+ * @param model - The model to submit with the dialog. This is typically the data collected.
+ */
+ onSubmit(model: M): void;
+ /**
+ * Cancel the dialog programmatically.
+ */
+ onCancel(): void;
+};
+
+/**
+ * Methods to manage dialogs in the application.
+ * @public
+ */
+export interface DialogApiExtension {
+ /**
+ * Open a dialog with the given options and body component and return a handle to it.
+ * @param initialOptions - The initial options for the dialog, such as title and action label.
+ * @param dialog - The body component to render in the dialog. This component should accept props of type `P`.
+ * @param props - Additional props to pass to the body
+ */
+ openDialog(
+ initialOptions: DialogOptions,
+ dialog: ComponentType>,
+ props: P,
+ ): DialogHandle;
+}
diff --git a/packages/module-api/src/api/extras.ts b/packages/module-api/src/api/extras.ts
new file mode 100644
index 0000000000..ad437c4986
--- /dev/null
+++ b/packages/module-api/src/api/extras.ts
@@ -0,0 +1,86 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { type JSX } from "react";
+
+/**
+ * Properties of an item added to the Space panel
+ * @alpha
+ */
+export interface SpacePanelItemProps {
+ /**
+ * A CSS class name for the item
+ */
+ className?: string;
+
+ /**
+ * An icon to show in the item. If not provided, no icon will be shown.
+ */
+ icon?: JSX.Element;
+
+ /**
+ * The label to show in the item
+ */
+ label: string;
+
+ /**
+ * A tooltip to show when hovering over the item
+ */
+ tooltip?: string;
+
+ /**
+ * Styles to apply to the item
+ */
+ style?: React.CSSProperties;
+
+ /**
+ * Callback when the item is selected
+ */
+ onSelected: () => void;
+}
+
+/**
+ * A callback that returns a JSX element representing the buttons.
+ *
+ * @alpha
+ * @param roomId - The ID of the room for which the header is being rendered.
+ * @returns A JSX element representing the buttons to be rendered in the room header, or undefined if no buttons should be rendered.
+ */
+export type RoomHeaderButtonsCallback = (roomId: string) => JSX.Element | undefined;
+
+/**
+ * API for inserting extra UI into Element Web.
+ * @alpha Subject to change.
+ */
+export interface ExtrasApi {
+ /**
+ * Inserts an item into the space panel as if it were a space button, below
+ * buttons for other spaces.
+ * If called again with the same spaceKey, will update the existing item.
+ * @param spaceKey - A key to identify this space-like item.
+ * @param props - Properties of the item to add.
+ */
+ setSpacePanelItem(spaceKey: string, props: SpacePanelItemProps): void;
+
+ /**
+ * Registers a callback to get the list of visible rooms for a given space.
+ *
+ * Element Web will call this callback when checking if a room is displayed for the given space. For example in case of message editing or replying.
+ * If the space added by the module displays a room view and doesn't provide this callback, Element Web won't be able to determine if a room is visible in that space and will redirect to display the room in its vanilla space/metaspace.
+ *
+ * @param spaceKey - The space key to get visible rooms for.
+ * @param cb - A callback that returns the list of visible room IDs.
+ */
+ getVisibleRoomBySpaceKey(spaceKey: string, cb: () => string[]): void;
+
+ /**
+ * Adds a callback to get extra buttons in the room header (which can vary depending on the room being displayed).
+ *
+ * @param cb - A callback that returns a JSX element representing the buttons (see {@link RoomHeaderButtonsCallback}).
+ */
+ addRoomHeaderButtonCallback(cb: RoomHeaderButtonsCallback): void;
+}
diff --git a/packages/module-api/src/api/i18n.ts b/packages/module-api/src/api/i18n.ts
new file mode 100644
index 0000000000..030081ae9d
--- /dev/null
+++ b/packages/module-api/src/api/i18n.ts
@@ -0,0 +1,86 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { type ReactNode } from "react";
+
+/**
+ * The translations for the module.
+ * @public
+ */
+export type Translations = Record<
+ string,
+ {
+ [ietfLanguageTag: string]: string;
+ }
+>;
+
+/**
+ * The value a variable or tag can take for a translation interpolation.
+ *
+ * When used as a function, `sub` is the text content wrapped between the tag
+ * in the translation string. For example, given `"Click here"`, the
+ * function receives `"here"` and should return a `ReactNode` wrapping it.
+ *
+ * @public
+ */
+export type SubstitutionValue = number | string | ReactNode | ((sub: string) => ReactNode);
+
+/**
+ * Variables to interpolate into a translation.
+ * @public
+ */
+export type Variables = {
+ /**
+ * The number of items to count for pluralised translations
+ */
+ count?: number;
+ [key: string]: SubstitutionValue;
+};
+
+/**
+ * Tags to interpolate into a translation, where the value is a ReactNode or a function that returns a ReactNode.
+ * This allows for more complex interpolations, such as links or formatted text.
+ * @public
+ */
+export type Tags = Record;
+
+/**
+ * The API for interacting with translations.
+ * @public
+ */
+export interface I18nApi {
+ /**
+ * Read the current language of the user in IETF Language Tag format
+ */
+ get language(): string;
+
+ /**
+ * Register translations for the module, may override app's existing translations
+ */
+ register(this: void, translations: Partial): void;
+
+ /**
+ * Perform a translation, with optional variables
+ * @param key - The key to translate
+ * @param variables - Optional variables to interpolate into the translation
+ */
+ translate(this: void, key: keyof Translations, variables?: Variables): string;
+ /**
+ * Perform a translation, with optional variables
+ * @param key - The key to translate
+ * @param variables - Optional variables to interpolate into the translation
+ * @param tags - Optional tags to interpolate into the translation
+ */
+ translate(this: void, key: keyof Translations, variables: Variables | undefined, tags: Tags): ReactNode;
+
+ /**
+ * Convert a timestamp into a translated, human-readable time,
+ * using the current system time as a reference, eg. "5 minutes ago".
+ * @param timeMillis - The time in milliseconds since epoch
+ */
+ humanizeTime(this: void, timeMillis: number): string;
+}
diff --git a/packages/module-api/src/api/index.test.ts b/packages/module-api/src/api/index.test.ts
new file mode 100644
index 0000000000..8cd7a879fb
--- /dev/null
+++ b/packages/module-api/src/api/index.test.ts
@@ -0,0 +1,22 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { expect, test } from "vitest";
+
+import { type Api, isModule } from ".";
+
+const TestModule = {
+ default: class TestModule {
+ public static moduleApiVersion = "1.0.0";
+ public constructor(private readonly api: Api) {}
+ public async load(): Promise {}
+ },
+};
+
+test("isModule correctly identifies valid modules", () => {
+ expect(isModule(TestModule)).toBe(true);
+});
diff --git a/packages/module-api/src/api/index.ts b/packages/module-api/src/api/index.ts
new file mode 100644
index 0000000000..3d60fc2a43
--- /dev/null
+++ b/packages/module-api/src/api/index.ts
@@ -0,0 +1,169 @@
+/*
+Copyright 2025 New Vector Ltd.
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import type { Root } from "react-dom/client";
+import { type LegacyModuleApiExtension } from "./legacy-modules";
+import { type LegacyCustomisationsApiExtension } from "./legacy-customisations";
+import { type ConfigApi } from "./config";
+import { type I18nApi } from "./i18n";
+import { type CustomComponentsApi } from "./custom-components";
+import { type NavigationApi } from "./navigation.ts";
+import { type DialogApiExtension } from "./dialog.ts";
+import { type AccountAuthApiExtension } from "./auth.ts";
+import { type ProfileApiExtension } from "./profile.ts";
+import { type ExtrasApi } from "./extras.ts";
+import { type BuiltinsApi } from "./builtins.ts";
+import { type StoresApi } from "./stores.ts";
+import { type ClientApi } from "./client.ts";
+import { type WidgetLifecycleApi } from "./widget-lifecycle.ts";
+import { type WidgetApi } from "./widget.ts";
+import { type CustomisationsApi } from "./customisations.ts";
+
+/**
+ * Module interface for modules to implement.
+ * @public
+ */
+export interface Module {
+ load(): Promise;
+}
+
+const moduleSignature: Record = {
+ load: "function",
+};
+
+/**
+ * Module interface for modules to export as the default export.
+ * @public
+ */
+export interface ModuleFactory {
+ readonly moduleApiVersion: string;
+ new (api: Api): Module;
+ readonly prototype: Module;
+}
+
+const moduleFactorySignature: Record = {
+ moduleApiVersion: "string",
+ prototype: "object",
+};
+
+export interface ModuleExport {
+ default: ModuleFactory;
+}
+
+const moduleExportSignature: Record = {
+ default: "function",
+};
+
+type Type = "function" | "string" | "number" | "boolean" | "object";
+
+function isInterface(obj: unknown, type: "object" | "function", keys: Record): obj is T {
+ if (obj === null || typeof obj !== type) return false;
+ for (const key in keys) {
+ if (typeof (obj as Record)[key] !== keys[key]) return false;
+ }
+ return true;
+}
+
+export function isModule(module: unknown): module is ModuleExport {
+ return (
+ isInterface(module, "object", moduleExportSignature) &&
+ isInterface(module.default, "function", moduleFactorySignature) &&
+ isInterface(module.default.prototype, "object", moduleSignature)
+ );
+}
+
+/**
+ * The API for modules to interact with the application.
+ * @public
+ */
+export interface Api
+ extends
+ LegacyModuleApiExtension,
+ LegacyCustomisationsApiExtension,
+ DialogApiExtension,
+ AccountAuthApiExtension,
+ ProfileApiExtension {
+ /**
+ * The API to read config.json values.
+ * Keys should be scoped to the module in reverse domain name notation.
+ * @public
+ */
+ readonly config: ConfigApi;
+ /**
+ * The internationalisation API.
+ * @public
+ */
+ readonly i18n: I18nApi;
+ /**
+ * The root node the main application is rendered to.
+ * Intended for rendering sibling React trees.
+ * @public
+ */
+ readonly rootNode: HTMLElement;
+
+ /**
+ * The custom message component API.
+ * @alpha
+ */
+ readonly customComponents: CustomComponentsApi;
+
+ /**
+ * Allows modules to render components that are part of Element Web.
+ * @alpha
+ */
+ readonly builtins: BuiltinsApi;
+
+ /**
+ * API to navigate the application.
+ * @public
+ */
+ readonly navigation: NavigationApi;
+
+ /**
+ * Allows modules to insert extra UI into Element Web.
+ * @alpha
+ */
+ readonly extras: ExtrasApi;
+
+ /**
+ * Allows modules to access a limited functionality of certain stores from Element Web.
+ */
+ readonly stores: StoresApi;
+
+ /**
+ * Access some very specific functionality from the client.
+ */
+ readonly client: ClientApi;
+
+ /**
+ * API for modules to auto-approve widget preloading, identity token requests, and capability requests.
+ * @alpha Subject to change.
+ */
+ readonly widgetLifecycle: WidgetLifecycleApi;
+
+ /**
+ * API for modules to interact with widgets in Element Web, including getting what widgets
+ * are active in a given room.
+ * @alpha Subject to change.
+ */
+ readonly widget: WidgetApi;
+
+ /**
+ * Allows modules to customise behaviour of app's components.
+ * @alpha Subject to change.
+ */
+ readonly customisations: CustomisationsApi;
+
+ /**
+ * Create a ReactDOM root for rendering React components.
+ * Exposed to allow modules to avoid needing to bundle their own ReactDOM.
+ * @param element - the element to render use as the root.
+ * @public
+ */
+ createRoot(element: Element): Root;
+}
diff --git a/packages/module-api/src/api/legacy-customisations.ts b/packages/module-api/src/api/legacy-customisations.ts
new file mode 100644
index 0000000000..6374789b5b
--- /dev/null
+++ b/packages/module-api/src/api/legacy-customisations.ts
@@ -0,0 +1,259 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+/**
+ * The types here suck but these customisations are deprecated and will be removed soon.
+ */
+
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
+export interface AliasCustomisations {
+ // E.g. prefer one of the aliases over another
+ getDisplayAliasForAliasSet?(canonicalAlias: string | null, altAliases: string[]): string | null;
+}
+
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
+export interface ChatExportCustomisations {
+ /**
+ * Force parameters in room chat export fields returned here are forced
+ * and not allowed to be edited in the chat export form
+ */
+ getForceChatExportParameters(): {
+ format?: ExportFormat;
+ range?: ExportType;
+ // must be < 10**8
+ // only used when range is 'LastNMessages'
+ // default is 100
+ numberOfMessages?: number;
+ includeAttachments?: boolean;
+ // maximum size of exported archive
+ // must be > 0 and < 8000
+ sizeMb?: number;
+ };
+}
+
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
+export interface ComponentVisibilityCustomisations {
+ /**
+ * Determines whether or not the active MatrixClient user should be able to use
+ * the given UI component. If shown, the user might still not be able to use the
+ * component depending on their contextual permissions. For example, invite options
+ * might be shown to the user but they won't have permission to invite users to
+ * the current room: the button will appear disabled.
+ * @param component - The component to check visibility for.
+ * @returns True (default) if the user is able to see the component, false otherwise.
+ */
+ shouldShowComponent?(
+ component:
+ | "UIComponent.sendInvites"
+ | "UIComponent.roomCreation"
+ | "UIComponent.spaceCreation"
+ | "UIComponent.exploreRooms"
+ | "UIComponent.addIntegrations"
+ | "UIComponent.filterContainer"
+ | "UIComponent.roomOptionsMenu",
+ ): boolean;
+}
+
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
+export interface DirectoryCustomisations {
+ requireCanonicalAliasAccessToPublish?(): boolean;
+}
+
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
+export interface LifecycleCustomisations {
+ onLoggedOutAndStorageCleared?(): void;
+}
+
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
+export interface Media {
+ readonly isEncrypted: boolean;
+ readonly srcMxc: string;
+ readonly thumbnailMxc: string | null | undefined;
+ readonly hasThumbnail: boolean;
+ readonly srcHttp: string | null;
+ readonly thumbnailHttp: string | null;
+ getThumbnailHttp(width: number, height: number, mode?: "scale" | "crop"): string | null;
+ getThumbnailOfSourceHttp(width: number, height: number, mode?: "scale" | "crop"): string | null;
+ getSquareThumbnailHttp(dim: number): string | null;
+ downloadSource(): Promise;
+}
+
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
+export interface MediaContructable {
+ new (prepared: PreparedMedia): Media;
+}
+
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
+export interface MediaCustomisations {
+ readonly Media: MediaContructable;
+ mediaFromContent(content: Content, client?: Client): Media;
+ mediaFromMxc(mxc?: string, client?: Client): Media;
+}
+
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
+export interface RoomListCustomisations {
+ /**
+ * Determines if a room is visible in the room list or not. By default,
+ * all rooms are visible. Where special handling is performed by Element,
+ * those rooms will not be able to override their visibility in the room
+ * list - Element will make the decision without calling this function.
+ *
+ * This function should be as fast as possible to avoid slowing down the
+ * client.
+ * @param room - The room to check the visibility of.
+ * @returns True if the room should be visible, false otherwise.
+ */
+ isRoomVisible?(room: Room): boolean;
+}
+
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
+export interface UserIdentifierCustomisations {
+ /**
+ * Customise display of the user identifier
+ * hide userId for guests, display 3pid
+ *
+ * Set withDisplayName to true when user identifier will be displayed alongside user name
+ */
+ getDisplayUserIdentifier(userId: string, opts: { roomId?: string; withDisplayName?: boolean }): string | null;
+}
+
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
+export interface WidgetPermissionsCustomisations {
+ /**
+ * Approves the widget for capabilities that it requested, if any can be
+ * approved. Typically this will be used to give certain widgets capabilities
+ * without having to prompt the user to approve them. This cannot reject
+ * capabilities that Element will be automatically granting, such as the
+ * ability for Jitsi widgets to stay on screen - those will be approved
+ * regardless.
+ * @param widget - The widget to approve capabilities for.
+ * @param requestedCapabilities - The capabilities the widget requested.
+ * @returns Resolves to the capabilities that are approved for use
+ * by the widget. If none are approved, this should return an empty Set.
+ */
+ preapproveCapabilities?(widget: Widget, requestedCapabilities: Set): Promise>;
+}
+
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
+export interface WidgetVariablesCustomisations {
+ /**
+ * Provides a partial set of the variables needed to render any widget. If
+ * variables are missing or not provided then they will be filled with the
+ * application-determined defaults.
+ *
+ * This will not be called until after isReady() resolves.
+ * @returns The variables.
+ */
+ provideVariables?(): {
+ currentUserId: string;
+ userDisplayName?: string;
+ userHttpAvatarUrl?: string;
+ clientId?: string;
+ clientTheme?: string;
+ clientLanguage?: string;
+ deviceId?: string;
+ baseUrl?: string;
+ };
+ /**
+ * Resolves to whether or not the customisation point is ready for variables
+ * to be provided. This will block widgets being rendered.
+ * If not provided, the app will assume that the customisation is always ready.
+ * @returns a promise which resolves when ready.
+ */
+ isReady?(): Promise;
+}
+
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
+export type LegacyCustomisations = (customisations: T) => void;
+
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
+export interface LegacyCustomisationsApiExtension {
+ /**
+ * @deprecated in favour of the new Module API
+ */
+ readonly _registerLegacyAliasCustomisations: LegacyCustomisations;
+ /**
+ * @deprecated in favour of the new Module API
+ */
+ readonly _registerLegacyChatExportCustomisations: LegacyCustomisations>;
+ /**
+ * @deprecated in favour of the new Module API
+ */
+ readonly _registerLegacyComponentVisibilityCustomisations: LegacyCustomisations;
+ /**
+ * @deprecated in favour of the new Module API
+ */
+ readonly _registerLegacyDirectoryCustomisations: LegacyCustomisations;
+ /**
+ * @deprecated in favour of the new Module API
+ */
+ readonly _registerLegacyLifecycleCustomisations: LegacyCustomisations;
+ /**
+ * @deprecated in favour of the new Module API
+ */
+ readonly _registerLegacyMediaCustomisations: LegacyCustomisations>;
+ /**
+ * @deprecated in favour of the new Module API
+ */
+ readonly _registerLegacyRoomListCustomisations: LegacyCustomisations>;
+ /**
+ * @deprecated in favour of the new Module API
+ */
+ readonly _registerLegacyUserIdentifierCustomisations: LegacyCustomisations;
+ /**
+ * @deprecated in favour of the new Module API
+ */
+ readonly _registerLegacyWidgetPermissionsCustomisations: LegacyCustomisations<
+ WidgetPermissionsCustomisations
+ >;
+ /**
+ * @deprecated in favour of the new Module API
+ */
+ readonly _registerLegacyWidgetVariablesCustomisations: LegacyCustomisations;
+}
diff --git a/packages/module-api/src/api/legacy-modules.ts b/packages/module-api/src/api/legacy-modules.ts
new file mode 100644
index 0000000000..baaad96b01
--- /dev/null
+++ b/packages/module-api/src/api/legacy-modules.ts
@@ -0,0 +1,30 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore -- optional interface, will gracefully degrade to `any` if `react-sdk-module-api` isn't installed
+import type { ModuleApi, RuntimeModule } from "@matrix-org/react-sdk-module-api";
+
+/**
+ * @alpha
+ * @deprecated in favour of the new module API
+ */
+export type RuntimeModuleConstructor = new (api: ModuleApi) => RuntimeModule;
+
+/**
+ * @alpha
+ * @deprecated in favour of the new module API
+ */
+/* eslint-disable @typescript-eslint/naming-convention */
+export interface LegacyModuleApiExtension {
+ /**
+ * Register a legacy module based on \@matrix-org/react-sdk-module-api
+ * @param LegacyModule - the module class to register
+ * @deprecated provided only as a transition path for legacy modules
+ */
+ _registerLegacyModule(LegacyModule: RuntimeModuleConstructor): Promise;
+}
diff --git a/packages/module-api/src/api/navigation.ts b/packages/module-api/src/api/navigation.ts
new file mode 100644
index 0000000000..76ff59f1c3
--- /dev/null
+++ b/packages/module-api/src/api/navigation.ts
@@ -0,0 +1,59 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { type JSX } from "react";
+
+/**
+ * A function called to render a component when a user navigates to the corresponding
+ * location. Currently renders alongside just the SpacePanel.
+ * @alpha
+ */
+export type LocationRenderFunction = () => JSX.Element;
+
+/**
+ * The options available for changing the open behaviour.
+ * @public
+ */
+export interface OpenRoomOptions {
+ /**
+ * The list of servers to join via.
+ */
+ viaServers?: string[];
+
+ /**
+ * Whether to automatically join the room if we are not already in it.
+ */
+ autoJoin?: boolean;
+}
+
+/**
+ * API methods to navigate the application.
+ * @public
+ */
+export interface NavigationApi {
+ /**
+ * Navigate to a permalink, optionally causing a join if the user is not already a member of the room/space.
+ * @param link - The permalink to navigate to, e.g. `https://matrix.to/#/!roomId:example.com`.
+ * @param join - If true, the user will be made to attempt to join the room/space if they are not already a member.
+ */
+ toMatrixToLink(link: string, join?: boolean): Promise;
+
+ /**
+ * Register a renderer for a given location path.
+ * @param path - The location path to register the renderer for.
+ * @param renderer - The function that will render the component for the location.
+ * @alpha
+ */
+ registerLocationRenderer(path: string, renderer: LocationRenderFunction): void;
+
+ /**
+ * Open a room in element-web.
+ * @param roomIdOrAlias - id/alias of the room to open
+ * @param opts - Options to control the open action, see {@link OpenRoomOptions}
+ */
+ openRoom(roomIdOrAlias: string, opts?: OpenRoomOptions): void;
+}
diff --git a/packages/module-api/src/api/profile.ts b/packages/module-api/src/api/profile.ts
new file mode 100644
index 0000000000..6be444f05f
--- /dev/null
+++ b/packages/module-api/src/api/profile.ts
@@ -0,0 +1,38 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { type Watchable } from "./watchable.ts";
+
+/**
+ * The profile of the user currently logged in.
+ * @public
+ */
+export interface Profile {
+ /**
+ * Indicates whether the user is a guest user.
+ */
+ isGuest?: boolean;
+ /**
+ * The user ID of the logged-in user, if undefined then no user is logged in.
+ */
+ userId?: string;
+ /**
+ * The display name of the logged-in user.
+ */
+ displayName?: string;
+}
+
+/**
+ * API extensions for modules to access the profile of the logged-in user.
+ * @public
+ */
+export interface ProfileApiExtension {
+ /**
+ * The profile of the user currently logged in.
+ */
+ readonly profile: Watchable;
+}
diff --git a/packages/module-api/src/api/stores.ts b/packages/module-api/src/api/stores.ts
new file mode 100644
index 0000000000..9e5bfa252d
--- /dev/null
+++ b/packages/module-api/src/api/stores.ts
@@ -0,0 +1,36 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import type { Room } from "../models/Room";
+import { type Watchable } from "./watchable";
+
+/**
+ * Provides some basic functionality of the Room List Store from element-web.
+ * @public
+ */
+export interface RoomListStoreApi {
+ /**
+ * Returns a watchable holding a flat list of sorted room.
+ */
+ getRooms(): Watchable;
+
+ /**
+ * Returns a promise that resolves when RLS is ready.
+ */
+ waitForReady(): Promise;
+}
+
+/**
+ * Provides access to certain stores from element-web.
+ * @public
+ */
+export interface StoresApi {
+ /**
+ * Use this to access limited functionality of the RLS from element-web.
+ */
+ roomListStore: RoomListStoreApi;
+}
diff --git a/packages/module-api/src/api/watchable.test.ts b/packages/module-api/src/api/watchable.test.ts
new file mode 100644
index 0000000000..e55695c29c
--- /dev/null
+++ b/packages/module-api/src/api/watchable.test.ts
@@ -0,0 +1,99 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { expect, test, vi, vitest } from "vitest";
+
+import { Watchable } from "./watchable";
+
+test("initial value is set correctly", () => {
+ const watchable = new Watchable(42);
+ expect(watchable.value).toBe(42);
+});
+
+test("value can be updated", () => {
+ const watchable = new Watchable(100);
+ watchable.value = 200;
+ expect(watchable.value).toBe(200);
+});
+
+test("watchers are notified on value change", () => {
+ const watchable = new Watchable(1);
+ const listener = vitest.fn();
+
+ watchable.watch(listener);
+ watchable.value = 2; // This should trigger the listener
+ expect(listener).toHaveBeenCalledExactlyOnceWith(2);
+
+ watchable.unwatch(listener); // Clean up after the test
+});
+
+test("watchers are not notified if value does not change", () => {
+ const watchable = new Watchable(10);
+ const listener = vitest.fn();
+
+ watchable.watch(listener);
+ watchable.value = 10; // This should not trigger the listener
+ expect(listener).not.toHaveBeenCalled();
+
+ watchable.unwatch(listener); // Clean up after the test
+});
+
+test("when value is an object, shallow comparison works", () => {
+ const watchable = new Watchable({ a: 1, b: 2 });
+ const listener = vitest.fn();
+ watchable.watch(listener);
+
+ // Update with a new object that has the same properties
+ watchable.value = { a: 3, b: 2 }; // This should trigger the listener
+ expect(listener).toHaveBeenCalledExactlyOnceWith({ a: 3, b: 2 });
+ listener.mockClear();
+ watchable.value = { a: 3, b: 2 }; // This should not trigger the listener again
+ expect(listener).not.toHaveBeenCalled();
+
+ watchable.unwatch(listener); // Clean up after the test
+});
+
+test("onFirstWatch and onLastWatch are called when appropriate", () => {
+ const onFirstWatch = vi.fn();
+ const onLastWatch = vi.fn();
+ class CustomWatchable extends Watchable {
+ protected onFirstWatch(): void {
+ onFirstWatch();
+ }
+ protected onLastWatch(): void {
+ onLastWatch();
+ }
+ }
+
+ const watchable = new CustomWatchable(10);
+ // No listeners yet, so expect no calls
+ expect(onFirstWatch).not.toHaveBeenCalled();
+ expect(onLastWatch).not.toHaveBeenCalled();
+
+ // Let's say that we have three listeners
+ const listeners = [vi.fn(), vi.fn(), vi.fn()];
+
+ // Let's add all of them via watch
+ for (const listener of listeners) {
+ watchable.watch(listener);
+ }
+
+ // Only expect onFirstWatch() to have been called once
+ expect(onFirstWatch).toHaveBeenCalledOnce();
+
+ // Let's remove all the listeners
+ for (const listener of listeners) {
+ watchable.unwatch(listener);
+ }
+
+ // Only expect onLastWatch to have been called once
+ expect(onLastWatch).toHaveBeenCalledOnce();
+
+ // Should call onFirstWatch again once we have more listeners
+ watchable.watch(vi.fn());
+ expect(onFirstWatch).toHaveBeenCalledTimes(2);
+});
diff --git a/packages/module-api/src/api/watchable.ts b/packages/module-api/src/api/watchable.ts
new file mode 100644
index 0000000000..69296571c8
--- /dev/null
+++ b/packages/module-api/src/api/watchable.ts
@@ -0,0 +1,101 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { useEffect, useState } from "react";
+
+type WatchFn = (value: T) => void;
+
+function shallowCompare(obj1: T, obj2: T): boolean {
+ return (
+ Object.keys(obj1).length === Object.keys(obj2).length &&
+ Object.keys(obj1).every((key) => obj1[key as keyof T] === obj2[key as keyof T])
+ );
+}
+
+function isObject(value: unknown): value is object {
+ return value !== null && typeof value === "object";
+}
+
+/**
+ * Utility class to wrap a value and allow listeners to be notified when the value changes.
+ * If T is an object, it will use a shallow comparison to determine if the value has changed.
+ * @public
+ */
+export class Watchable {
+ protected readonly listeners = new Set>();
+
+ public constructor(private currentValue: T) {}
+
+ /**
+ * The value stored in this watchable.
+ * Warning: Could potentially return stale data if you haven't called {@link Watchable#watch}.
+ */
+ public get value(): T {
+ return this.currentValue;
+ }
+
+ public set value(value: T) {
+ // If the value hasn't changed, do nothing.
+ if (value === this.currentValue) {
+ return;
+ }
+ if (isObject(value) && isObject(this.currentValue) && shallowCompare(this.currentValue as object, value)) {
+ return;
+ }
+
+ this.currentValue = value;
+ for (const listener of this.listeners) {
+ listener(this.currentValue);
+ }
+ }
+
+ public watch(listener: (value: T) => void): void {
+ // Call onFirstWatch if there was no listener before.
+ if (this.listeners.size === 0) {
+ this.onFirstWatch();
+ }
+ this.listeners.add(listener);
+ }
+
+ public unwatch(listener: (value: T) => void): void {
+ const hasDeleted = this.listeners.delete(listener);
+ // Call onLastWatch if every listener has been removed.
+ if (hasDeleted && this.listeners.size === 0) {
+ this.onLastWatch();
+ }
+ }
+
+ /**
+ * This is called when the number of listeners go from zero to one.
+ * Could be used to add external event listeners.
+ */
+ protected onFirstWatch(): void {}
+
+ /**
+ * This is called when the number of listeners go from one to zero.
+ * Could be used to remove external event listeners.
+ */
+ protected onLastWatch(): void {}
+}
+
+/**
+ * A React hook to use an updated Watchable value.
+ * @param watchable - The Watchable instance to watch.
+ * @returns The live value of the Watchable.
+ * @public
+ */
+export function useWatchable(watchable: Watchable): T {
+ const [value, setValue] = useState(watchable.value);
+ useEffect(() => {
+ setValue(watchable.value);
+ watchable.watch(setValue);
+ return (): void => {
+ watchable.unwatch(setValue);
+ };
+ }, [watchable]);
+ return value;
+}
diff --git a/packages/module-api/src/api/widget-lifecycle.ts b/packages/module-api/src/api/widget-lifecycle.ts
new file mode 100644
index 0000000000..6258629eab
--- /dev/null
+++ b/packages/module-api/src/api/widget-lifecycle.ts
@@ -0,0 +1,76 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import type { MaybePromise } from "../utils";
+
+/**
+ * A description of a widget passed to approver callbacks.
+ * Contains the information needed to make approval decisions.
+ * @alpha Subject to change.
+ */
+export type WidgetDescriptor = {
+ /** The unique identifier of the widget. */
+ id: string;
+ /** The template URL of the widget, which may contain `$matrix_*` placeholder variables. */
+ templateUrl: string;
+ /** The Matrix user ID of the user who created the widget. */
+ creatorUserId: string;
+ /** The widget type, e.g. `m.custom`, `m.jitsi`, `m.stickerpicker`. */
+ type: string;
+ /** The origin of the widget URL. */
+ origin: string;
+ /** The room ID the widget belongs to, if it is a room widget. */
+ roomId?: string;
+};
+
+/**
+ * Callback that decides whether a widget should be auto-approved for preloading
+ * (i.e. loaded without the user clicking "Continue").
+ * Return `true` to auto-approve, or any other value to defer to the default consent flow.
+ * @alpha Subject to change.
+ */
+export type PreloadApprover = (widget: WidgetDescriptor) => MaybePromise;
+/**
+ * Callback that decides whether a widget should be auto-approved to receive
+ * the user's OpenID identity token.
+ * Return `true` to auto-approve, or any other value to defer to the default consent flow.
+ * @alpha Subject to change.
+ */
+export type IdentityApprover = (widget: WidgetDescriptor) => MaybePromise;
+/**
+ * Callback that decides which of a widget's requested capabilities should be auto-approved.
+ * Return a `Set` of approved capability strings, or `undefined` to defer to the default consent flow.
+ * @alpha Subject to change.
+ */
+export type CapabilitiesApprover = (
+ widget: WidgetDescriptor,
+ requestedCapabilities: Set,
+) => MaybePromise | undefined>;
+
+/**
+ * API for modules to auto-approve widget preloading, identity token requests, and capability requests.
+ * @alpha Subject to change.
+ */
+export interface WidgetLifecycleApi {
+ /**
+ * Register a handler that can auto-approve widget preloading.
+ * Returning true auto-approves; any other value results in no auto-approval.
+ */
+ registerPreloadApprover(approver: PreloadApprover): void;
+
+ /**
+ * Register a handler that can auto-approve identity token requests.
+ * Returning true auto-approves; any other value results in no auto-approval.
+ */
+ registerIdentityApprover(approver: IdentityApprover): void;
+
+ /**
+ * Register a handler that can auto-approve widget capabilities.
+ * Return a set containing the capabilities to approve.
+ */
+ registerCapabilitiesApprover(approver: CapabilitiesApprover): void;
+}
diff --git a/packages/module-api/src/api/widget.ts b/packages/module-api/src/api/widget.ts
new file mode 100644
index 0000000000..66c8b31e73
--- /dev/null
+++ b/packages/module-api/src/api/widget.ts
@@ -0,0 +1,68 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { type IWidget } from "matrix-widget-api";
+
+/**
+ * Containers that control where a widget is displayed on the screen.
+ *
+ * "top" is the app drawer, and currently the only sensible value.
+ *
+ * "right" is the right panel, and the default for widgets. Setting
+ * this as a container on a widget is essentially like saying "no
+ * changes needed", though this may change in the future.
+ *
+ * "center" was uncodumented at time of porting this from an enum.
+ * Possibly when a widget replaces the main chat view like element call.
+ *
+ * @alpha Subject to change.
+ */
+export type Container = "top" | "right" | "center";
+
+/**
+ * An API for interfacing with widgets in Element Web, including getting what widgets
+ * are active in a given room.
+ * @alpha Subject to change.
+ */
+export interface WidgetApi {
+ /**
+ * Gets the widgets active in a given room.
+ *
+ * @param roomId - The room to get the widgets for.
+ */
+ getWidgetsInRoom(roomId: string): IWidget[];
+
+ /**
+ * Gets the URL of a widget's avatar, if it has one.
+ *
+ * @param app - The widget to get the avatar URL for.
+ * @param width - Optional width to resize the avatar to.
+ * @param height - Optional height to resize the avatar to.
+ * @param resizeMethod - Optional method to use when resizing the avatar.
+ * @returns The URL of the widget's avatar, or null if it doesn't have one.
+ */
+ getAppAvatarUrl(app: IWidget, width?: number, height?: number, resizeMethod?: string): string | null;
+
+ /**
+ * Checks if a widget is in a specific container in a given room.
+ *
+ * @param app - The widget to check.
+ * @param container - The container to check.
+ * @param roomId - The room to check in.
+ * @returns True if the widget is in the specified container, false otherwise.
+ */
+ isAppInContainer(app: IWidget, container: Container, roomId: string): boolean;
+
+ /**
+ * Moves a widget to a specific container in a given room.
+ *
+ * @param app - The widget to move.
+ * @param container - The container to move the widget to.
+ * @param roomId - The room to move the widget in.
+ */
+ moveAppToContainer(app: IWidget, container: Container, roomId: string): void;
+}
diff --git a/packages/module-api/src/index.ts b/packages/module-api/src/index.ts
new file mode 100644
index 0000000000..a246b12f9e
--- /dev/null
+++ b/packages/module-api/src/index.ts
@@ -0,0 +1,30 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+export { ModuleLoader, ModuleIncompatibleError } from "./loader";
+export type { Api, Module, ModuleFactory } from "./api";
+export type { Config, ConfigApi } from "./api/config";
+export type { I18nApi, Variables, Translations, SubstitutionValue, Tags } from "./api/i18n";
+export type * from "./models/event";
+export type * from "./models/Room";
+export type * from "./api/custom-components";
+export type * from "./api/extras";
+export type * from "./api/legacy-modules";
+export type * from "./api/legacy-customisations";
+export type * from "./api/auth";
+export type * from "./api/dialog";
+export type * from "./api/profile";
+export type * from "./api/navigation";
+export type * from "./api/builtins";
+export type * from "./api/stores";
+export type * from "./api/client";
+export type * from "./api/widget-lifecycle";
+export type * from "./api/widget";
+export type * from "./api/customisations";
+export { UIComponent } from "./api/customisations";
+export * from "./api/watchable";
+export type * from "./utils";
diff --git a/packages/module-api/src/loader.test.ts b/packages/module-api/src/loader.test.ts
new file mode 100644
index 0000000000..8010c72af4
--- /dev/null
+++ b/packages/module-api/src/loader.test.ts
@@ -0,0 +1,58 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { expect, test, describe, vi, beforeEach } from "vitest";
+
+import { type Api, ModuleIncompatibleError, ModuleLoader } from ".";
+
+describe("ModuleIncompatibleError", () => {
+ test("should extend Error", () => {
+ expect(new ModuleIncompatibleError("1.0.0")).toBeInstanceOf(Error);
+ });
+});
+
+describe("ModuleLoader", () => {
+ const mockApi = {} as Api;
+
+ beforeEach(() => {
+ vi.stubGlobal("__VERSION__", "1.0.1");
+ });
+
+ test("should load a module", async () => {
+ const TestModule = {
+ default: class TestModule {
+ public static moduleApiVersion = "^1.0.0";
+ public constructor(private readonly api: Api) {}
+ public async load(): Promise {}
+ },
+ };
+
+ const spy = vi.spyOn(TestModule.default.prototype, "load");
+
+ const loader = new ModuleLoader(mockApi);
+ await loader.load(TestModule);
+ await loader.start();
+ expect(spy).toHaveBeenCalledWith();
+ });
+
+ test("should fail to load an incompatible module", async () => {
+ const TestModule = {
+ default: class TestModule {
+ public static moduleApiVersion = "^2";
+ public constructor(private readonly api: Api) {}
+ public async load(): Promise {}
+ },
+ };
+
+ const spy = vi.spyOn(TestModule.default.prototype, "load");
+
+ const loader = new ModuleLoader(mockApi);
+ await expect(loader.load(TestModule)).rejects.toThrowError(ModuleIncompatibleError);
+ await loader.start();
+ expect(spy).not.toHaveBeenCalledWith();
+ });
+});
diff --git a/packages/module-api/src/loader.ts b/packages/module-api/src/loader.ts
new file mode 100644
index 0000000000..c057109f28
--- /dev/null
+++ b/packages/module-api/src/loader.ts
@@ -0,0 +1,55 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { satisfies } from "semver";
+
+import { type Api, isModule, type Module, type ModuleExport } from "./api";
+
+/**
+ * Error thrown when a module is incompatible with the engine version.
+ * @public
+ */
+export class ModuleIncompatibleError extends Error {
+ public constructor(pluginVersion: string) {
+ super(`Plugin version ${pluginVersion} is incompatible with engine version ${__VERSION__}`);
+ }
+}
+
+/**
+ * A module loader for loading and starting modules.
+ * @public
+ */
+export class ModuleLoader {
+ private modules: Module[] = [];
+ private started = false;
+
+ public constructor(private api: Api) {}
+
+ public async load(moduleExport: ModuleExport): Promise {
+ if (this.started) {
+ throw new Error("PluginEngine.start() has already been called");
+ }
+
+ if (!isModule(moduleExport)) {
+ throw new Error("Invalid plugin");
+ }
+ if (!satisfies(__VERSION__, moduleExport.default.moduleApiVersion)) {
+ throw new ModuleIncompatibleError(moduleExport.default.moduleApiVersion);
+ }
+ const { default: Module } = moduleExport;
+ this.modules.push(new Module(this.api));
+ }
+
+ public async start(): Promise {
+ if (this.started) {
+ throw new Error("PluginEngine.start() has already been called");
+ }
+ this.started = true;
+
+ await Promise.all(this.modules.map((plugin) => plugin.load()));
+ }
+}
diff --git a/packages/module-api/src/models/Room.ts b/packages/module-api/src/models/Room.ts
new file mode 100644
index 0000000000..eb67d8054e
--- /dev/null
+++ b/packages/module-api/src/models/Room.ts
@@ -0,0 +1,28 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { type Watchable } from "../api/watchable";
+
+/**
+ * Represents a room from element-web.
+ * @public
+ */
+export interface Room {
+ /**
+ * Id of this room.
+ */
+ id: string;
+ /**
+ * {@link Watchable} holding the name for this room.
+ */
+ name: Watchable;
+ /**
+ * Get the timestamp of the last message in this room.
+ * @returns last active timestamp
+ */
+ getLastActiveTimestamp: () => number;
+}
diff --git a/packages/module-api/src/models/event.ts b/packages/module-api/src/models/event.ts
new file mode 100644
index 0000000000..b75606090e
--- /dev/null
+++ b/packages/module-api/src/models/event.ts
@@ -0,0 +1,48 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+/**
+ * Representation of a Matrix event, as specified by the client server specification.
+ * @alpha Subject to change.
+ * @see https://spec.matrix.org/v1.14/client-server-api/#room-event-format
+ */
+export interface MatrixEvent {
+ /**
+ * The event ID of this event.
+ */
+ eventId: string;
+ /**
+ * The room ID which contains this event.
+ */
+ roomId: string;
+ /**
+ * The Matrix ID of the user who sent this event.
+ */
+ sender: string;
+ /**
+ * The content of the event.
+ * If the event was encrypted, this is the decrypted content.
+ */
+ content: Record;
+ /**
+ * Contains optional extra information about the event.
+ */
+ unsigned: Record;
+ /**
+ * The type of the event.
+ */
+ type: string;
+ /**
+ * The state key of the event.
+ * If this key is set, including `""` then the event is a state event.
+ */
+ stateKey?: string;
+ /**
+ * Timestamp (in milliseconds since the unix epoch) on originating homeserver when this event was sent.
+ */
+ originServerTs: number;
+}
diff --git a/packages/module-api/src/utils.ts b/packages/module-api/src/utils.ts
new file mode 100644
index 0000000000..8692b180c8
--- /dev/null
+++ b/packages/module-api/src/utils.ts
@@ -0,0 +1,13 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+/**
+ * A value that may be a direct value or a Promise resolving to that value.
+ * Useful for callback APIs that can operate synchronously or asynchronously.
+ * @public
+ */
+export type MaybePromise = T | PromiseLike;
diff --git a/packages/module-api/tsconfig.json b/packages/module-api/tsconfig.json
new file mode 100644
index 0000000000..b8136d3517
--- /dev/null
+++ b/packages/module-api/tsconfig.json
@@ -0,0 +1,18 @@
+{
+ "$schema": "http://json.schemastore.org/tsconfig",
+ "compilerOptions": {
+ "target": "esnext",
+ "lib": ["dom", "es2022", "esnext"],
+ "esModuleInterop": true,
+ "strict": true,
+ "declaration": true,
+ "module": "es2022",
+ "moduleResolution": "bundler",
+ "types": [],
+ "outDir": "lib",
+ "jsx": "react-jsx",
+ "declarationMap": true,
+ "allowImportingTsExtensions": true
+ },
+ "include": ["src"]
+}
diff --git a/packages/module-api/vite.config.ts b/packages/module-api/vite.config.ts
new file mode 100644
index 0000000000..61f8fc5389
--- /dev/null
+++ b/packages/module-api/vite.config.ts
@@ -0,0 +1,59 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vite";
+import dts from "vite-plugin-dts";
+import externalGlobals from "rollup-plugin-external-globals";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+ build: {
+ lib: {
+ entry: resolve(__dirname, "src/index.ts"),
+ name: "element-web-plugin-engine",
+ fileName: "element-web-plugin-engine",
+ },
+ outDir: "lib",
+ target: "esnext",
+ sourcemap: true,
+ },
+ plugins: [
+ dts(),
+ externalGlobals({
+ // Reuse React from the host app
+ react: "window.React",
+ }),
+ ],
+ define: {
+ __VERSION__: JSON.stringify(process.env.npm_package_version),
+ // Use production mode for the build as it is tested against production builds of Element Web,
+ // this is required for React JSX versions to be compatible.
+ process: { env: { NODE_ENV: "production" } },
+ },
+ test: {
+ coverage: {
+ provider: "v8",
+ include: ["src/**/*"],
+ reporter: [["lcov", { projectRoot: "../../" }]],
+ },
+ reporters: [
+ ["default", { summary: false }],
+ [
+ "vitest-sonar-reporter",
+ {
+ outputFile: "coverage/sonar-report.xml",
+ onWritePath(path: string): string {
+ return `packages/element-web-module-api/${path}`;
+ },
+ },
+ ],
+ ],
+ },
+});
diff --git a/packages/playwright-common/package.json b/packages/playwright-common/package.json
index 46a11f94a2..9aa51eef68 100644
--- a/packages/playwright-common/package.json
+++ b/packages/playwright-common/package.json
@@ -19,10 +19,10 @@
},
"scripts": {
"prepack": "nx build:playwright",
- "lint:types": "tsc --noEmit"
+ "lint:types": "nx lint:types"
},
"devDependencies": {
- "@element-hq/element-web-module-api": "*",
+ "@element-hq/element-web-module-api": "workspace:*",
"@types/lodash-es": "^4.17.12",
"typescript": "^5.8.2",
"wait-on": "^9.0.4"
diff --git a/packages/playwright-common/project.json b/packages/playwright-common/project.json
index b3e491b9d6..bf6ef190c2 100644
--- a/packages/playwright-common/project.json
+++ b/packages/playwright-common/project.json
@@ -8,7 +8,13 @@
"command": "tsc",
"inputs": ["src"],
"outputs": ["{projectRoot}/lib"],
- "options": { "cwd": "packages/playwright-common" }
+ "options": { "cwd": "packages/playwright-common" },
+ "dependsOn": ["^build"]
+ },
+ "lint:types": {
+ "command": "pnpm exec tsc --noEmit",
+ "options": { "cwd": "packages/playwright-common" },
+ "dependsOn": ["^build"]
},
"docker:prebuild": {
"cache": true,
diff --git a/packages/shared-components/package.json b/packages/shared-components/package.json
index 29a3ded4d6..2cfe4a0fab 100644
--- a/packages/shared-components/package.json
+++ b/packages/shared-components/package.json
@@ -51,7 +51,7 @@
"lint:types": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json"
},
"dependencies": {
- "@element-hq/element-web-module-api": "catalog:",
+ "@element-hq/element-web-module-api": "workspace:*",
"@matrix-org/spec": "^1.7.0",
"@vector-im/compound-design-tokens": "catalog:",
"classnames": "^2.5.1",
diff --git a/packages/shared-components/project.json b/packages/shared-components/project.json
index 0c9dc50527..b4401cc5a0 100644
--- a/packages/shared-components/project.json
+++ b/packages/shared-components/project.json
@@ -7,7 +7,8 @@
"command": "vite build",
"inputs": ["src"],
"outputs": ["{projectRoot}/dist"],
- "options": { "cwd": "packages/shared-components" }
+ "options": { "cwd": "packages/shared-components" },
+ "dependsOn": ["^build"]
},
"start": {
"command": "vite build --watch",
@@ -19,7 +20,8 @@
"command": "typedoc",
"inputs": ["src"],
"outputs": ["{projectRoot}/typedoc"],
- "options": { "cwd": "packages/shared-components" }
+ "options": { "cwd": "packages/shared-components" },
+ "dependsOn": ["^build"]
},
"storybook": {
"cache": "true",
diff --git a/packages/shared-components/src/room/HistoryVisibilityBadge/__snapshots__/HistoryVisibilityBadge.test.tsx.snap b/packages/shared-components/src/room/HistoryVisibilityBadge/__snapshots__/HistoryVisibilityBadge.test.tsx.snap
index e284eb7a51..51459abcdc 100644
--- a/packages/shared-components/src/room/HistoryVisibilityBadge/__snapshots__/HistoryVisibilityBadge.test.tsx.snap
+++ b/packages/shared-components/src/room/HistoryVisibilityBadge/__snapshots__/HistoryVisibilityBadge.test.tsx.snap
@@ -3,7 +3,7 @@
exports[`HistoryVisibilityBadge > renders the badge for invited 1`] = `