# Emojis & stickers — handoff

## Summary

Paarrot extends Cinny's emoji/sticker system with **usage tracking** (frequently used emojis), **Telegram sticker pack import**, custom emoji pack plugins, and configurable **emoji font** (System / Apple / Twemoji). Pack management lives under Settings and room/space settings.

## User-facing behavior

- **Settings → Emojis & stickers**: global packs, user packs, Telegram import
- Frequently-used emojis sorted by usage stats
- **Settings → General → Emoji style**: System, Apple, Twemoji fonts
- Telegram: bot token stored locally, import packs by name
- Room/space emoji packs via common-settings (inherited Cinny patterns)

## Architecture

```
useEmojiUsage → account data paarrot.favemojis
EmojiStyleFeature (ClientNonUIFeatures) → CSS --font-emoji
TelegramImport.tsx → telegramStickerImport.ts → Matrix image pack upload
custom-emoji plugin (plugins/custom-emoji/) → PackMetaReader
Settings / common-settings EmojisStickers pages
```

## Key files

| Path | Role |
|------|------|
| `cinny/src/app/hooks/useEmojiUsage.ts` | Usage stats in account data |
| `cinny/src/app/utils/telegramStickerImport.ts` | Telegram Bot API import |
| `cinny/src/app/features/settings/emojis-stickers/TelegramImport.tsx` | Import UI |
| `cinny/src/app/features/settings/emojis-stickers/EmojisStickers.tsx` | Settings hub |
| `cinny/src/app/features/settings/emojis-stickers/UserPack.tsx` | User pack editor |
| `cinny/src/app/features/settings/emojis-stickers/GlobalPacks.tsx` | Global packs |
| `cinny/src/app/plugins/custom-emoji/` | Custom emoji pack reader |
| `cinny/src/app/pages/client/ClientNonUIFeatures.tsx` | `EmojiStyleFeature` |
| `cinny/src/app/state/settings.ts` | `EmojiStyle` enum |

## Data model

| Key | Scope | Content |
|-----|-------|---------|
| `paarrot.favemojis` | User account data | Emoji usage counts |
| `cinny_telegram_bot_token` | localStorage | Telegram bot token (TelegramImport) |
| `im.ponies.room_emotes` | Room state | Standard Matrix emoji packs |

## Dependencies

- Telegram Bot API (`api.telegram.org`)
- Twemoji / Apple Color Emoji fonts (bundled or system)
- `matrix-js-sdk` for image pack events

## Integration points

- **Emoji board / composer autocomplete**: reads usage ordering
- **Image pack viewer**: preview imported packs
- **Plugins**: custom-emoji pack format

## Testing

### Manual

1. Send messages with varied emoji; open picker — frequent ones rise.
2. Import Telegram pack with valid bot token; verify stickers in room.
3. Switch emoji style General setting; verify font change in messages.
4. Add room emoji pack in space settings.

### Automated

- None

## Known issues & gotchas

- Telegram token in **localStorage** — not encrypted; user-provided bot
- Telegram import uses network to Telegram servers — rate limits apply
- `PAARROT_EMOJI_USAGE_EVENT = 'paarrot.favemojis'` — must stay stable or migrate
- Pack id prefix `telegram_${packName}` for imported packs

## Future work

- Encrypt or secure-store Telegram token
- Usage stats sync across devices (account data already does)
- Sticker pack marketplace

## Related docs

- Cinny upstream emoji pack docs (if any)

## Add your extra things here

- Emoji style values: `EmojiStyle.System | Apple | Twemoji` in settings atom
- `useEmojiGroupLabels` for picker section headers