copy-pasted Cadence's message as documentation

docs/threads-as-rooms.md

@@ -0,0 +1,9 @@
+I thought pretty hard about it and I opted to make threads separate rooms because
+
+1. parity: discord has separate things like permissions and pins for threads, matrix cannot do this at all unless the thread is a separate room
+2. usage styles: most discord threads I've seen tend to be long-lived, spanning months or years, which isn't suited to matrix because of the timeline
+  - I'm in a discord thread for posting photos of food that gets a couple posts a week and has a timeline going back to 2023
+3. the timeline: if a matrix room has threads, and you want to scroll back through the timeline of a room OR of one of its threads, the timeline is merged, so you have to download every message linearised and throw them away if they aren't part of the thread you're looking through. it's bad for threads and it's bad for the main room
+4. it is also very very complex for clients to implement read receipts and typing indicators correctly for the merged timeline. if your client doesn't implement this, or doesn't do it correctly, you have a bad experience. many clients don't. element seems to have done it well enough, but is an exception
+
+overall in my view, threads-as-rooms has better parity and fewer downsides over native threads. but if there are things you don't like about this approach, I'm happy to discuss and see if we can improve them.

src/m2d/event-dispatcher.js

@@ -226,7 +226,7 @@ async event => {
 		api.sendEvent(event.room_id, "m.room.message", {
 			body: "⚠️ **This message may not have been bridged to Discord in the way you thought it was gonna be!**\n\nIt seems like you sent this message inside a Matrix thread. Matrix threads don't work like Discord threads - they are effectively just „fancy replies”, not independent rooms/channels (any „thread-like appearance” is handled purely client-side - and even then, most Matrix clients don't handle it particularly well, with Element being the only one known to actually render threads as threads), and as such, they are bridged as replies to Discord. *In other words: __Discord users will not be aware that you sent this message inside a thread - the reply will go directly onto the main channel.__ If the thread you sent this message in is old, such a random reply **may be distracting** to Discord users!*\n\nFor the sake of Discord parity (and for better support in numerous Matrix clients - as stated above, most Matrix clients don't handle threads particularly well, and they just render in-thread messages as fancy replies), it is recommended to send threaded messages inside a separate Matrix room that gets bridged to Discord. "+ (bridgedTo ? "Luckily for you, this thread already has one! You can access it on https://matrix.to/#/"+bridgedTo+"?"+(await utils.getViaServersQuery(bridgedTo, api)).toString() : "Please run `/thread [Optional: Thread Name]` to create such a room for this thread, or get a link to it if someone else has already done so. If you run `/thread` (without any arguments) outside any threads and not as a reply, you'll get more info about this command")+".\n\n*You can read more about the rationale behind this design choice [here](https://gitdab.com/cadence/out-of-your-element/src/branch/main/docs/threads-as-rooms.md).*",
 			format: "org.matrix.custom.html",
-			formatted_body: "⚠️ <strong>This message may not have been bridged to Discord in the way you thought it was gonna be!</strong><br><br>It seems like you sent this message inside a Matrix thread. Matrix threads don't work like Discord threads - they are effectively just „fancy replies”, not independent rooms/channels (any „thread-like appearance” is handled purely client-side - and even then, most Matrix clients don't handle it particularly well, with Element being the only one known to actually render threads as threads), and as such, they are bridged as replies to Discord. <em>In other words: <u>Discord users will not be aware that you sent this message inside a thread - the reply will go directly onto the main channel.</u> If the thread you sent this message in is old, such a random reply <strong>may be distracting</strong> to Discord users!</em><br><br>For the sake of Discord parity (and for better support in numerous Matrix clients - as stated above, most Matrix clients don't handle threads particularly well, and they just render in-thread messages as fancy replies), it is recommended to send threaded messages inside a separate Matrix room that gets bridged to Discord. "+ (bridgedTo ? "Luckily for you, this thread already has one! You can access it on <a href=\"https://matrix.to/#/"+bridgedTo+"?"+(await utils.getViaServersQuery(bridgedTo, api)).toString()+"\">https://matrix.to/#/"+bridgedTo+"?"+(await utils.getViaServersQuery(bridgedTo, api)).toString()+"</a>" : "Please run <code>/thread [Optional: Thread Name]</code> to create such a room for this thread, or get a link to it if someone else has already done so. If you run <code>/thread</code> (without any arguments) outside any threads and not as a reply, you'll get more info about this command")+".<br><br><em>You can read more about the rationale behind this design choice <a href=\"https://gitdab.com/cadence/out-of-your-element/src/branch/main/docs/threads-as-rooms.md\">here</a>.</em>",
+			formatted_body: "⚠️ <strong>This message may not have been bridged to Discord in the way you thought it was gonna be!</strong><br><br>It seems like you sent this message inside a Matrix thread. Matrix threads don't work like Discord threads - they are effectively just „fancy replies”, not independent rooms/channels (any „thread-like appearance” is handled purely client-side - and even then, most Matrix clients don't handle it particularly well, with Element being the only one known to actually render threads as threads), and as such, they are bridged as replies to Discord. <em>In other words: <u>Discord users will not be aware that you sent this message inside a thread - the reply will go directly onto the main channel.</u> If the thread you sent this message in is old, such a random reply <strong>may be distracting</strong> to Discord users!</em><br><br>For the sake of Discord parity (and for better support in numerous Matrix clients - as stated above, most Matrix clients don't handle threads particularly well, and they just render in-thread messages as fancy replies), it is recommended to send threaded messages inside a separate Matrix room that gets bridged to Discord. "+ (bridgedTo ? "Luckily for you, this thread already has one! You can access it on <a href=\"https://matrix.to/#/"+bridgedTo+"?"+(await utils.getViaServersQuery(bridgedTo, api)).toString()+"\">"+bridgedTo+"</a>" : "Please run <code>/thread [Optional: Thread Name]</code> to create such a room for this thread, or get a link to it if someone else has already done so. If you run <code>/thread</code> (without any arguments) outside any threads and not as a reply, you'll get more info about this command")+".<br><br><em>You can read more about the rationale behind this design choice <a href=\"https://gitdab.com/cadence/out-of-your-element/src/branch/main/docs/threads-as-rooms.md\">here</a>.</em>",
 			"m.mentions": { "user_ids": [event.sender]},
 			"m.relates_to": {
 				event_id: event.content["m.relates_to"].event_id,