reorder image pack sections

Signed-off-by: jpcshka <189279532+jpcshka@users.noreply.github.com>

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

@@ -34,6 +34,7 @@ Where `ALPHA` and `DIGIT` are as defined in
 [RFC 5234](https://datatracker.ietf.org/doc/html/rfc5234). Shortcodes are
 case-sensitive. The length of a shortcode MUST NOT exceed 100 bytes.
 
+{{% boxes/note %}}
 The `:` character is specifically excluded because it is widely used across messaging
 platforms as a delimiter for triggering emote search (for example, typing
 `:cat` to search for an emote named `cat`). The `/` character is excluded
@@ -41,6 +42,7 @@ because clients MAY use it to separate a shortcode from a pack name in
 completion UI (for example, `:cat/my_pack:`). Spaces are excluded to avoid
 ambiguity and common usability issues. This character set matches that used
 by Discord and Slack, simplifying bridging.
+{{% /boxes/note %}}
 
 Homeservers MAY enforce this grammar when `m.room.image_pack` events are
 submitted by clients via
@@ -53,14 +55,6 @@ Clients SHOULD render emotes and stickers that have malformed shortcodes, so
 that users can identify and correct them. Clients SHOULD enforce this grammar
 when creating or editing image packs.
 
-#### Events
-
-{{% event event="m.room.image_pack" %}}
-
-#### Account data
-
-{{% event event="m.image_pack.rooms" %}}
-
 #### Image properties
 
 Emoticons SHOULD be at least 128×128 pixels. Stickers SHOULD be at least
@@ -74,9 +68,11 @@ animations based on user preferences.
 #### Room image packs
 
 A room MAY contain any number of image packs, each defined by an
-`m.room.image_pack` state event with a distinct `state_key`. Clients SHOULD
+[`m.room.image_pack`](#mroomimage_pack) state event with a distinct `state_key`. An image pack with an empty `state_key` has no special meaning, it is simply another unique identifier. Clients SHOULD
 present the images in a room's packs only when the user is interacting in
-that room.
+that room, unless that image pack is enabled globally.
+
+{{% event event="m.room.image_pack" %}}
 
 #### User image packs
 
@@ -84,21 +80,7 @@ To make a room's image pack available globally across all rooms, a user adds
 a reference to the pack in their `m.image_pack.rooms` account data event. The
 reference consists of the room ID and the `state_key` of the pack.
 
-For example, to enable two packs from different rooms:
-
-```json
-{
-  "rooms": {
-    "!someroom:example.org": {
-      "": {}
-    },
-    "!anotherroom:example.org": {
-      "": {},
-      "sticker_pack": {}
-    }
-  }
-}
-```
+{{% event event="m.image_pack.rooms" %}}
 
 #### Space image packs
 
@@ -163,8 +145,8 @@ Clients implementing image pack support SHOULD override this value when
 rendering based on the user's font size or other environmental factors. The
 `width` attribute SHOULD be omitted to preserve the image's aspect ratio.
 
-Clients MAY render messages that consist entirely of custom emotes at a larger
-size.
+Clients MAY render messages that consist entirely of custom emotes and/or normal emoji
+at a larger size.
 
 ##### Sending stickers
 
@@ -176,11 +158,13 @@ absent, an empty object.
 
 ##### Emote picker suggestions
 
-Clients MAY use the `:` character as a trigger to initiate emote search. When
+Clients MAY use the `:` character as a trigger to initiate emote search in the message composer. When
 multiple packs contain images with the same shortcode, clients SHOULD provide
 disambiguation UI rather than silently resolving to one image. Clients MAY
 disambiguate by appending a slugified pack display name separated by `/`
-(for example, `:cat_wave/my_pack:`). Because pack names are not globally
+(for example, `:cat_wave/my_pack:`).
+
+Because pack names are not globally
 unique, clients SHOULD NOT attempt to automatically resolve a shortcode to a
 specific image. Clients SHOULD instead present a search modal or similar UI
 to allow the user to select the intended image.
@@ -210,14 +194,3 @@ A user who enables a room image pack globally via `m.image_pack.rooms`
 implicitly trusts the pack's administrator not to introduce abusive imagery.
 If abusive content is added to a pack, the affected user SHOULD remove the
 reference from their `m.image_pack.rooms` account data.
-
-#### Unstable prefix
-
-Before this feature was included in the Matrix specification, the following
-unstable identifiers were in use. Clients SHOULD migrate to the stable
-identifiers defined in this specification.
-
-| Stable identifier | Unstable identifier |
-|---|---|
-| `m.room.image_pack` | `im.ponies.room_emotes` |
-| `m.image_pack.rooms` | `im.ponies.emote_rooms` |

data/event-schemas/schema/m.image_pack.rooms.yaml

@@ -20,17 +20,19 @@ properties:
           Each entry references a specific `m.room.image_pack` state event
           that the user has enabled globally.
 
-          The bottom-level object is reserved for future use by a subsequent
-          MSC. Clients MUST treat it as opaque and preserve any unrecognised
-          properties when modifying this event.
-
           A room ID present as a key but with no `state_key` entries (i.e. an
           empty inner object) currently has no defined meaning.
 
           Clients SHOULD be aware that the user may not be a member of a room
-          referenced here, and MAY present appropriate UI to handle this case.
+          referenced here, thus the client will not be able to access any images from the
+          pack. Clients MAY present appropriate UI to handle this case.
         type: object
         additionalProperties:
+          description: |
+            Map from image pack `state_key` to an empty object.
+            
+            The bottom-level object is reserved for future use. Clients SHOULD treat it 
+            as opaque and preserve any unrecognised properties when modifying this event.
           type: object
           additionalProperties:
             type: object