monal-rebuild/REACTIONS-PLAN.md

Emoji reactions (XEP-0444) — design notes, 2026-10-08

The survey, then the two decisions it waited on, both now settled — §4 by the operator, §5 from Monal's source. Implementation is done; §6 and §7 say what was built and what was run, and UX-REACTIONS-RESULTS.md carries the evidence.

The operator's framing: Monal probably cannot do reactions, and 0ff chat should have them anyway. That is a legitimate position — it just changes what "done" means, which §4 is about.

1. What exists today, verified

• No reaction code anywhere. grep -niE "emoji|reaction|0444" over src/, test/ and over blunix's capabilities/ and docs/ returns nothing.
• Nobody has ever sent one to this server. urn:xmpp:reactions does not appear anywhere under /var/lib/prosody/. So no client in use here — Monal included — has put a reaction on the wire, which matches the operator's guess without confirming it (an unused feature and an absent feature look the same from the archive).
• Emoji as text already work, and need nothing: they are ordinary Unicode, 10 archive files already contain codepoints from the U+1F300–1FAFF block. There is no emoji picker in the composer; on a phone the system keyboard covers it, on desktop it does not.
• The client advertises its features in src/xmpp/caps.ts (BASE_FEATURES); reactions would add one entry there.
• The reply plumbing already solved the hard addressing question. src/xmpp/replies.ts's replyId() returns the room-issued stanzaId for groupchat and originId ?? id otherwise — which is exactly XEP-0444's rule. Reuse it; do not write a second one.

2. The wire format, from the XEP

Read from https://xmpp.org/extensions/xep-0444.html on 2026-10-08:

<message to='…' type='chat'>
  <reactions id='744f6e18-a57a-11e9-a656-4889e7820c76' xmlns='urn:xmpp:reactions:0'>
    <reaction>👋</reaction>
  </reactions>
  <store xmlns='urn:xmpp:hints'/>
</message>

