Custom Emoji

Area: custom-emoji Status: Active Last updated: 2026-06-05

Overview

Custom emoji lets users upload small image emoji, use them in chat messages and reactions, and sync emoji assets needed for rendering to connected peers over the existing data-channel mesh.

Responsibilities

Own custom emoji asset validation, local persistence, user-saved library membership, shortcut ranking, and peer-to-peer asset sync.
Expose a shared picker consumed by chat message reactions and the chat composer.
Keep usage ranking local to the current user; usage counts are not synced.
Does not store custom emoji on the signaling server.

Key Concepts

Custom emoji asset: A user-created image stored as a data URL with id, name, mime, size, hash, creator, timestamps, and optional saved-library membership.
Known custom emoji: A synced asset available for message rendering and forwarding, but not shown in the current user's picker unless saved.
Saved custom emoji: A known asset with savedByUser enabled; saved emoji appear in the picker and shortcut ranking.
Emoji shortcut row: The seven most-used emoji entries for the current user plus an eighth control that opens the full selector.
Custom emoji token: The stable message/reaction representation :emoji[id](name), resolved locally to the synced image asset when rendering.
Composer emoji alias: The readable inline draft representation :name:. The composer rewrites known aliases to stable custom emoji tokens only when sending.

Peer Envelope Contract

Custom emoji uses ChatEvent data-channel envelopes:

custom-emoji-summary: { customEmojiSummaries: [{ id, hash, updatedAt }] }
custom-emoji-request: { ids: string[] }
custom-emoji-full: { customEmojiTransfer: Omit<CustomEmoji, 'dataUrl'>, total: number }
custom-emoji-chunk: { customEmojiId, index, total, data }

When a peer connects, each side sends a summary of known assets. The receiver requests missing or stale emoji by id, and the owner replies with a small manifest followed by bounded base64 chunks using buffered peer sends. Creating a new emoji also streams that manifest and chunk sequence to every currently connected peer. Outgoing room chat messages, edits, reactions, and direct messages proactively push every referenced custom emoji asset to connected peers in parallel with the message event, so receivers do not wait for a request round-trip. Small assets that fit under CUSTOM_EMOJI_INLINE_MAX_JSON_BYTES travel inline in one custom-emoji-full event; larger assets use manifest plus chunks. Incoming chat messages and chat-sync batches still scan for :emoji[id](name) tokens and request any missing assets from the sender as a repair path. Full inline customEmoji payloads remain accepted for backward compatibility.

Business Rules

Uploads are capped at 1 MB.
Accepted image types match profile avatars: WebP, GIF, JPG, and JPEG.
Local shortcut ranking is keyed by the active user and includes Unicode emoji plus saved custom emoji only.
Message rendering reserves inline emoji space with a transparent placeholder image while a referenced custom emoji asset is not yet available; deferred markdown placeholders rewrite tokens to readable :name: aliases so raw :emoji[id](name) text never flashes in chat.
Seen custom emoji are not added to the picker automatically; right-click a rendered custom emoji in chat or on a custom emoji reaction and choose Add to emoji library from the app context menu (NativeContextMenuComponent).
Saved custom emoji can be removed from the picker library by right-clicking them inside the emoji picker and choosing Remove from emoji library; the asset stays available for rendering messages that already reference it.
Emoji hosts are marked with data-custom-emoji / data-custom-emoji-library plus data-custom-emoji-id so the global context menu can distinguish them from regular images and suppress the default Copy Image action.
The full emoji picker includes a search field that filters built-in Unicode emoji by common terms and saved custom emoji by name.
Custom emoji data-channel chunks are capped below typical SCTP message limits; back-pressure alone is not enough because a single oversized send can fire RTCDataChannel.onerror.
Completed transfers are persisted only when the reconstructed data URL matches the manifest size and hash; corrupt local rows are dropped before summaries are advertised.

Data Access

Browser runtime stores custom emoji in IndexedDB store customEmojis.
Electron runtime stores custom emoji in SQLite table custom_emojis, created by migration 1000000000011-AddCustomEmojis.
Renderer access goes through DatabaseService methods saveCustomEmoji, getCustomEmojis, and deleteCustomEmoji.

Testing

Unit tests cover upload size validation, shortcut selection, picker search filtering, custom emoji token generation, data-channel chunk splitting, readable composer alias rewriting, transfer integrity, saved-library membership, and add/remove library context-menu actions.

Security Considerations

Emoji payloads are image-only and size-limited before persistence or broadcast.
Assets sync only to already connected peers; the signaling server does not persist or proxy emoji images.

5.3 KiB Raw Blame History