Tidy up

2026-03-13 16:19:27 +00:00
parent 610a9494d1
commit c058c187c4
6 changed files with 22 additions and 19 deletions
@@ -1,4 +1,13 @@
-<!-- Based on element-modules/modules/opendesk/element-web/tests/fixture/widget.html -->
+<!--
+    Minimal fixture widget used by e2e tests to exercise the Matrix Widget API lifecycle:
+      1. Element requests capabilities  → widget declares what it needs
+      2. Element notifies approval      → widget requests an OpenID token
+      3. Element grants the token       → widget resolves the user's Matrix ID and displays it
+
+    The `caps` query parameter controls which capabilities the widget requests (comma-separated).
+    Pass `caps=none` to request none. Defaults to m.room.topic if omitted.
+    The `hsUrl` query parameter is required for the OpenID userinfo lookup in step 3.
+-->
 <!doctype html>
 <html lang="en">
    <head>
@@ -19,6 +28,7 @@
            let sendEventCount = 0;
            window.onmessage = async (ev) => {
                if (ev.data.action === "capabilities") {
+                    // Step 1: Element is asking what capabilities this widget needs.
                    window.parent.postMessage(
                        Object.assign(
                            {
@@ -31,6 +41,8 @@
                        "*",
                    );
                } else if (ev.data.action === "notify_capabilities") {
+                    // Step 2: Capabilities have been approved. Request an OpenID token
+                    // so we can identify the current user in step 3.
                    window.parent.postMessage(
                        {
                            api: "fromWidget",
@@ -42,6 +54,8 @@
                        "*",
                    );
                } else if (ev.data.action === "get_openid" && ev.data.response?.state === "allowed") {
+                    // Step 3: Token granted — exchange it for the user's Matrix ID and display it.
+                    // Tests assert on this heading to verify identity was passed through correctly.
                    const { access_token } = ev.data.response;

                    const hsUrl = new URLSearchParams(window.location.search).get("hsUrl");