tg-port-feature

Port a feature from an official Telegram client

This skill is the standard procedure for replicating a feature that exists in an official Telegram client into tweb (Telegram Web K, Solid.js + TS). All three reference clients are cloned locally so they can be grep-ed and read directly — no GitHub round-trips needed.

Reference repositories

The skill expects the three official Telegram clients to be cloned as siblings of the tweb repo (one directory up from the tweb root). Default paths assume ~/Documents/projects/tweb; if the project lives elsewhere, the same sibling layout still applies — just adjust the parent.

Setup (one-time, only if any repo is missing)

Before invoking the skill, check the paths above exist. If any is missing, clone it as a sibling of tweb:

cd "$(dirname "$(git -C ~/Documents/projects/tweb rev-parse --show-toplevel)")"   # or just: cd ~/Documents/projects
git clone --depth 1 --filter=blob:none https://github.com/telegramdesktop/tdesktop.git
git clone --depth 1 --filter=blob:none https://github.com/DrKLO/Telegram.git
git clone --depth 1 --filter=blob:none https://github.com/TelegramMessenger/Telegram-iOS.git

If a clone goes stale, refresh with git -C <path> pull (works for both shallow and full clones). Don't re-clone unless necessary.

Specifying the reference client

The user picks the client; the skill MUST honour that choice.

If the feature renders very differently per platform (e.g., a swipe-driven UI), surface that to the user in 1–2 sentences and ask which one to follow before writing code.

Where common feature areas live

tdesktop — ~/Documents/projects/tdesktop/Telegram/SourceFiles/

Android DrKLO — ~/Documents/projects/Telegram/TMessagesProj/src/main/java/org/telegram/

For Android, ALWAYS grep -rn first — the files are too big to read top-to-bottom.

Telegram-iOS — ~/Documents/projects/Telegram-iOS/submodules/

Modular layout. Each module name maps to a feature. Examples:

• ChatListUI/ — chat list
• ChatPresentationInterfaceState/, ChatMessageInteractiveMediaNode/ — chat interior
• StoryContainerScreen/, MediaEditor/ — stories
• PremiumUI/, GiftSetupScreen/, StarsUI/ — monetization
• PeerInfoUI/, SettingsUI/, PeerInfoScreen/ — info/settings
• TelegramCore/ — managers, state, signal pipelines
• TelegramApi/ — generated MTProto bindings (Api.functions.*)
• TelegramUI/ — top-level UI assembly

Search by feature noun first (ls submodules | grep -i story); the names are descriptive.

Exploration workflow

1. Locate the feature. For anything beyond a one-line lookup, spawn an Explore subagent scoped to the chosen reference repo so its read-window doesn't blow up the main context:

   Agent({
     subagent_type: "Explore",
     description: "Find gift resale flow in tdesktop",
     prompt: "In ~/Documents/projects/tdesktop, find where the 'resell unique gift' flow is implemented. I need: (1) the popup/box class, (2) the MTProto method(s) called and their params, (3) the data model/struct that backs the gift state. Search breadth: medium."
   })
   

   For Android use ~/Documents/projects/Telegram/TMessagesProj/src/main/java, for iOS use ~/Documents/projects/Telegram-iOS/submodules.

2. Find the MTProto method(s). This is the most portable signal across clients — the same method name maps directly to tweb. Search patterns:

   • tdesktop: grep -rn "MTPxxxxxx" Telegram/SourceFiles (e.g. MTPpayments_GetStarGifts)
   • Android: grep -rn "TLRPC\$TL_xxxxxx" TMessagesProj/src/main/java
   • iOS: grep -rn "Api.functions.xxxx" submodules
   • tweb equivalent: await rootScope.managers.apiManager.invokeApi('xxxx', {…})

3. Read the equivalent area in tweb. tweb's manager pattern (src/lib/appManagers/) maps loosely to tdesktop's Data::* / Android's *Controller / iOS's Telegram* modules. Check whether the feature already has a partial implementation — often a method exists but the UI surface is missing.

4. Translate, don't transliterate. Their UI code is throwaway for our purposes — re-implement in Solid.js + tweb conventions. What you actually port:

   • Data flow: which MTProto methods, in what order, with what params/flags.
   • Edge cases: error paths, empty states, retry/throttle/backoff behavior.
   • UX shape: when to show what (popup vs page vs inline), button placements, copy.
   • NOT their widget tree — Qt / Android Views / SwiftUI don't translate.

Translating tech idioms → tweb

When official clients disagree

If iOS / Android / Desktop implement the same feature differently (different popup vs page, different option ordering, different default, different MTProto flag values), and the user didn't pre-select a reference:

1. Default to tdesktop (canonical-most often).
2. In your reply, surface the disagreement in 1–2 sentences with the trade-off, and let the user redirect before you write code.

Example: "iOS shows resale price as a single field; Android splits it into 'price' + 'currency picker'. Defaulting to tdesktop's combined-field approach — say if you'd prefer Android's split UI."

Memory & follow-ups

• After porting a non-trivial feature, consider noting any tweb-specific gotchas in user memory (e.g. "the X manager doesn't expose Y, had to add it") so the next port doesn't re-discover them.
• If the reference client used an MTProto method tweb has never called before, double-check the type in src/layer.d.ts (@layer) before assuming the call signature.

What this skill does NOT cover

• Pure tweb-internal refactors with no other-client reference.
• MTProto bug debugging — use tweb-mtproto-debug instead.
• Updating the reference repos themselves — git pull manually if you want fresher code.
• Reading/scraping non-official Telegram clients (third-party forks, unofficial mods).