Merge pull request #198 from element-hq/langleyd/widget-lifecycle-module-api

Widget lifecycle module api

packages/element-web-module-api/src/api/index.ts

@@ -19,6 +19,7 @@ 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";
 
 /**
  * Module interface for modules to implement.
@@ -136,6 +137,12 @@ export interface Api
      */
     readonly client: ClientApi;
 
+    /**
+     * API for modules to auto-approve widget preloading, identity token requests, and capability requests.
+     * @alpha Subject to change.
+     */
+    readonly widgetLifecycle: WidgetLifecycleApi;
+
     /**
      * Create a ReactDOM root for rendering React components.
      * Exposed to allow modules to avoid needing to bundle their own ReactDOM.

packages/element-web-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<boolean | undefined>;
+/**
+ * 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<boolean | undefined>;
+/**
+ * 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<string>,
+) => MaybePromise<Set<string> | 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;
+}

packages/element-web-module-api/src/index.ts

@@ -22,4 +22,6 @@ 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 * from "./api/watchable";
+export type * from "./utils";

packages/element-web-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> = T | PromiseLike<T>;