• Full state, not a delta. Each <reactions> replaces everything that sender had on that message. Removing one means resending the set without it; removing all means an empty <reactions id='…'/>. The UI must therefore always send the sender's complete set, and the store must key reactions by (message, sender) and overwrite.
• Which id: the id attribute, preferably XEP-0359 <origin-id>, in 1:1; for type='groupchat' the stanza's own id must not be used — the room-issued <stanza-id> is required.
• <store/> hint (XEP-0334) SHOULD be added unless the message reacted to carried <no-store/>. This matters here, see §3.
• Disco feature: urn:xmpp:reactions:0.
• Content: a <reaction> SHOULD be codepoints that display as a single emoji (UTS #51). The XEP says nothing about encryption and nothing about MAM.

3. The server side: almost nothing, and why

A reaction is an ordinary <message>, so Prosody needs no module and no new configuration. One thing was checked rather than assumed:

mod_mam's should_store (mod_mam.lua:322 in the deployed prosody 13.0.6) archives on a <body>, a <subject>, urn:xmpp:eme:0, receipts, chat markers — and has no branch for urn:xmpp:reactions:0. A reaction has no body, so it would not be archived and would vanish on reload. But the <store/> hint hits the branch above those checks and returns true. So: send the hint and the archive works; forget the hint and reactions silently fail to persist. That is the single server-facing fact of this whole feature.

Not checked yet: whether MUC reactions pass through muc.0ff.space untouched, and whether the room archive stores them. mod_muc_mam has its own storage rules.

4. The real decision: OMEMO

This is what makes the feature more than an afternoon, and it has to be settled before any code.

The client has no envelope for arbitrary XML. It implements legacy OMEMO (eu.siacs.conversations.axolotl): session.svelte.ts:233 encrypts content.body — a string — and buildEncryptedMessage (omemo-wire.ts:185) wraps exactly that. There is no XEP-0420 Stanza Content Encryption here, so a <reactions> element cannot be put inside the ciphertext the way the aesgcm:// URL was.

Three ways out, with what each costs:

• (a) Send reactions in cleartext, next to the encrypted body. Cheap and interoperable. It leaks, per reaction, that a reaction happened, to which message, and which emoji — in a chat whose text is encrypted. For 👍 on a message whose content is unknown to the server, that is a small leak; it is still a visible exception to "this chat is encrypted", and the client has so far refused every such exception (a plaintext oob to a capable peer is rejected outright, session.svelte.ts:218).
• (b) Implement XEP-0420 SCE and encrypt the whole payload. The honest answer protocol-wise, and it would also clean up quoted replies, whose metadata is likewise outside the ciphertext today. It is a substantial piece of work and changes the OMEMO wire format this client and Monal agreed on — verified interop would have to be redone.
• (c) A private convention (a reaction encoded in an encrypted body). Interoperates with nothing and pollutes the archive. Rejected before it is proposed.

Decided 2026-10-08, by the operator: (a), stated plainly in the UI. A reaction in an encrypted chat goes out in cleartext, and the UI says so where the reaction is given rather than burying it — what leaks is which emoji landed on which message, never the message text. This is a named exception to the client's fail-closed rule, which stays in force for everything carrying content: a plaintext oob to a capable peer is still rejected outright (session.svelte.ts:218), and an encrypted message still refuses to be quoted into an unencrypted reply.

(b) stays on the backlog as its own project, with quoted replies' metadata folded in; it is what retires the exception.

5. Monal ignores them silently — checked, not assumed

Monal Stable 6.4.21 (release source 9be038e9, the same checkout that settled the aesgcm:// format; see OMEMO-PLAN.md) was read on 2026-10-08. The question was whether a reaction would reach the operator's phone as an empty bubble or, worse, as a notification per thumbs-up.

• No XEP-0444 at all. urn:xmpp:reactions appears nowhere in the tree; the string reaction appears in no .m, .h, .swift or .rs file; monal.doap does not list the XEP.
• A bodiless reaction is dropped on the floor. In MLMessageProcessor.m the whole store/notify/contact-create branch is gated on [messageNode check:@"body#"] || decrypted (:560), with addActiveBuddies inside it (:712). Without a body the stanza falls through the else-if chain — :728 is the outbound case — and the separate receipt, chat-marker and chatstate blocks match nothing in it. No bubble, no entry in the active-chats list, no notification.
• No push. mod_push2.lua:184 is_important ends at has_body (:165) for a chat message. A cleartext reaction has no body, no <encrypted> and no Jingle element, so it is not important and the urn:xmpp:push2:match:important filter drops it.

So reactions are invisible on the phone and cost nothing there. Two consequences worth holding on to: the feature is 0ff chat ↔ 0ff chat only until Monal grows support, and the no-push result depends on reactions staying unencrypted — the moment they ride inside <encrypted> (§4(b)) they become important at mod_push2.lua:170 and start pushing. Still worth confirming once in the journal rather than trusting the read.

6. Client work, in the order it happened

All of steps 1-7 below are done, and UX-REACTIONS-RESULTS.md records what was built and what was run. Two differences from the plan as written: the store keys by the reacted-to message's stable id rather than by the local message key, so a reaction arriving before its message can wait for it; and the affordance is not what step 5 imagined. It was built as a picker — six quick reactions plus a field — and the operator replaced it the same day with a double-tap that gives one fixed reaction, and had the bubble's "Reply" and "React" buttons removed with it. See UX-REACTIONS-RESULTS.md, "The bubble as the operator wanted it".

1. Decide §4 and §5. Both settled on 2026-10-08: cleartext with a visible notice, and Monal ignores a bodiless reaction entirely.
2. Wire layer, src/xmpp/reactions.ts alongside replies.ts: build and parse <reactions>, reuse replyId() for addressing, validate that each <reaction> is a single grapheme and cap the count per sender. Never trust the id or the emoji from the wire.
3. Store, src/store/db.ts: reactions keyed by (message key, sender), full-state overwrite, delete on empty. They arrive both live and from MAM, so the same dedupe discipline as messages applies — a reaction can also arrive before the message it points at (MAM paging), which the store has to tolerate rather than drop.
4. Receive and render, src/ui/Chat.svelte: a compact row under the bubble, grouped by emoji with a count, the viewer's own highlighted.
5. Send: superseded by the operator on 2026-10-08. A double-tap or double-click on a bubble gives one fixed reaction (a heart); tapping a chip joins or leaves a reaction somebody already gave. There is no picker and no bubble button, so there is also no keyboard or mouse route to quoting any more — the swipe is touch-only. That is a deliberate trade the operator made for a quieter bubble; it is recorded here rather than argued, and SWIPE-IS-THE-ONLY-QUOTE-ROUTE in ux-swipe-runner.cjs fails if the buttons come back unnoticed.
6. Advertise urn:xmpp:reactions:0 in caps.ts.
7. Rooms last: the stanza-id addressing, and the mod_muc_mam question from §3.

7. What "verified" has to mean here

The bar the previous packages set: candidate checks in a runner against the deployed bundle, then the device half by the operator. Every line below now has a named check or a named reason it was not run; see UX-REACTIONS-RESULTS.md for the results.

• A reaction goes out with the right id for 1:1 and for a room, carries <store/>, and survives a reload — read back from the server archive, not only from local state. Done: REACT-GOES-OUT, REACT-ROOM-STANZA-ID, REACT-IN-ARCHIVE, REACT-ROOM-ARCHIVE, REACT-SURVIVES-RELOAD. The mod_muc_mam question from §3 is answered with a read of the room's own archive: it keeps them.
• Full-state semantics: two reactions, then one removed, leaves exactly one, for both the sender's and the receiver's view. Done: REACT-FULL-STATE, REACT-RECEIVE-AND-WITHDRAW.
• A reaction to a message that is not in the local store does not create a ghost, and does not crash the list. Done: REACT-NO-GHOST.
• A reaction with twenty emoji, or with arbitrary text instead of an emoji, is refused or clamped — not rendered. Done: REACT-CLAMPED, and the parser cases in test/reactions.test.ts.
• The push journal shows no push for a reaction. Partly: zero pushes over the run window, but the audit sessions hold no push registration, so the weight is on the mod_push2.lua read in §5. A real pushing device is a device check.
• On the phone: what Monal actually does with one. Not run: its source says it is dropped silently (§5); nobody has watched the phone.

8. Smaller thing, separately

An emoji picker in the composer is unrelated to all of the above — pure client UI, no protocol, no OMEMO question. It is worth little on iOS (the system keyboard has one) and noticeably more on desktop. If the point is "it would be nice to have emoji", that is a much cheaper piece of work than §4–§7 and could come first.