Merge 1d7846b0f9 into 48051c3450

Signed-off-by: Andy Balaam <andy.balaam@matrix.org>
Co-authored-by: Tulir Asokan <tulir@maunium.net>
Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com>

.github/workflows/main.yml

@@ -1,7 +1,7 @@
 name: "Spec"
 
 env:
-  HUGO_VERSION: 0.153.3
+  HUGO_VERSION: 0.155.3
   PYTHON_VERSION: 3.13
   NODE_VERSION: 24
 

README.md

@@ -61,7 +61,7 @@ place after an MSC has been accepted, not as part of a proposal itself.
 
 1. Install the extended version (often the OS default) of Hugo:
    <https://gohugo.io/getting-started/installing>. Note that at least Hugo
-   v0.146.0 is required.
+   v0.155.0 is required.
 
    Alternatively, use the Docker image at
    https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required

changelogs/client_server/newsfragments/2345.feature

@@ -0,0 +1 @@
+Specify `unsigned.replaces_state` in client-formatted events. Contributed by @nexy7574.

changelogs/client_server/newsfragments/2352.clarification

@@ -0,0 +1 @@
+Clarify how to find `via` parameter when following room upgrades.

changelogs/client_server/newsfragments/2354.feature

@@ -0,0 +1 @@
+Specify `m.key_backup` account data, as per [MSC4287](https://github.com/matrix-org/matrix-spec-proposals/pull/4287).

changelogs/client_server/newsfragments/2357.clarification

@@ -0,0 +1,11 @@
+Fixes a typo in `/rooms/{roomId}/relations/{eventId}`.
+
+The specification says about the `from` request query parameter:
+
+> The pagination token to start returning results from. If not supplied, results start at the most recent topological event known to the server.
+>
+> Can be a `next_batch` or `prev_batch` token from a previous call, or a returned `start` token from `/messages`, or a `next_batch` token from `/sync`.
+
+The last part is wrong. It should be:
+
+> … or a `prev_batch` token from `/sync`.

changelogs/internal/newsfragments/2346.clarification

@@ -0,0 +1 @@
+Upgrade Docsy theme to v0.14.3.

content/client-server-api/modules/end_to_end_encryption.md

@@ -1479,6 +1479,43 @@ potential new key backup algorithm version that would fix this issue.
 
 {{% http-api spec="client-server" api="key_backup" %}}
 
+###### Key backup enabled preference
+
+{{% added-in v="1.19" %}}
+
+This enables clients to track a user's preference about enabling or
+disabling [server-side backups of room keys](#server-side-key-backups). The data
+is stored in the [`m.key_backup`](#mkey_backup) global
+[account data](#client-config).
+
+{{% event event="m.key_backup" %}}
+
+When a user signs in to a client which supports encryption and key backup:
+
+* If this event type exists in account data and contains the specified property
+  in the correct format, clients which support key backup MUST take account of
+  its contents in their behaviour. For example, clients may automatically turn
+  on/off key backup based on the property, or prompt the user, using the
+  property value as a default. (Because this property is server-controlled,
+  clients may wish to confirm the user's intention.)
+
+* If this event type does not exist in account data, or if it does not contain
+  the `enabled` property, or if the value of `enabled` is not a boolean value,
+  clients MUST ignore the existing value and MAY decide whether or not to
+  perform key backup, possibly based on user input.
+
+If the user turns on key backups, clients MUST set this event type in account
+data, to `"enabled": true`.
+
+If the user turns off key backups, clients MUST set this event type in account
+data, to `"enabled": false`.
+
+Clients are not required to monitor the `m.key_backup` account data actively.
+Clients MAY monitor the setting but should be aware that changing this setting
+without user interaction based on choices made in a different client (or a
+compromised homeserver) may cause unforeseen security problems or simply be
+unexpected by users.
+
 ##### Key exports
 
 Keys can be manually exported from one device to an encrypted file,

content/client-server-api/modules/room_upgrades.md

@@ -20,6 +20,10 @@ old room. Another approach may be to virtually merge the rooms such that
 the old room's timeline seamlessly continues into the new timeline
 without the user having to jump between the rooms.
 
+When joining a room using the room ID in an `m.room.tombstone` event or
+`predecessor` field on `m.room.create`, clients SHOULD parse the event
+`sender` and use the resulting server name as a `via` parameter.
+
 {{% http-api spec="client-server" api="room_upgrades" %}}
 
 #### Server behaviour

data/api/client-server/definitions/client_event_without_room_id.yaml

@@ -105,9 +105,10 @@ properties:
         type: string
       prev_content:
         description: |
-          The previous `content` for this event. This field is generated
-          by the local homeserver, and is only returned if the event is a state event,
-          and the client has permission to see the previous content.
+          The `content` of the previous state event that was replaced by this event.
+          This field is generated by the local homeserver, and is only returned if
+          the event is a state event, and the client has permission to see the
+          previous event.
         x-changedInMatrixVersion:
           "1.2": |
             Previously, this field was specified at the top level of returned
@@ -117,6 +118,13 @@ properties:
             this.
         title: EventContent
         type: object
+      replaces_state:
+        description: |
+          The event ID of the state event replaced by this event. This field is generated
+          by the local homeserver, and is only returned if the event is a state event.
+          Unlike `prev_content`, this field is included regardless of history visibility.
+        type: string
+        x-addedInMatrixVersion: "1.19"
       membership:
         description: |
           The room membership of the user making the request, at the time of the event.

data/api/client-server/relations.yaml

@@ -254,7 +254,7 @@ components:
 
         Can be a `next_batch` or `prev_batch` token from a previous call, or a returned
         `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
-        or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
+        or a `prev_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
       required: false
       example: page2_token
       schema:

data/event-schemas/examples/m.key_backup.yaml

@@ -0,0 +1,7 @@
+{
+  "$ref": "core/event.json",
+  "type": "m.key_backup",
+  "content": {
+    "enabled": false
+  }
+}

data/event-schemas/schema/m.key_backup.yaml

@@ -0,0 +1,24 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/event.yaml
+description: |-
+  Allows clients to track user preferences about key backup.
+properties:
+  content:
+    type: object
+    properties:
+      enabled:
+        type: boolean
+        description: |-
+          True if the user chose to enable key backup. False if the user chose
+          to disable key backup.
+    required:
+      - enabled
+  type:
+    type: string
+    enum:
+      - m.key_backup
+title: Key Backup Event
+type: object

go.mod

@@ -2,4 +2,4 @@ module github.com/matrix-org/matrix-spec
 
 go 1.12
 
-require github.com/matrix-org/docsy v0.0.0-20260106184755-71d103ebb20a // indirect
+require github.com/matrix-org/docsy v0.0.0-20260331222549-f318855c7886 // indirect

go.sum

@@ -1,4 +1,4 @@
 github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
-github.com/matrix-org/docsy v0.0.0-20260106184755-71d103ebb20a h1:WB3unuZJy7ewAf33sxbtEwYnC+i+Jt1sJpAR3BtzvEo=
-github.com/matrix-org/docsy v0.0.0-20260106184755-71d103ebb20a/go.mod h1:mdn1m5HJug6ZddQgrOyCrXNegbtdl5evHiqqbEQLzdI=
+github.com/matrix-org/docsy v0.0.0-20260331222549-f318855c7886 h1:+Qowx/XQ8sQGTeVyoyIpcwOcdlB+Ft6x+QJkJEPDIpg=
+github.com/matrix-org/docsy v0.0.0-20260331222549-f318855c7886/go.mod h1:mdn1m5HJug6ZddQgrOyCrXNegbtdl5evHiqqbEQLzdI=
 github.com/twbs/bootstrap v5.3.8+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=

layouts/_markup/render-heading.html

@@ -1,7 +1,7 @@
 {{- /*
 
     This is a heading render hook (https://gohugo.io/render-hooks/headings/)
-    using Docsy's heading self-links hook (https://www.docsy.dev/docs/adding-content/navigation/#heading-self-links).
+    using Docsy's heading self-links hook (https://www.docsy.dev/docs/content/navigation/#heading-self-links).
 
     This is used when a heading is encountered in markdown content to generate
     the HTML for that heading. A self-link anchor is added at the end of the

layouts/_partials/navbar.html

@@ -2,7 +2,6 @@
 
   A copy of the navbar.html partial in Docsy, modified to:
 
-  * remove `data-bs-theme` at L20, otherwise the title disappears on hover.
   * replace the site title with "specification" at L31.
   * include the spec version from the config at L34-35, which is calculated
     using an inline `version-string` partial.
@@ -16,7 +15,8 @@
 {{ $baseURL := urls.Parse $.Site.Params.Baseurl -}}
 
 <nav class="td-navbar js-navbar-scroll
-            {{- if $cover }} td-navbar-cover {{- end }}">
+      {{- if $cover }} td-navbar-cover td-navbar-transparent {{- end }}"
+      {{- if eq (.Param "ui.navbar_theme") "dark" }} data-bs-theme="dark" {{- end }}>
 <div class="td-navbar-container container-fluid flex-column flex-md-row">
   <a class="navbar-brand" href="{{ .Site.Home.RelPermalink }}">
     {{- /**/ -}}
@@ -35,7 +35,7 @@
 	  <span class="navbar-version"> &mdash; {{ partial "version-string" . }}</span>
     {{- /**/ -}}
   </a>
-  <div class="td-navbar-nav-scroll td-navbar-nav-scroll--indicator" id="main_navbar">
+  <div class="td-navbar__main td-navbar-nav-scroll td-navbar-nav-scroll--indicator" id="main_navbar">
     <div class="scroll-indicator scroll-left"></div>
     <ul class="navbar-nav">
       {{ $p := . -}}
@@ -80,7 +80,7 @@
     </ul>
     <div class="scroll-indicator scroll-right"></div>
   </div>
-  <div class="d-none d-lg-block td-navbar__search">
+  <div class="td-navbar__search d-none d-lg-block">
     {{ partial "search-input.html" . }}
   </div>
 </div>

layouts/_partials/sidebar-tree.html

@@ -14,6 +14,7 @@
 {{ $cacheSidebar := .cacheSidebar -}}
 
 {{ with $context -}}
+
 {{/* When the sidebar is cached, "active" class is set client side. */ -}}
 {{ $shouldDelayActive := $cacheSidebar -}}
 
@@ -174,7 +175,7 @@
       {{- end -}}
       <span class="
         {{- if $active }}td-sidebar-nav-active-item{{ end -}}
-        {{- if and $s.Params.sidebar_root_for site.Params.ui.sidebar_root_enabled }} td-sidebar-root-up-icon{{ end -}}
+        {{- if and $treeRoot $s.Params.sidebar_root_for site.Params.ui.sidebar_root_enabled }} td-sidebar-root-up-icon{{ end -}}
       ">
         {{- $s.LinkTitle -}}
       </span></a>
@@ -190,4 +191,4 @@
     </ul>
     {{- end }}
   </li>
-{{- end }}
+{{- end -}}