From 6b0f8f158fbeb58f95be71958d7adcf24698bab0 Mon Sep 17 00:00:00 2001
From: David Langley <langley.dave@gmail.com>
Date: Thu, 9 Apr 2026 20:30:37 +0100
Subject: [PATCH] Add an api to brand the window title

---
 .../element-web-module-api.api.md             | 19 ++++++
 .../element-web-module-api/src/api/brand.ts   | 64 +++++++++++++++++++
 .../element-web-module-api/src/api/index.ts   |  7 ++
 packages/element-web-module-api/src/index.ts  |  1 +
 4 files changed, 91 insertions(+)
 create mode 100644 packages/element-web-module-api/src/api/brand.ts

diff --git a/packages/element-web-module-api/element-web-module-api.api.md b/packages/element-web-module-api/element-web-module-api.api.md
index 74194eb5..50084c29 100644
--- a/packages/element-web-module-api/element-web-module-api.api.md
+++ b/packages/element-web-module-api/element-web-module-api.api.md
@@ -44,6 +44,7 @@ export interface AliasCustomisations {
 //
 // @public
 export interface Api extends LegacyModuleApiExtension, LegacyCustomisationsApiExtension, DialogApiExtension, AccountAuthApiExtension, ProfileApiExtension {
+    readonly brand: BrandApi;
     // @alpha
     readonly builtins: BuiltinsApi;
     readonly client: ClientApi;
@@ -65,6 +66,11 @@ export interface Api extends LegacyModuleApiExtension, LegacyCustomisationsApiEx
     readonly widgetLifecycle: WidgetLifecycleApi;
 }
 
+// @public
+export interface BrandApi {
+    registerTitleRenderer(renderFunction: TitleRenderFunction): void;
+}
+
 // @alpha
 export interface BuiltinsApi {
     renderNotificationDecoration(roomId: string): React.ReactNode;
@@ -446,6 +452,19 @@ export type SubstitutionValue = number | string | ReactNode | ((sub: string) =>
 // @public
 export type Tags = Record<string, SubstitutionValue>;
 
+// @public
+export type TitleRenderFunction = (opts: TitleRenderOptions) => string;
+
+// @public
+export type TitleRenderOptions = {
+    brand: string;
+    notificationCount?: number;
+    hasActivity?: boolean;
+    statusText?: string;
+    roomId?: string;
+    roomName?: string;
+};
+
 // @public
 export type Translations = Record<string, {
     [ietfLanguageTag: string]: string;
diff --git a/packages/element-web-module-api/src/api/brand.ts b/packages/element-web-module-api/src/api/brand.ts
new file mode 100644
index 00000000..b7b84beb
--- /dev/null
+++ b/packages/element-web-module-api/src/api/brand.ts
@@ -0,0 +1,64 @@
+/*
+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.
+*/
+
+/**
+ * Options provided to the title render function representing the current application state.
+ * @public
+ */
+export type TitleRenderOptions = {
+    /**
+     * The configured brand name (e.g. "Element", "Element Pro").
+     */
+    brand: string;
+    /**
+     * The number of rooms with unread notifications.
+     */
+    notificationCount?: number;
+    /**
+     * Whether there is unread activity (but below notification threshold).
+     */
+    hasActivity?: boolean;
+    /**
+     * Translated status text from the host application, if applicable
+     * (e.g. "Offline"). Undefined when there is no status.
+     */
+    statusText?: string;
+    /**
+     * The current room ID, if a room is open.
+     */
+    roomId?: string;
+    /**
+     * The current room name, if a room is open.
+     */
+    roomName?: string;
+};
+
+/**
+ * Function to render the window title.
+ * @public
+ * @param opts - Current state of the client.
+ * @returns The text to be rendered as the document title.
+ */
+export type TitleRenderFunction = (opts: TitleRenderOptions) => string;
+
+/**
+ * API for modules to customise application branding.
+ * @public
+ */
+export interface BrandApi {
+    /**
+     * Register a function to render the window title. This function will be called whenever
+     * the application needs to re-render the title of the browser window.
+     *
+     * Only one module may register a title renderer. If another module has already registered
+     * one, this will throw.
+     *
+     * @param renderFunction - The function to use to render the title.
+     * @throws If another module has already registered a title renderer.
+     */
+    registerTitleRenderer(renderFunction: TitleRenderFunction): void;
+}
diff --git a/packages/element-web-module-api/src/api/index.ts b/packages/element-web-module-api/src/api/index.ts
index 3d60fc2a..1c41e7c9 100644
--- a/packages/element-web-module-api/src/api/index.ts
+++ b/packages/element-web-module-api/src/api/index.ts
@@ -23,6 +23,7 @@ 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";
+import { type BrandApi } from "./brand.ts";
 
 /**
  * Module interface for modules to implement.
@@ -112,6 +113,12 @@ export interface Api
      */
     readonly customComponents: CustomComponentsApi;
 
+    /**
+     * The branding API for customising window titles.
+     * @public
+     */
+    readonly brand: BrandApi;
+
     /**
      * Allows modules to render components that are part of Element Web.
      * @alpha
diff --git a/packages/element-web-module-api/src/index.ts b/packages/element-web-module-api/src/index.ts
index a246b12f..2c0ee430 100644
--- a/packages/element-web-module-api/src/index.ts
+++ b/packages/element-web-module-api/src/index.ts
@@ -12,6 +12,7 @@ export type { I18nApi, Variables, Translations, SubstitutionValue, Tags } from "
 export type * from "./models/event";
 export type * from "./models/Room";
 export type * from "./api/custom-components";
+export type * from "./api/brand";
 export type * from "./api/extras";
 export type * from "./api/legacy-modules";
 export type * from "./api/legacy-customisations";