Support for custom message components via Module API

package.json

@@ -81,7 +81,7 @@
     },
     "dependencies": {
         "@babel/runtime": "^7.12.5",
-        "@element-hq/element-web-module-api": "1.0.0",
+        "@element-hq/element-web-module-api": "1.2.0",
         "@fontsource/inconsolata": "^5",
         "@fontsource/inter": "^5",
         "@formatjs/intl-segmenter": "^11.5.7",

playwright/e2e/modules/custom-component.spec.ts

@@ -0,0 +1,112 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { type Page } from "@playwright/test";
+
+import { test, expect } from "../../element-web-test";
+
+const screenshotOptions = (page: Page) => ({
+    mask: [page.locator(".mx_MessageTimestamp")],
+    // Hide the jump to bottom button in the timeline to avoid flakiness
+    // Exclude timestamp and read marker from snapshot
+    css: `
+        .mx_JumpToBottomButton {
+            display: none !important;
+        }
+        .mx_TopUnreadMessagesBar, .mx_MessagePanel_myReadMarker {
+            display: none !important;
+        }
+    `,
+});
+test.describe("Custom Component API", () => {
+    test.use({
+        displayName: "Manny",
+        config: {
+            modules: ["/modules/custom-component-module.js"],
+        },
+        page: async ({ page }, use) => {
+            await page.route("/modules/custom-component-module.js", async (route) => {
+                await route.fulfill({ path: "playwright/sample-files/custom-component-module.js" });
+            });
+            await use(page);
+        },
+        room: async ({ page, app, user, bot }, use) => {
+            const roomId = await app.client.createRoom({ name: "TestRoom" });
+            await use({ roomId });
+        },
+    });
+    test.describe("basic functionality", () => {
+        test(
+            "should replace the render method of a textual event",
+            { tag: "@screenshot" },
+            async ({ page, room, app }) => {
+                await app.viewRoomById(room.roomId);
+                await app.client.sendMessage(room.roomId, "Simple message");
+                await expect(await page.locator(".mx_EventTile_last")).toMatchScreenshot(
+                    "custom-component-tile.png",
+                    screenshotOptions(page),
+                );
+            },
+        );
+        test(
+            "should fall through if one module does not render a component",
+            { tag: "@screenshot" },
+            async ({ page, room, app }) => {
+                await app.viewRoomById(room.roomId);
+                await app.client.sendMessage(room.roomId, "Fall through here");
+                await expect(await page.locator(".mx_EventTile_last")).toMatchScreenshot(
+                    "custom-component-tile-fall-through.png",
+                    screenshotOptions(page),
+                );
+            },
+        );
+        test(
+            "should render the original content of a textual event conditionally",
+            { tag: "@screenshot" },
+            async ({ page, room, app }) => {
+                await app.viewRoomById(room.roomId);
+                await app.client.sendMessage(room.roomId, "Do not replace me");
+                await expect(await page.locator(".mx_EventTile_last")).toMatchScreenshot(
+                    "custom-component-tile-original.png",
+                    screenshotOptions(page),
+                );
+            },
+        );
+        test("should disallow editing when the allowEditingEvent hint is set to false", async ({ page, room, app }) => {
+            await app.viewRoomById(room.roomId);
+            await app.client.sendMessage(room.roomId, "Do not show edits");
+            await page.getByText("Do not show edits").hover();
+            await expect(
+                await page.getByRole("toolbar", { name: "Message Actions" }).getByRole("button", { name: "Edit" }),
+            ).not.toBeVisible();
+        });
+        test(
+            "should render the next registered component if the filter function throws",
+            { tag: "@screenshot" },
+            async ({ page, room, app }) => {
+                await app.viewRoomById(room.roomId);
+                await app.client.sendMessage(room.roomId, "Crash the filter!");
+                await expect(await page.locator(".mx_EventTile_last")).toMatchScreenshot(
+                    "custom-component-crash-handle-filter.png",
+                    screenshotOptions(page),
+                );
+            },
+        );
+        test(
+            "should render original component if the render function throws",
+            { tag: "@screenshot" },
+            async ({ page, room, app }) => {
+                await app.viewRoomById(room.roomId);
+                await app.client.sendMessage(room.roomId, "Crash the renderer!");
+                await expect(await page.locator(".mx_EventTile_last")).toMatchScreenshot(
+                    "custom-component-crash-handle-renderer.png",
+                    screenshotOptions(page),
+                );
+            },
+        );
+    });
+});

playwright/sample-files/custom-component-module.js

@@ -0,0 +1,55 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+export default class CustomComponentModule {
+    static moduleApiVersion = "^1.2.0";
+    constructor(api) {
+        this.api = api;
+        this.api.customComponents.registerMessageRenderer(
+            (evt) => evt.content.body === "Do not show edits",
+            (_props, originalComponent) => {
+                return originalComponent();
+            },
+            { allowEditingEvent: false },
+        );
+        this.api.customComponents.registerMessageRenderer(
+            (evt) => evt.content.body === "Fall through here",
+            (props) => {
+                const body = props.mxEvent.content.body;
+                return `Fallthrough text for ${body}`;
+            },
+        );
+        this.api.customComponents.registerMessageRenderer(
+            (evt) => {
+                if (evt.content.body === "Crash the filter!") {
+                    throw new Error("Fail test!");
+                }
+                return false;
+            },
+            () => {
+                return `Should not render!`;
+            },
+        );
+        this.api.customComponents.registerMessageRenderer(
+            (evt) => evt.content.body === "Crash the renderer!",
+            () => {
+                throw new Error("Fail test!");
+            },
+        );
+        // Order is specific here to avoid this overriding the other renderers
+        this.api.customComponents.registerMessageRenderer("m.room.message", (props, originalComponent) => {
+            const body = props.mxEvent.content.body;
+            if (body === "Do not replace me") {
+                return originalComponent();
+            } else if (body === "Fall through here") {
+                return null;
+            }
+            return `Custom text for ${body}`;
+        });
+    }
+    async load() {}
+}

src/events/EventTileFactory.tsx

@@ -43,6 +43,7 @@ import ViewSourceEvent from "../components/views/messages/ViewSourceEvent";
 import { shouldDisplayAsBeaconTile } from "../utils/beacon/timeline";
 import { ElementCall } from "../models/Call";
 import { type IBodyProps } from "../components/views/messages/IBodyProps";
+import ModuleApi from "../modules/Api";
 
 // Subset of EventTile's IProps plus some mixins
 export interface EventTileTypeProps
@@ -257,7 +258,14 @@ export function renderTile(
     cli = cli ?? MatrixClientPeg.safeGet(); // because param defaults don't do the correct thing
 
     const factory = pickFactory(props.mxEvent, cli, showHiddenEvents);
-    if (!factory) return undefined;
+    if (!factory) {
+        // If we don't have a factory for this event, attempt
+        // to find a custom component that can render it.
+        // Will return null if no custom component can render it.
+        return ModuleApi.customComponents.renderMessage({
+            mxEvent: props.mxEvent,
+        });
+    }
 
     // Note that we split off the ones we actually care about here just to be sure that we're
     // not going to accidentally send things we shouldn't from lazy callers. Eg: EventTile's
@@ -284,36 +292,48 @@ export function renderTile(
         case TimelineRenderingType.File:
         case TimelineRenderingType.Notification:
         case TimelineRenderingType.Thread:
-            // We only want a subset of props, so we don't end up causing issues for downstream components.
-            return factory(props.ref, {
-                mxEvent,
-                highlights,
-                highlightLink,
-                showUrlPreview,
-                editState,
-                replacingEventId,
-                getRelationsForEvent,
-                isSeeingThroughMessageHiddenForModeration,
-                permalinkCreator,
-                inhibitInteraction,
-            });
+            return ModuleApi.customComponents.renderMessage(
+                {
+                    mxEvent: props.mxEvent,
+                },
+                (origProps) =>
+                    factory(props.ref, {
+                        // We only want a subset of props, so we don't end up causing issues for downstream components.
+                        mxEvent,
+                        highlights,
+                        highlightLink,
+                        showUrlPreview: origProps?.showUrlPreview ?? showUrlPreview,
+                        editState,
+                        replacingEventId,
+                        getRelationsForEvent,
+                        isSeeingThroughMessageHiddenForModeration,
+                        permalinkCreator,
+                        inhibitInteraction,
+                    }),
+            );
         default:
-            // NEARLY ALL THE OPTIONS!
-            return factory(ref, {
-                mxEvent,
-                forExport,
-                replacingEventId,
-                editState,
-                highlights,
-                highlightLink,
-                showUrlPreview,
-                permalinkCreator,
-                callEventGrouper,
-                getRelationsForEvent,
-                isSeeingThroughMessageHiddenForModeration,
-                timestamp,
-                inhibitInteraction,
-            });
+            return ModuleApi.customComponents.renderMessage(
+                {
+                    mxEvent: props.mxEvent,
+                },
+                (origProps) =>
+                    factory(ref, {
+                        // NEARLY ALL THE OPTIONS!
+                        mxEvent,
+                        forExport,
+                        replacingEventId,
+                        editState,
+                        highlights,
+                        highlightLink,
+                        showUrlPreview: origProps?.showUrlPreview ?? showUrlPreview,
+                        permalinkCreator,
+                        callEventGrouper,
+                        getRelationsForEvent,
+                        isSeeingThroughMessageHiddenForModeration,
+                        timestamp,
+                        inhibitInteraction,
+                    }),
+            );
     }
 }
 
@@ -332,7 +352,14 @@ export function renderReplyTile(
     cli = cli ?? MatrixClientPeg.safeGet(); // because param defaults don't do the correct thing
 
     const factory = pickFactory(props.mxEvent, cli, showHiddenEvents);
-    if (!factory) return undefined;
+    if (!factory) {
+        // If we don't have a factory for this event, attempt
+        // to find a custom component that can render it.
+        // Will return null if no custom component can render it.
+        return ModuleApi.customComponents.renderMessage({
+            mxEvent: props.mxEvent,
+        });
+    }
 
     // See renderTile() for why we split off so much
     const {
@@ -350,19 +377,25 @@ export function renderReplyTile(
         permalinkCreator,
     } = props;
 
-    return factory(ref, {
-        mxEvent,
-        highlights,
-        highlightLink,
-        showUrlPreview,
-        overrideBodyTypes,
-        overrideEventTypes,
-        replacingEventId,
-        maxImageHeight,
-        getRelationsForEvent,
-        isSeeingThroughMessageHiddenForModeration,
-        permalinkCreator,
-    });
+    return ModuleApi.customComponents.renderMessage(
+        {
+            mxEvent: props.mxEvent,
+        },
+        (origProps) =>
+            factory(ref, {
+                mxEvent,
+                highlights,
+                highlightLink,
+                showUrlPreview: origProps?.showUrlPreview ?? showUrlPreview,
+                overrideBodyTypes,
+                overrideEventTypes,
+                replacingEventId,
+                maxImageHeight,
+                getRelationsForEvent,
+                isSeeingThroughMessageHiddenForModeration,
+                permalinkCreator,
+            }),
+    );
 }
 
 // XXX: this'll eventually be dynamic based on the fields once we have extensible event types
@@ -386,6 +419,12 @@ export function haveRendererForEvent(
         return false;
     }
 
+    // Check to see if we have any hints for this message, which indicates
+    // there is a custom renderer for the event.
+    if (ModuleApi.customComponents.getHintsForMessage(mxEvent)) {
+        return true;
+    }
+
     // No tile for replacement events since they update the original tile
     if (mxEvent.isRelation(RelationType.Replace)) return false;
 

src/modules/Api.ts

@@ -6,8 +6,8 @@ Please see LICENSE files in the repository root for full details.
 */
 
 import { createRoot, type Root } from "react-dom/client";
+import { type Api, type RuntimeModuleConstructor } from "@element-hq/element-web-module-api";
 
-import type { Api, RuntimeModuleConstructor } from "@element-hq/element-web-module-api";
 import { ModuleRunner } from "./ModuleRunner.ts";
 import AliasCustomisations from "../customisations/Alias.ts";
 import { RoomListCustomisations } from "../customisations/RoomList.ts";
@@ -21,6 +21,7 @@ import { WidgetPermissionCustomisations } from "../customisations/WidgetPermissi
 import { WidgetVariableCustomisations } from "../customisations/WidgetVariables.ts";
 import { ConfigApi } from "./ConfigApi.ts";
 import { I18nApi } from "./I18nApi.ts";
+import { CustomComponentsApi } from "./customComponentApi.ts";
 
 const legacyCustomisationsFactory = <T extends object>(baseCustomisations: T) => {
     let used = false;
@@ -58,6 +59,7 @@ class ModuleApi implements Api {
 
     public readonly config = new ConfigApi();
     public readonly i18n = new I18nApi();
+    public readonly customComponents = new CustomComponentsApi();
     public readonly rootNode = document.getElementById("matrixchat")!;
 
     public createRoot(element: Element): Root {