tdesktop Documentation

Technical Documentation: telegramdesktop/tdesktop

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

[Telegram Desktop][telegram_desktop] – Official Messenger

This is the complete source code and the build instructions for the official Telegram messenger desktop client, based on the Telegram API and the MTProto secure protocol.

The source code is published under GPLv3 with OpenSSL exception, the license is available here.

Supported systems Copy Chapter

The latest version is available for

• Windows 7 and above (64 bit) (portable)
• Windows 7 and above (32 bit) (portable)
• macOS 10.13 and above
• Linux static build for 64 bit
• Snap
• Flatpak

Old system versions Copy Chapter

Version 4.9.9 was the last that supports older systems

• macOS 10.12
• Linux with glibc < 2.28 static build

Version 2.4.4 was the last that supports older systems

• OS X 10.10 and 10.11
• Linux static build for 32 bit

Version 1.8.15 was the last that supports older systems

• Windows XP and Vista (portable)
• OS X 10.8 and 10.9
• OS X 10.6 and 10.7

Third-party Copy Chapter

• Qt 6 (LGPL) and Qt 5.15 (LGPL) slightly patched
• OpenSSL 3.2.1 (Apache License 2.0)
• WebRTC (New BSD License)
• zlib (zlib License)
• LZMA SDK 9.20 (public domain)
• liblzma (public domain)
• Google Breakpad (License)
• Google Crashpad (Apache License 2.0)
• GYP (BSD License)
• Ninja (Apache License 2.0)
• OpenAL Soft (LGPL)
• Opus codec (BSD License)
• FFmpeg (LGPL)
• Guideline Support Library (MIT License)
• Range-v3 (Boost License)
• Open Sans font (Apache License 2.0)
• Vazirmatn font (SIL Open Font License 1.1)
• Emoji alpha codes (MIT License)
• xxHash (BSD License)
• QR Code generator (MIT License)
• CMake (New BSD License)
• Hunspell (LGPL)
• Ada (Apache License 2.0)
• zxcvbn-c (MIT License)
• FrequencyWords by Hermit Dave (Creative Commons Attribution-ShareAlike 4.0)

Build instructions Copy Chapter

• Windows (32-bit and 64-bit)
• macOS
• GNU/Linux using Docker

Thanks to Copy Chapter

CI infrastructure sponsored by Depot — fast GitHub Actions runners.

Overview (`tools/clangtidy/README.md`) Copy Section

clang-tidy for tdesktop

python3 tools/clangtidy/compile_db.py               # after each configure
git diff -U0 HEAD | clang-tidy-diff.py -p1 -path out/clang-tidy -j 10 -quiet
run-clang-tidy -p out/clang-tidy -j 10 -quiet <files>

Both runners ship with LLVM, under share/clang. Needs clang-tidy 20 or
newer: an older one ignores CustomFunctions without a word.

The commit hook, once per clone, submodules included; its tests run with
python3 tools/rules/test_hook.py:

for repo in . $(git config -f .gitmodules --get-regexp path \
        | awk '{print $2}' | grep -v ThirdParty); do
    hooks=$(git -C "$repo" rev-parse --git-path hooks)/pre-commit
    printf '#!/bin/sh\nexec python3 %s/tools/rules/hook.py --staged\n' \
        "$PWD" > "$hooks" && chmod +x "$hooks"
done

Overview (`Telegram/Resources/zxcvbn/README.md`) Copy Section

zxcvbn frequency lists

The two word lists in this directory are unmodified copies of third-party
frequency lists. They are read only at build time: the rules in
Telegram/cmake/lib_zxcvbn.cmake transliterate them and compile the result
into the zxcvbn-c password dictionary behind
Telegram/SourceFiles/ui/passcode_strength.cpp. No built artifact contains
these files: they are build-time inputs to a generated header. They are
tracked, so every source distribution of Telegram Desktop ships them
verbatim, and the attribution below covers those copies as well as the
dictionary compiled from them.

Provenance Copy Chapter

• Title: FrequencyWords
• Creator: Hermit Dave
• Repository: https://github.com/hermitdave/FrequencyWords
• Upstream commit: f8a65e6ddc17e0baa2e366a909986798d8dbe55b (2019-02-15,
  "Additional languages including pl, pt and zh variants", the last upstream
  commit touching either file)
• Derivation: generated by the upstream author from the OpenSubtitles2018
  corpus (http://opus.nlpl.eu/OpenSubtitles2018.php); one word count
  pair per line, separated by a single space, in descending order of count;
  50,000 lines each, all lowercase, LF line endings, no BOM.

sha256 digests, equal to the GitHub raw files at the pinned commit (verified
2026-09-06):

6095f507cc167488ec66ada5a85ac50433503a08ad24a07c6eabdf54352c4e7f  ru_50k.txt
881686fe66a168b79f6a9ee2f6cbbf944cfb12bfb7040913ef535cb29bd86ec9  uk_50k.txt

.gitattributes pins Telegram/Resources/zxcvbn/*.txt to text eol=lf, so
the digests hold on a Windows checkout as well.

Licence Copy Chapter

Upstream's README.md states, under "License", at the upstream head
525f9b560de45753a5ea01069454e72e9aa541c6 (2022-02-07) — head on
2026-09-06, the day these copies were taken:

MIT License for code.
CC-by-sa-4.0 for content.

The licence version in that statement has changed exactly once. At the
pinned commit f8a65e6ddc17e0baa2e366a909986798d8dbe55b (2019-02-15, the
only commit that ever touched either list) the section read
MIT License for codes. / CC-by-sa-3.0 for contents.; commit
0c6a7e40cfd8c645f9e91ff70cd94d7aa8c85c09 (2019-02-15) reworded it to
MIT License for code. / CC-by-sa-3.0 for content., leaving the
version at 3.0; and commit 34bb6447a96d4434dc2d4b24e0cf946c523090b3
(2020-08-11, "Update README.md") replaced CC-by-sa-3.0 with
CC-by-sa-4.0 in that one line, since when the section has read as quoted
above.

The word lists are content, not code, and the licence that governs these
copies is the Creative Commons Attribution-ShareAlike 4.0 International
licence (CC BY-SA 4.0), https://creativecommons.org/licenses/by-sa/4.0/,
through the licensor's standing offer at head — not through the pin, and
not merely because the bytes are unchanged. A public licence is an offer
made when the material is made available, and a licensor may add a new offer
over unchanged files without withdrawing the old one (CC BY-SA 3.0 §7(b),
CC BY-SA 4.0 §6(c)). The pin fixes which bytes are tracked, and the digests
above stay pinned to it; it does not fix which offer they were taken under.

The earlier 3.0 offer is perpetual and remains available, but it is not
relied on here. Were the 4.0 offer ever disputed, 3.0 alone would still
reach CC BY-SA 4.0, because 3.0 §4(b)(ii) permits distributing an Adaptation
under "a later version of this License with the same License Elements"; it
would not reach the GNU GPL directly, because Creative Commons records that
"Currently, no non-CC licenses have been designated as compatible with BY-SA
3.0".

The repository's LICENSE file (MIT, "Copyright (c) 2016 Hermit Dave")
covers the generator code only. Upstream supplies no separate copyright or
disclaimer notice for the content beyond the licence line quoted above.

Changes made Copy Chapter

The lists are used as build-time input only: the word column is kept, each
word is transliterated to Latin letters by zxcvbn_translit, words that are
still non-ASCII or shorter than two letters are dropped, four OpenSubtitles
subtitle-markup strings (chffffff, fntahoma, b1, i0) are dropped,
and the result is compiled into the zxcvbn dictionary; the tracked files are
unmodified copies.
The count column only orders the words: the generated dictionary keeps a
word's rank, not its count.

Compatibility with the application licence Copy Chapter

Telegram Desktop is distributed under the GNU General Public License, version
3 or (at your option) any later version (/LICENSE, /LEGAL), with the
OpenSSL linking exception. CC BY-SA 4.0 content may be adapted into a GPLv3
project on this basis:

• Creative Commons, "Compatible Licenses",
  https://creativecommons.org/share-your-work/licensing-considerations/compatible-licenses/:
  "GPLv3: The GNU General Public License version 3 was declared a
  'BY-SA–Compatible License' for version 4.0 …" and "Note that compatibility
  with the GPLv3 is one-way only, which means you may license your
  contributions to adaptations of BY-SA 4.0 materials under GPLv3, but you
  may not license your contributions to adaptations of GPLv3 projects under
  BY-SA 4.0." (declared 2015-10-08).
• Creative Commons wiki, "ShareAlike compatibility: GPLv3",
  https://wiki.creativecommons.org/wiki/ShareAlike_compatibility:_GPLv3:
  "When someone creates an adaptation of a BY-SA licensed work and includes
  it in a GPLv3-licensed project, both licenses apply and downstream users
  must comply with both licenses. However, Section 2(a)(5)(B) of BY-SA 4.0
  allows anyone who receives the adapted material downstream to satisfy the
  conditions of both BY-SA and GPLv3 (i.e. attribution and ShareAlike) in
  the manner dictated by the GPLv3." and "this compatibility determination
  only allows movement one way, from BY-SA 4.0 to GPLv3."
• Free Software Foundation, "Various Licenses and Comments about Them",
  https://www.gnu.org/licenses/license-list.html#ccbysa: "CC BY-SA 4.0 is
  one-way compatible with the GNU GPL version 3: this means you may license
  your modified versions of CC BY-SA 4.0 materials under GNU GPL version 3,
  but you may not relicense GPL 3 licensed works under CC BY-SA 4.0. Because
  Creative Commons lists only version 3 of the GNU GPL on its compatible
  licenses list, it means that you can not license your adapted CC BY-SA
  works under the terms of 'GNU GPL version 3, or (at your option) any later
  version.' However, Section 14 of the GNU GPL version 3 allows licensors to
  specify a proxy to determine whether future versions of the GNU GPL can be
  used. Therefore, if someone adapts a CC BY-SA 4.0 work and incorporates it
  into a GNU GPL version 3 licensed project, they can specify Creative
  Commons as their proxy …"

Consequence for this repository — an owner decision this file records but
cannot make. Creative Commons declared only GPL version 3 a
BY-SA-Compatible License, and the wiki page quoted above instructs adapters:
"You must specify version 3 of the GPL when redistributing a GPL project
into which BY-SA 4.0 content is adapted." Telegram Desktop's own offer is
broader: /LEGAL — and every source file header that points at it — says
"either version 3 of the License, or (at your option) any later version".
Once the dictionary compiled from this corpus is linked in, that broader
offer cannot be made for the combined work unless the Program itself names a
proxy under GPL §14 ("If the Program specifies that a proxy can decide which
future versions of the GNU General Public License can be used…"). This file
is not the Program's licence statement and cannot make that designation. The
repository owner has to pick one:

• (a) add a GPL §14 proxy designation naming Creative Commons
  (https://creativecommons.org/compatiblelicenses) to /LEGAL, after
  which "or any later version" works again for the combined work as and when
  Creative Commons declares a later GPL version compatible;
• (b) accept that builds containing this dictionary are offered under GPL
  version 3 only, and qualify /LEGAL accordingly;
• (c) drop this corpus — no BY-SA content, no constraint.

Until (a) or (b) is recorded in /LEGAL, this component and the tree's "or
any later version" offer are in tension. The in-app statement,
lng_about_text2, already reads "licensed under the GNU GPL version 3". The
tracked lists themselves remain verbatim copies under CC BY-SA 4.0.

Reproducing the dictionary Copy Chapter

The build performs these steps itself; run them by hand from the checkout
root after a Debug build to check that the generated header is reproducible.
<dir> is any scratch directory outside the checkout.

out/Telegram/Debug/zxcvbn_translit \
    Telegram/Resources/zxcvbn/ru_50k.txt <dir>/ru_50k-latin.txt
out/Telegram/Debug/zxcvbn_translit \
    Telegram/Resources/zxcvbn/uk_50k.txt <dir>/uk_50k-latin.txt
out/Telegram/Debug/zxcvbn_dictgen -o <dir>/dict-src.h \
    Telegram/ThirdParty/zxcvbn/words-eng_wiki.txt \
    Telegram/ThirdParty/zxcvbn/words-female.txt \
    Telegram/ThirdParty/zxcvbn/words-male.txt \
    Telegram/ThirdParty/zxcvbn/words-passwd.txt \
    Telegram/ThirdParty/zxcvbn/words-surname.txt \
    Telegram/ThirdParty/zxcvbn/words-tv_film.txt \
    <dir>/ru_50k-latin.txt \
    <dir>/uk_50k-latin.txt
cmp <dir>/dict-src.h out/Telegram/zxcvbn_gen/dict-src.h

The input order matters: the generator interleaves its inputs by rank, so
the six upstream lists come first, in the order lib_zxcvbn.cmake lists
them, followed by the Russian and then the Ukrainian intermediate. cmp
must report no difference.

Overview (`Telegram/SourceFiles/test/README.md`) Copy Section

Telegram Desktop task-test harness

This directory contains the permanent Debug-only infrastructure used by
perform-task overlays. Read this catalog before designing or recovering a
scenario. The overlay should add only task-specific fixtures, production
entry points, checks, and captures; do not recreate facilities already here.

The default is one packed scenario and one app launch. Put all compatible
checks, themes, values, interactions, and captures into that execution. Plan
another launch only when you can name an incompatible process-lifetime
requirement, such as a startup-only setting or persisted state that the first
flow necessarily contaminates. “The scenario is large” and “a smoke run is
simpler” are not reasons to split it. After a TEST_FLAW, repair every flaw
visible in the run together and rerun the packed scenario.

Cite code by symbol, never by line number, here and in harness comments:
Runner::finish() in test_runner.cpp, not test_runner.cpp:NNN or
:NNN-MMM. Line numbers drift with every edit, including the next harness
task's, and nothing updates them. A failure-diagnosis row names the
functions, constants and macros on its causal path, in product, submodule
and Qt sources alike. Quoted log or crash text stays verbatim.

The stage contract Copy Chapter

Runner executes each Stage as three distinct operations:

A stage timeout is a harness failure unless the readiness condition itself is
the behavior under test. Keep expected geometry, text, pixels, counts, and
other falsifiable outcomes in then or captureAndInspect, not in until.
Otherwise a real product mismatch is mislabeled as an opaque timeout.

Use Runner::actOnWidget when an action depends on a widget that may appear
asynchronously. It polls the resolver and optional readiness predicate, keeps
a QPointer to the exact accepted object, and invokes the action once. This
removes both the eager-.run crash and the “resolve again in .then” race.
The same rule is built into the harness's widget-carrying readings:
Test::BoxShellButtons, Test::WindowMappedCapture,
Test::PaintingLayerRootResult, Test::ToastSubtreeReading and
Test::ContextMenuReading hold QPointer<QWidget>, so a reading kept
across a stage boundary answers matched() / resolved() false (a
context-menu reading's menu reads null) once its subject is destroyed and
still prints its counts, labels, identity and refusal; format a
WidgetDescription of the pointer while the reading is still matched,
because there is nothing to format afterwards.

The generic startup waits are opt-in:

• waitEvent("launch_finished") is the normal first gate.
• waitForSessionReady() is needed only when the scenario consumes a
  session.
• waitForChatsLoaded() is needed only when the tested setup consumes the
  chats list; it is non-fatal and records whether loading completed.
• waitForChatsLoadedStrict() is appropriate only when chats loading is part
  of the required fixture or result.

Do not put all three waits in every scenario preamble. An injected box,
helper oracle, or direct production seam often needs none of the account or
chats gates.

Exact objects and actions Copy Chapter

Telegram custom widgets generally do not declare Q_OBJECT. Never call
findChildren(); Qt may return unrelated widgets blindly
cast to that type. FindAll<T>, FindFirst<T>, and FindVisible<T> enumerate
real QWidget descendants and apply C++ RTTI safely.

FindVisible means only QWidget::isVisible(). It does not prove that the
widget belongs to the current layer, is unobscured, has non-empty mapped
geometry, or is the latest instance. Add those task-specific conditions, or
publish the exact object from its construction seam.

For layer-owned objects, repeated boxes, async replacements, and footer
callbacks with no returned pointer, use the live publication helpers:

// In an inventoried Debug overlay hunk at the real construction seam.
Test::PublishLiveWidget(u"gift.composer"_q, composer);
Test::PublishLiveAction(
	u"gift.confirm"_q,
	box,
	[=] { confirm(); });

// In test_scenario.cpp.
runner->actOnWidget(
	u"open current composer"_q,
	[] { return Test::ReadLiveWidget(u"gift.composer"_q).widget; },
	[](QWidget *widget) { Test::Click(widget); },
	[](QWidget *widget) {
		return widget->isVisible() && widget->isEnabled();
	},
	Test::kDefaultStageTimeout,
	[](QWidget *widget) {
		return u"visible=%1 enabled=%2 size=%3x%4"_q
			.arg(widget->isVisible())
			.arg(widget->isEnabled())
			.arg(widget->width())
			.arg(widget->height());
	});

Each publication advances a generation. A destroyed context makes its widget
or action unavailable. Actions are one-shot by default; pass true only for
a production callback that is intentionally retryable. Use
ReadLiveAction() to wait for a specific generation and invocation count,
then InvokeLiveAction() in an action/assertion stage. This is preferable to
guessing which RoundButton belongs to a presentation wrapper.

Drive a top-level Ui::RpWindow through that static type, never through a
QWidget* or a QPointer<QWidget>. Ui::RpWindow (rp_window.h)
declares setMinimumSize(), setFixedSize(), setGeometry(),
showFullScreen(), showNormal() and close() without virtual and
forwards each to its Ui::Platform::BasicWindowHelper (rp_window.cpp).
The QWidget members of the same names are non-virtual too, so these six
only hide them and the static type picks the function: through a
QWidget* the call compiles, runs the QWidget member and silently skips
lib_ui's platform window helper. Keep the type the product hands out —
Calls::Group::Panel::window(), Calls::Panel::window() and
Calls::Window::window() return not_null — and hold it
across stages as QPointer. A window found through
QApplication::topLevelWidgets() or QWidget::window() is a QWidget*:
dynamic_cast it before the call, and treat a null cast of
the window a stage means to drive as a fixture gate, never as a reason to
call through the QWidget*. Every other Ui::RpWindow forward, such as
setTitle() or setStaysOnTop(), has no QWidget namesake, so a
QWidget* call to it does not compile; a member Ui::RpWindow does not
declare, such as showMaximized(), windowState() or geometry(), is
the same QWidget member through either type. The full-screen row under
“Failure diagnosis” gives the skip's measured consequence on Windows.

Resolving a chat's message list Copy Chapter

A chat's message list is not necessarily HistoryWidget / HistoryInner.
The legacy main-chat stack is HistoryWidget (history/history_widget.h)
plus HistoryInner (history/history_inner_widget.h); the modern stack is
HistoryView::ChatWidget (history/view/history_view_chat_section.h) plus
HistoryView::ListWidget (history/view/history_view_list_widget.h); and the
admin log is a third stack again, AdminLog::InnerWidget, which implements
HistoryView::ElementDelegate itself and constructs no ListWidget.
ChatWidget already backs replies threads, forum topics and both monoforum
and Saved Messages sublists (both are Data::SavedSublist); scheduled
messages, pinned messages, welcome messages and the chat preview popup each
construct their own ListWidget.

A scenario that assumes one named widget renders every chat fails opaquely.
Publishing a live widget from HistoryWidget's construction seam and then
walking the window logged RENDER_ROUTES: published=0 walked=0 chain=[none]
against 403 root descendants — the HistoryInner was never constructed, and
the walk found none either — while the window grab plainly showed the chat
painting the row.

The rule is therefore about resolution, not about a name, and stays true as
the migration proceeds. Resolve the list from the section that constructs it
and prove the candidate owns the message:

• publish the exact live object at the statement that constructs the list —
  _inner = _scroll->setOwnedWidget(object_ptr<ListWidget>( in
  history/view/history_view_chat_section.cpp — through
  Test::PublishLiveWidget;
• keep Test::FindVisible<HistoryView::ListWidget> as an independent
  cross-check and log both answers;
• accept a candidate only when its own lookup answers for the exact message:
  list->viewByPosition(item->position()) must return an Element whose
  data() is that item and whose delegate() is that same list;
• scroll with the product's own entry points, showThread and then the list's
  showAtPosition; decide where the row sits with the list's public
  elementIntersectsRange(view, from, till), and frame it with
  Test::CaptureMappedRect.

item->mainView() is not the Element the visible section owns, so it is
neither a readiness gate nor a geometry oracle. For a row a ListWidget was
painting it answered view=1 with viewHeight=0 and itemTop=-3; use the
list's own viewByPosition for both jobs instead.

The parent chain a resolved ListWidget produced, as the shape to expect, was
ListWidget < Ui::ElasticScroll < ChatWidget < MainWidget < Ui::RpWidget < Ui::RpWidget < MainWindow.

Input helpers Copy Chapter

All input helpers synchronously dispatch real Qt events and drain
Ui::PostponeCall work after each event. They lifetime-guard the target and
stop if it is destroyed. AppendClipboardRoundTrip sits beside DropText
below because the two answer the clipboard question from opposite sides, but
it is a stage, not an event helper: it yields to the event loop between its
attempts.

On macOS a default workspace.py test-run launch of an app bundle's main
executable does not activate the client: it launches the bundle through
LaunchServices in the background, with Qt's own launch activation switched off
(.agents/shared/test-loop.md, Launch activation; the report reads
launch_method: "background"). The client starts as an inactive application
and its windows open behind the frontmost application's. A window shown
already covered reads isExposed() true until the window server first reports
a change for it, so exposed=1 is no proof that it is on screen; after such a
change a covered window reads unexposed and gets no paints. Drive focus-routed
actions with ForceWindowActive, keep a window a stage needs painted exposed
with KeepWindowExposed either way, and use test-run --activate when
genuine OS activation is the subject. Product flows that raise or activate a
top-level window - Ui::PopupMenu, Ui::SeparatePanel::showAndActivate(),
Window::Controller::activate(), DropText into a shown field - still
request activation of the client on macOS, and so do the not-marking-read,
separate-panel-walk and popup-menu self-tests. After a background launch the
window server may grant or refuse that request: on this host it granted it
about 11 s after launch in two default runs and refused it about 20 s after
launch in a third, under a condition those runs did not establish
(2026/10/08/launch-the-testagent-client-without-activating-it, Runs 4, 8 and
9). A granted request takes the key window from the frontmost application.
After a refused one the client stays inactive and the frontmost application
keeps its key window, but the client's window may still be ordered in front of
the frontmost application's window by the request's own window ordering: in
Run 9 above the primary window stayed covered after its restore, while with an
overlay that made the client's own application-activation calls no-ops,
reproducing that refusal under another stage sequence, the inactive primary
window was in front for about 4 s after the not-marking-read self-test's
restore through Window::Controller::activate(), until a later request put it
behind again
(2026/10/09/keep-background-testagent-runs-on-macos-unthrottled-and-painting,
Runs 0 and 3). So the scenario's own activation is no reliable route to OS
activation under the default. A client the launch did not activate is a
background application, which macOS may nap and whose timers it may coalesce:
in background runs on this host without a hold, a sampler's heartbeat gaps
grew to 100-290 ms after about 15 s of normal cadence
(2026/10/01/animate-gram-card-sending-and-settle-effects, Run 1), and a 4 ms
precise sampler ticked every 50-1000 ms from about the 80th second
(2026/10/02/show-the-input-method-composition-in-the-gram-send-amount, Run
1). On a locked console macOS napped such a client without a hold, from about
30 s after process start
(2026/10/09/keep-background-testagent-runs-on-macos-unthrottled-and-painting,
Runs 0 and 4), but another application's window covering the client did not
guarantee it: on an unlocked console, a client without a hold that the
frontmost application's window covered kept an exact 16 ms timer cadence over
60 s and over 300 s (Runs 1 and 2). Those runs did not establish what made
macOS nap the client. So on macOS the harness holds one user-initiated,
latency-critical NSProcessInfo activity
(NSActivityUserInitiatedAllowingIdleSystemSleep | NSActivityLatencyCritical;
idle system sleep stays allowed) for the whole -testagent run:
Test::ApplyStartupOverrides() (test_agent.cpp) begins it early in
Application::run(), before Test::Start(), and never ends it, so it lasts
until the process exits, a watchdog or stage-timeout ending included. The log
says once which case a run is in: a held run reads
NOTE: TDESKTOP_TEST_APP_NAP=[] applied: hold=active ..., and a run without
the hold reads hold=off with the reason. An overlay no longer holds an
activity of its own: the per-overlay BeginLatencyActivity of the
2026/10/07/animate-the-sending-row-for-a-collectible-transfer overlay is
history, and a second activity is harmless but redundant. A campaign whose
subject is background scheduling itself (App Nap, timer coalescing,
throttled-timer behaviour) launches with
test-run --env TDESKTOP_TEST_APP_NAP=allow, and its log then reads
hold=off source=environment; any other non-empty value is logged as
rejected and the hold is kept. Off macOS nothing reads
TDESKTOP_TEST_APP_NAP and nothing is held.

The harness has no pointer. No helper leaves a hover behind, and every
measurement is taken as if no cursor exists — assert a hovered state by
setting it deliberately, not by relying on a click's residue. The one
helper that enters a widget, OpenChatListContextMenu, does so only for
its own call: its QEnterEvent sets the chat list's _mouseActive (the
list's enterEventHook also resolves the real QCursor::pos(), which the
reader never attributes), and its closing QEvent::Leave clears
_mouseActive, the active click handler and, on HistoryInner,
Element::Hovered() again, while Element::Moused() and _overElement
keep the last resolved view, which is not hover. A press also
starts a RippleButton ripple that decays over its style's
showDuration + hideDuration; finish it with finishAnimating() or wait
it out before measuring a fill.

Timers, queued invokes, animations, network callbacks, and reactive streams
still require condition waits. Settle is not a replacement for readiness.

Capture and visual assertions Copy Chapter

Choose the narrowest helper that captures the real paint owner:

CaptureInLayerRoot crops to the box content's own rect. That is not the
whole box: Ui::BoxLayerWidget::setTitle creates _title parented to the
shell, and addButton re-parents each footer button onto the shell, so
both live outside box->rect(). CaptureBoxLayer grabs that shell.

captureWidget and captureAndInspect reject missing, hidden, empty,
near-uniform, and invalid transparent-root frames. Their readiness predicate
should identify current content: model id, generation, title, child count,
paint generation, or settled animation state. It must not assert that the
result has the expected height or colour.

captureAndInspect saves the accepted image before it runs assertions, so a
failure still has decisive evidence:

runner->captureAndInspect(
	u"gift_composer_150"_q,
	[] { return Test::ReadLiveWidget(u"gift.composer"_q).widget; },
	[](QWidget *widget) {
		return widget->property("contentGeneration").toInt() > 0;
	},
	[](QWidget *widget, const QImage &image) {
		Test::Note(u"composer image=%1x%2"_q
			.arg(image.width())
			.arg(image.height()));
		const auto content = widget->childrenRect();
		Test::Check(
			widget->rect().contains(content),
			u"composer contains its child geometry"_q,
			u"owner=%1,%2 %3x%4 children=%5,%6 %7x%8"_q
				.arg(widget->rect().x())
				.arg(widget->rect().y())
				.arg(widget->rect().width())
				.arg(widget->rect().height())
				.arg(content.x())
				.arg(content.y())
				.arg(content.width())
				.arg(content.height()));
	});

If a child grab exposes the harness background, capture the ancestor that
paints the background. If a row is clipped by a scroll viewport, grab the
content widget and map the row rect with CaptureMappedRect; do not treat a
partial screenshot as product evidence.

For a capture whose subject is the currently visible mapping — a card, row,
or child rectangle that must appear whole in the painted owner — the caller
supplies that origin widget, the painted owner, and the exact origin-local
rectangle to ReadMappedTarget / MappedTargetReady. Readiness is
whole-rectangle containment in the owner and the relevant viewport
(Ui::ElasticScroll itself, because its viewport() is Dummy and returns
the inner content; QAbstractScrollArea::viewport() otherwise). It never
intersects, clips, or reframes the requested rect. Origin-local containment
alone is not visibility: a HistoryInner-local card rect can sit fully
inside the inner widget while a negative scroll offset leaves part of it
outside HistoryWidget. CaptureMappedTarget refuses that unready reading
and then composes CaptureMappedRect, which still independently refuses a
rect that is not fully inside the grabbed widget. A nonpainting owner whose
geometry fits is still not capture-ready (PreparedWidgetCapture::prepare).
PaintingLayerRoot resolves boxes inside layers specifically; it is not a
history/list paint-owner resolver. Callers still own semantic navigation
and exact item identity.

Sample an animating owner whose product paints can run back to back —
several animations at once, especially in Debug — with PostPaintSampler
(test_post_paint.h) instead of a timer-driven sampler. In Attempt 1 Run 1
of 2026/10/05/play-gram-card-read-animations-one-after-another a one-shot
16 ms base::Timer sampler of a chat list had a 52 ms gap, from grab 25
(hi 44159) to grab 26 (lo 44211), while three product paints ran back to
back (frames 44159, 44173 and 44193, about 16-20 ms each in Debug), and the
product's own precise timer reported arrive due=44159 late=52; the bound
vstart(B2).hi - turn <= 50 spanned that gap, read 75 and stayed undecided.
Hand the sampler a name for its rows, the owner whose own paintEvent
paints the measured surface (a child's paints are not seen), one action —
normally one Test::GrabRect of an owner-local rect — and
sampleDuring(from, till) windows in crl::now() milliseconds; outside
every window it is idle. A product paint received inside a window posts at
most one queued sample, which runs after that paint returned; a paint
arriving while one is pending shares it. Each sample is one row and one log
line, NOTE: <name>: kind=post seq=<n> paint=<ms> last=<ms> covered=<k> lo=<ms> hi=<ms>: paint and last are the receipt times of the first and
the last product paint it covers, covered counts them, and lo / hi are
crl::now() taken by the sampler itself right before and right after the
action. Read rows through mark(), taken immediately before the action
under test, and samplesSince(mark), and key images by the seq the action
receives, never by position. A sample's lo never precedes the end of the
paint it follows, so a bound from that paint's start shorter than the paint
plus one action cannot be decided with it.

grabFreeDuring(from, till) declares a window in which no sample runs. Its
lead is the longest action so far, at least 40 ms: a paint received from
from minus the lead until till posts nothing and joins no pending
sample, a queued sample that would start there is dropped without a row and
counted in dropped=, and sampling resumes with the first product paint
received at or after till. The recursion guard ignores every paint
received during the action: a grab delivers QEvent::Paint to the owner
through QWidget::render, so a sample never posts another, while an owner
that requests a repaint from every paint keeps being sampled because it
keeps painting. Any other grab of the owner or of an ancestor taken inside a
sampling window looks like a product paint: route it through the action or
take it outside the windows. There is no timer fallback, so nothing is
sampled without a product paint; a frame of an idle surface is a plain grab
taken outside the windows. The owner is held weakly. When it is destroyed, a
pending sample does nothing and the sampler logs one kind=stop reason=owner-destroyed row with its pending=, samples=, paints=,
ignored= and dropped= counts; when the sampler is destroyed first, its
queued call does nothing, and its destructor logs nothing, so read the rows
before releasing it. The stop row is NOTE: <name>: kind=stop reason=owner-destroyed seq=<n> pending=<0|1> samples=<n> paints=<n> ignored=<n> dropped=<n> (PostPaintStopText). Both rows print ordinary
integers until Test::RequestTelemetryNumbers() (test_log.h); a row
formatted after it prints every one of its numbers as a TelemetryNumber
instead, for example kind=post seq=4821p paint=37645p last=37693p covered=59p lo=61482p hi=61537p and kind=stop reason=owner-destroyed seq=4821p pending=1p samples=3764p .... A judge reads a value of either
grammar with float(v.replace('p', '.')). PostPaintSampleText and
PostPaintStopText also take an explicit NumberFormat, so a self-test
reads both formats. details() and the empty-window note (NOTE: <name>: ignored an empty sampling|grab-free window from=<ms> till=<ms>) keep
ordinary integers either way. Confirm with
AppendPostPaintSamplerSelfTest.

Capture a short Ui::Animations-driven animation — a slide transition, a
reveal, a button or card animation of a few hundred milliseconds — at chosen
elapsed times with Test::RunClockedFrames (test_animation_clock.h), not
at whatever runner tick comes next. Its value changes only on an
animation-manager tick: in Run 2 of
2026/10/06/round-rich-message-edge-media-like-ordinary-media twelve 200 ms
transitions sampled at the next 50 ms runner tick were already over. A
ClockedRequest names its rows (name) and carries exactly one of an
action or a handler with its context, strictly increasing elapsed
times in milliseconds after the action, an optional animationEnd and a
synchronous render. The helper starts a probe Ui::Animations::Basic of
its own, runs the action inside Test::Settle with crl::now() stamped
right before the action and right after its postponed calls were drained,
and calls a handler's onClick(context) directly, never through
ActivateClickHandler(), whose crl::on_main call would run only after the
stage returned. For each time it sleeps on the main thread until then,
drains the postponed calls — Manager::update() skips while the manager's
own schedule() callback is pending, and the drain runs it — calls
Core::App().animationManager().update() once, its only manager call, and
renders. The probe proves each tick and supplies its time: a tick that did
not reach it is refused as manager-did-not-tick, a render that did as
render-advanced-the-manager, each a TEST_RESULT: FAIL: fixture gate: <name>: frame <k> at <ms> ms row, and that frame is not taken. An animation
started inside the action or in a postponed call it posted stands, at a tick
T, somewhere in the reached bounds
[T - actionFinished, T - actionStarted], so judge a painted value against
the transition at both bounds. A time at or after the declared
end, or a frame whose upper bound reached it, is a first-class TEST_RESULT: N/A: <name>: frame <k> at <ms> ms - <reason> gate with nothing rendered,
never a FAIL; a malformed request is one TEST_RESULT: FAIL: fixture gate: <name>: clocked frames refused row, and nothing runs. Each taken frame is
one row, NOTE: <name>: kind=frame index=<k> requested=<ms> reached=[<lo>,<hi>] tick=<ms> waited=<ms> probeTicks=<n> renderTicks=<n>
(ClockedFrameText). Every number in these rows is an ordinary integer
until Test::RequestTelemetryNumbers() (test_log.h) and a
TelemetryNumber after it, read once per call, so one call's rows share a
format: the frame row (index=37p requested=4821p reached=[3764p,4829p] tick=37645p ...), the frame 37p at 4821p ms subject, the gate and
refusal reasons (requested 4821p ms is at or after the declared animation end 3764p ms, the tick reached [5937p,6148p] ms, probe calls 59p before and after it, 7293p ms after the action started, waited 8352p ms, called 41p time(s) during the render) and the request refusal's details
(exactly one of action and handler must be set (action=1p handler=1p),
elapsed times must be non-negative and strictly increasing, read 4821p,3764p). A judge reads a value of either grammar with
float(v.replace('p', '.')). ClockedFrameText, ClockedFrameSubject,
ClockedEndGateText, ClockedReachedGateText, ClockedNoTickText,
ClockedRenderTickText and ClockedRequestRefusal also take an explicit
NumberFormat; a gate or refusal text kept in a ClockedFrame or
ClockedRun keeps the format it was formatted in. The caller's elapsed
times and animationEnd are among those numbers, so under the request they
print in a format that hides digits from the secrecy scan: they must never
be a fixture secret or a number read from one.
Render with Test::GrabWidget / Test::GrabRect,
which are QWidget::render, never with repaint() or processEvents();
keep the render cheap and save images after the run: Run 4 of the same
campaign took a ~140 ms pair capture per frame, and its +100 / +160 ms ticks
landed at 181 / 324 ms. Gate anim::Disabled(), which makes the first tick
jump to the end, and scale times by anim::SlowMultiplier(). Choose by the
subject: when the product's own paint sequence is measured — back-to-back
paints, a bound from a paint — use PostPaintSampler, which samples only
after real product paints and so needs a shown, exposed, painting window
(Test::KeepWindowExposed keeps one that another application covers
exposed without activating anything);
when a Ui::Animations value at a known elapsed time is measured, use the
clock, which awaits no paint and so runs the same in a minimized window or
on a never-shown widget. Neither advances a streamed video player, which
paces itself with its own base::Timer (see the failure row for an inline
video or GIF that stays on one frame). Confirm with
AppendAnimationClockSelfTest, which clocks a 200 ms linear bar started
from a click handler on a never-shown child of the primary window.

Compare a rounded corner of a media or bubble with a twin or a reference
through test_corner_patch.h, not through pixels read by hand. Each reading
takes a CornerPatch: a device-pixel QImage cropped at a named
PatchCorner inside the media's bounding box, about
Ui::BubbleRadiusLarge() + 2 logical px square so that its corner-most
pixel lies beyond the arc and its opposite corner inside the media, and a
media colour sampled inside the media away from the arc and from any chrome;
a coverage map assumes that colour is locally uniform near the arc.
ReadCornerBackground reads the background at the patch's own corner-most
pixel (CornerMostPixel) and keeps only the 4-connected component of pixels
exactly that colour, so a background-coloured glyph the media encloses is
never background. ReadCornerCoverage maps each pixel's media share on the
channel where media and background contrast most. CompareCornerCoverage
compares two patches of one corner by those maps, both read against the
reference's background, so capture both twins over one base: twins whose
media colours differ but whose arcs match compare equal, while another
radius, a square corner or a one-pixel arc shift does not, and the worst
pixel, its delta and the count over the tolerance are printed on both
verdicts. Pass kCoverageSameKind (0.03) within one media kind and
kCoverageCrossKind (0.06) across kinds. ReadCornerContainment checks
that every background pixel of the reference stays background in the
subject; a second reference with another media colour widens the mask by the
zero-coverage pixels both share that stay connected to the corner, such as a
shadow. Chrome — a corner-status badge, an enlarge badge — is left out only
through GateCornerChrome, gated on a twin or reference that does not draw
it: the gate refuses a region touching an arc or background pixel there, and
the compare and the containment refuse a chrome the gate did not accept
instead of applying it. A reading that cannot be made is refused by name,
its predicate is false and every value it did not measure prints none:
ReadCornerBackground refuses empty-patch, media-missing,
media-at-corner and background-reaches-inner-corner;
ReadCornerCoverage empty-patch, background-missing, media-missing
and contrast-too-low; GateCornerChrome region-empty,
region-outside-patch, gate-background, gate-coverage,
chrome-touches-arc and chrome-touches-background;
CompareCornerCoverage corner-mismatch, size-mismatch, reference,
chrome-refused, chrome-mismatch, subject and
subject-background-differs; ReadCornerContainment size-mismatch,
second-reference-size-mismatch, reference, chrome-refused,
chrome-mismatch and empty-mask. The hand-written readings it replaces
produced false FAILs in Runs 1 and 5 of
2026/10/06/round-rich-message-edge-media-like-ordinary-media (the three
corner-patch rows under Failure diagnosis). Confirm with
AppendCornerPatchSelfTest, over synthetic patches rounded with the
product's own Images::CornersMask at both bubble radii.

Measurements cross three coordinate systems, and each has a fixed contract.
CaptureWidget / CaptureRect / CaptureMappedRect take widget LOGICAL
rects; the image they produce — like every Ui::GrabWidgetToImage grab —
holds logical-size × style::DevicePixelRatio() DEVICE pixels, so Crop
and any direct QImage sampling index device space. Multiply logical values
by the image's devicePixelRatio() exactly once, at the sampling boundary.
TDESKTOP_TEST_SCALE is a third, independent multiplier: it scales the
logical style metrics themselves, so derive expected geometry from the live
scaled tokens, never from literals recorded at 100%. Rects from different
widgets never share an origin by accident — map both through one declared
frame (Ui::MapFrom, mapToGlobal) before comparing, cropping, or
clicking.

Helper catalog Copy Chapter

Test::Check's third argument is an observation, not a failure excuse. It is
printed on both verdicts — TEST_RESULT: PASS: <what> - and
TEST_RESULT: FAIL: <what> - — so a green log says what each check
was made against and a passing run can be audited without re-running it. Pass
the values the check judged: the measured geometry, the observed identity, the
window and the rows behind the verdict. Text that is only true after a failure
stays conditional at the call site — ok ? QString() : u"out of tolerance"_q —
which leaves the passing line exactly TEST_RESULT: PASS: <what>, the same
line an empty details produces. Do not emit a Note beside a check only to
print a reading that check's own details could carry; that duplication is
what this argument replaces. Where the failure text cannot double as a true
passing observation, the details stay conditional and an adjacent Note
remains the carrier — CheckBlockedLaunchesExactly suppresses its mismatch
text on a pass and keeps its Test::Note(u"blocked launch record: [...]"),
which is what test_launch_fuse.h promises. None of this loosens a refusal:
failure text still has to name what it judged, and an undecidable reading is
still refused rather than printed as a Note a reader would take as a
measurement.

Read the selected module's header before using it; the contracts there are
more precise than the summary above. Search this directory before writing a
new local helper: an overlay that reimplements a shared facility is a test
flaw like any other, because the local copy carries none of the refusals the
shared one accumulated. One overlay rebuilt grab-check-save by hand after
CaptureWidget had already refused blank and hidden targets for months.

Building one reliable packed scenario Copy Chapter

1. Derive every falsifiable check from the task, visual contract, and retained
   diff before writing overlay code.
2. Choose the most direct fixture that still executes the changed production
   code. Publish exact objects/actions at construction and callback seams when
   unrelated navigation would be the fragile part.
3. Arrange nondestructive states first and destructive/closing actions last.
   Reuse one live fixture through its empty, rich, long, error, retry, light,
   and dark states when those transitions are production behavior.
4. Put readiness and generation checks in until; put actual-versus-expected
   values in then or captureAndInspect.
5. Log every value needed to diagnose a failure in the first run. A timeout
   should name the last object generation, visibility, geometry, state, and
   callback count instead of forcing a speculative second overlay edit.
6. Save decisive tight captures as the scenario reaches each state. Do not
   postpone all visuals to the end, after later actions have replaced them.
7. Finish with guards: no undeclared OS launch, no real payment/network call
   when mocked, expected callbacks exactly once, and no leftover expectation.

Account fixture secrets Copy Chapter

The golden test_TelegramForcePortable folder may carry secrets beside
tdata. Today those are 2svpassword.txt and test_gram_account.txt.
2svpassword.txt is the test account's two-step verification (cloud)
password, which the server demands on wallet.exportSecretPhrase,
wallet.replaceWallet and the password route of wallet.disableBackup
(PASSWORD_MISSING without it, SRP_ID_INVALID for a fabricated proof).
wallet.enableBackup, which has no password field, and the proof route of
wallet.disableBackup prove key ownership instead of sending the password. A
scenario reads it at runtime through
Test::TwoStepPassword() — whitespace-trimmed, std::nullopt when the file
is absent or blank, always std::nullopt outside test-agent mode — and the
generic Test::FixtureSecret(name) reads any sibling file the same way. Both
look in the live portable folder first and then in the golden sibling, so a
file added to the golden folder after a marked live copy was made is still
found.

Type the value into the product's own PasscodeBox so the real SRP path
computes the proof; never assemble an InputCheckPasswordSRP by hand. When a
selected check needs the password, the file's presence is gated before the
scenario is authored and its absence blocks the task (pipeline.md, Phase 3
step 5); a scenario that still reaches a missing file at runtime refuses with
a named fixture gate (fixture gate: 2svpassword.txt absent), never a
product FAIL, and never substitutes a driven answer for the leg. The value
never leaves the process: no overlay literal, Note, check details,
capture, evidence file, work/ artifact, receipt, prompt, or environment
variable recorded anywhere may carry it. The overlay is published into the
task repository with the result, so a literal there is a leak, not a
convenience.

test_gram_account.txt is the owner's funded golden wallet: the test
account's server-created wallet, recorded by hand and funded at its address.
The format is the word lines until the first empty line, then the address as
the app shows it; never assume a fixed word count, because a confirmed key
rotation lengthens it. A scenario reads it at runtime through
Test::GramAccount() — the live copy first, then the golden sibling — which
returns the words, the address line and addressRaw, the address normalized
through Wallet::CanonicalAddress so either form compares; std::nullopt
when the file is absent, has no word line or no address line, and always
outside test-agent mode. The golden sibling is consulted only when the live
copy is absent or blank — a present but malformed live copy answers
std::nullopt rather than masking a different golden file, because after a
rotation the live copy is the authority. The words are under the same rule as
the password: typed or compared in process only, never in overlay code, a
Note, check details, a capture, an evidence file, a work/ artifact, a
receipt or a prompt. Only the COUNT of the words and the address may be
recorded.

A campaign that declares it needs the funded wallet is gated on it at
campaign start, before anything is spent: the file must be present;
GramAccount()->addressRaw must equal *wallet.address() once
WalletRefreshSettled accepted the served state — a mismatch FAILS the run
and is never repaired by /wallet_reset, wallet.replaceWallet or a minted
wallet; and the balance must cover every planned live leg plus a margin — a
shortfall refuses with a named fixture gate (fixture gate: golden wallet balance short) and the performer publishes the task-local Block naming the
address and the amount required, never a driven workaround. Campaigns on the
golden wallet never reset it and spend only what a leg needs; state the count
of live legs the run issued. A live leg also satisfies the effective
wallet_transfer_min_nanos floor in force for that account, in addition to
the conservative 0.3 GRAM evidence guidance, which the configured floor does
not replace. No campaign spends a sub-floor amount to observe how the
backend answers: the client's own amount refusal is established from
controlled configuration and local send fixtures, and an at-the-floor
control may stop at fee preview.

After a confirmed key rotation the scenario calls
Test::RewriteGramAccountWords(newWords, addressRaw) from the stage that
observed the confirmation, before any later leg can cut the run off. It
rewrites the word lines of every existing copy — the marked live copy AND the
golden sibling — through QSaveFile, keeping the empty line and the address
line; each copy is parsed on its own and rewritten only when its own address
is the rotated wallet's (the scenario passes the served raw address); a copy
naming another wallet is left alone and reported false. It returns which
copies were written; the stage checks both and re-reads Test::GramAccount()
to compare the count and the words in process. The golden write is the one
owner-decided exception to the read-only golden folder; nothing else in the
harness or in a campaign ever writes there.

The golden tdata is never modified while the file is, so a later campaign's
P0 reconciles the two before anything else — in process, after the address
gate has already passed. Do not hand-roll it: call Test::AppendGramReconcile
(one stage) or Test::ReconcileGramAccount (the flow) from
test_gram_reconcile.h right after the address gate. The two cases remain the
definition: (a) the local custody has FEWER words than the file: the golden
tdata predates a confirmed rotation, so restore custody from the file's
words through the product's own import (Wallet::Session::restoreFromPhrase)
before any other stage; (b) the local reveal differs from the file with an
equal or greater count: the live copy was promoted after a chain-confirmed
rotation but the rewrite was cut off, so rewrite the file from the local
reveal.

A phrase qualifies when it signs for the served key (its signing key — words
13-24 of a 24-word phrase, the anchor of a 12-word one — is
Wallet::Session::publicKey()) and derives the served address (its anchor,
words 1-12, derives *wallet.address()). The helper decides in this order,
and each refusal is a named gate (GramReconcileGate) that writes nothing:

1. Preconditions: NotActive; ServedUnknown (no served address or no
   32-byte served key); FixtureAbsent; FixtureOtherWallet;
   CustodyUnreadable; CustodyBusy (custodyBusy(), a pending rotation,
   or a record still awaiting its server key — such a record "signs with" any
   served key, so it cannot certify the file).
2. NoOp: the file qualifies and a readable current record exists. Nothing is
   written.
3. Case (a), RestoredFromFile: the file qualifies, no current record exists,
   and the local count is below the file's. The local count is 0 when no
   record of the served wallet is held — the fresh golden copy — and otherwise
   implied by the held obsolete record's keys: 12 words when its signing key
   is its anchor, else 24. It is never read by a local reveal: under the
   rotation-following custody model an obsolete record is not the current
   record, so revealPhrase would fall through to the server's
   wallet.exportSecretPhrase. The helper restores with the silent Open grant
   (no chooser opens), then requires a local reveal equal to the file
   (RestoreFailed / ConfirmMismatch otherwise).
4. The file qualifies but (a) does not apply: NoReadableCurrentRecord, the
   detail naming why — the current record is unreadable, the held obsolete
   record is not shorter than the file, or a pre-v4 unresolved record whose
   count is unknown (never revealParked, whose reveal writes custody).
5. The file does not qualify: NoReadableCurrentRecord unless
   revealsLocally(); NoOpenGrant without a silent grant; otherwise the
   local reveal (RevealFailed when it fails), then
   RevealedNotServedKey, RevealedNotServedAddress or
   RevealedShorterThanFile. Otherwise case (b), RewroteFromReveal:
   RewriteGramAccountWords(revealed, served address), then GramAccount()
   is re-read and compared in process (RewriteFailed when the live copy was
   not written, RereadMismatch when the re-read differs).

The stage writes one public GRAM_RECONCILE: row (case, gate, counts,
booleans, public keys and addresses), reports NoOp, (a) and (b) as PASS,
and a refusal as TEST_RESULT: N/A with fixture gate: P0 <gate> - <detail>;
a campaign's funded-wallet legs gate on GramReconcileResult::reconciled().
A fresh golden copy whose keyring is not Open refuses NoOpenGrant (the
detail names the keyring kind) until the protection chooser has been driven
once on that copy. The helper never calls wallet.replaceWallet,
wallet.exportSecretPhrase or any other server method that mutates or
reveals the wallet, never resets and never mints. Its GramReconcileDrive
seam fakes only the served identity and the record facts it names, never
writes a fixture file (DrivenWriteSuppressed), and restores only when the
undriven facts show a same-phrase re-import. Its own acceptance is
Test::AppendGramReconcileSelfTest, on the marked live copy. Every stage of it
that reaches a reveal or a restore is a fixture gate, NoOpenGrant keyringKind=<N>, without the silent Open grant, and a live copy staged to 12
words that case (b) did not rewrite is put back to its earlier words through
RestoreGramAccountLiveWords (the gram_reconcile_restore_staged stage, and
again when the scenario finishes).

Never delete or reset the marked live copy while a campaign may have left a
rotation in flight or unrewritten: SETUP keeps a marked live copy, and only a
manual wipe or test-account-reset discards it — and with it the only copy of
a not-yet-rewritten signing half.

Public identity and log coverage are separate claims. The helpers in
test_publication_identity_scan.h answer two different questions. A
LaunchLogEnumerationReading::decided result establishes which declared
launch log classes were read with controls; it has no clean or secret
verdict. A PublicationIdentityReading decides whether supported complete
presentations of explicitly supplied public inputs occur in those bytes.
Its clean result requires decided coverage, valid supplied scope, completed
bounded parsing, passing matcher controls and zero findings. Neither result
proves that fixture secrets were audited. Only ReadSecrecy / CheckSecrecy
with usable supplied fixture secrets can support that claim; an empty secret
set remains undecided and not clean.

A late synchronous campaign stage can use the actual wrappers directly:

Test::CheckLaunchLogEnumeration();
Test::CheckPublicationIdentity({
    .identity = {
        .firstName = u"Ada"_q,
        .lastName = u"Syntheticriver"_q,
        .username = u"synthetic_public_handle"_q,
        .phone = u"+15551234567"_q,
        .userId = u"7"_q,
    },
});

These example identities are synthetic. The helper never discovers an
account identity or reads a credential fixture. Each wrapper plants a fresh
public control through Note, LOG and MTP_LOG, then uses
SelectThisLaunchLogs. CheckPublicationIdentity takes
PublicationIdentityScanArgs, whose logs member is
LaunchLogEnumerationArgs; both wrappers support its optional
testLogControl, appLogControl, debugLogControl, mtpLogControl and
earlierParts. The pure readers instead take an actual
SecrecyLaunchLogs, a nonempty planted control and optional enumeration
arguments, without planting or printing anything:

const auto logs = Test::SelectThisLaunchLogs({});
const auto coverage = Test::ReadLaunchLogEnumeration(logs, plantedControl);
const auto identity = Test::ReadPublicationIdentity(
    suppliedIdentity,
    logs,
    plantedControl);

plantedControl must already be present in every required class. The four
mandatory ordered rows are TestLog, AppLog, DebugLog and MtpLog, even
when a class has no source. Coverage reuses the strict reader's accepted
bytes: TestLog file, supplied main-log text, and quarter-hour DebugLogs parts
whose first line is their own day index. Window parts start at their last
NEW LOGGING INSTANCE STARTED!!! banner. No modification time participates.
MtpLog requires both Send and Recv headers regardless of source display
name; every required class needs an actual accepted readable source, the
planted control, and any requested named control. Enable DebugLogs for real
campaigns, since absent MTP logging cannot establish coverage.

Only selector metadata marked complete can decide coverage. Invalid or
reversed times, an unspecified/manual selection, the 200-quarter cap,
inconsistent candidate inventories, unreadable sources, absent classes or
controls all refuse by fixed scan/class categories. Exactly 200 quarters is
complete when the next quarter is beyond the end time; 201 quarters is
capped. A missing or foreign window candidate alongside an accepted
controlled part stays visible in counts without claiming its bytes were
examined. Unreadability still refuses. Explicit EarlierParts are scanned
whole and require a valid part name, valid matching day and their own
nonempty present per-part control; they are never inferred from other files.

The identity grammar is finite and applies only to supplied descriptors:

• Profile: a complete multipart display name with Unicode
  letter/number/mark/underscore boundaries, or supplied first_name and
  last_name strings in one recognized TL user object. An isolated
  one-part name is insufficient; a structured one-part profile also needs a
  supplied username, phone or id matched in that same object. Names use NFC,
  Unicode case folding and collapsed whitespace, with at most 256 UTF-16
  units per supplied component. Objects, siblings, entries and sources do
  not share profile fields.
• Username/link: the complete supplied username as a bounded token,
  @username, t.me/username, http[s]://t.me/username,
  http[s]://telegram.me/username or tg://resolve?domain=username.
  A complete username path component in screenshot metadata counts too.
  Longer handles, partial names and underscore continuations do not count;
  overlapping spellings of one occurrence count once. Inputs use ASCII
  letters, digits and underscores, include at least one letter, are at most
  64 characters and match with ASCII case folding.
• Phone: the complete international number, canonical or with ASCII
  spaces, balanced nonnested parentheses and hyphens, or full digits at a
  plain phone label or recognized user.phone field. The descriptor is
  + and one to fifteen ASCII digits, starting with a nonzero digit.
  Candidate-local normalization never joins arbitrary numbers across a log
  line. Suffixes, partial numbers and longer digit runs do not count.
• User id: an exact canonical positive decimal of at most twenty ASCII
  digits, at plain user_id=<decimal> / user_id: <decimal>, or the TL
  owner/field pairs user.id, userEmpty.id, userFull.id,
  peerUser.user_id, inputPeerUser.user_id, inputUser.user_id.
  The innermost object owns the field. Tiny positive ids still count there;
  generic id, wrong-parent fields, request ids, timing, coordinates,
  counters and transport integers do not count. Caller-defined schemas and
  computed-field exemptions are unavailable.

The TL writer grammar is { constructor, field: value, } with quoted
strings. It decodes \\, \", \n and the logger's visible separator
escapes \u000A, \u000B, \u000C, \u000D, \u001C, \u001D,
\u001E, \u0085, \u2028, \u2029 deliberately, without repeatedly
decoding escaped backslashes. Quotes keep braces and apparent fields inside
strings from changing ownership. Each physical TestLog row is an entry;
visible separators can encode a multiline profile within that row. The
additional parser state is bounded to 32 object frames, 4096 decoded UTF-16
units per string and 256 logical lines per open profile. Relevant
unterminated strings/profiles, unsupported escapes, lost object scope and
limit exhaustion refuse with fixed parser categories, including at entry,
source and final EOF boundaries. Empty/unusable supplied scope or any
nonempty malformed/over-limit descriptor refuses, even if another supplied
family is usable. Every usable family also needs its independent positive
and coincidence-negative in-memory matcher controls.

Plain, Send and Recv presentations count for identity publication; server
origin is no exemption. Identity has no computed-field exemptions. These
are bounded claims about the supplied identities and supported shapes,
not a general PII detector or an audit of unread credentials.
LOG_ENUMERATION_* and PUBLICATION_IDENTITY_* rows contain only fixed
class/family/selection/refusal names and counts. They never echo identities,
controls, paths, source names or matched lines. Wrapper nonce setup is a
separate PUBLICATION_AUDIT_CONTROL row. Fixed schema words or small counts
may coincide with a supplied tiny name/id; that coincidence is not value
emission. AppendPublicationIdentityScanSelfTest independently exercises
coincidences, presentations, enumeration, accepted selection, claim
separation, parser bounds and actual formatter/wrapper output, without an
account or network.

Proving no fixture secret reached the logs. A funded-wallet campaign proves that no recovery word, 2SV password, custody
record id or secret ref reached the test log, the app log or DebugLogs by
calling Test::CheckSecrecy(args, what) (test_secrecy_scan.h) once, from a
late stage's then, instead of grepping by hand. Hand it, in
SecrecyScanArgs::secrets:

• phrases: GramReconcileResult::phrases (the file's words and every
  revealed phrase), plus any rotated phrase the run produced later;
• shortSecrets: *Test::TwoStepPassword() when the campaign used it;
• tokens: Test::GramCustodySecretTokens(session) taken at P0 AND again at
  the scan (a restore or rotation mints a new record id), which lists every
  record id, secret ref and secret/ storage key of the custody store.

Declare computed fields in SecrecyScanArgs::computedFields only as described
under Declared computed fields below. The MTProto transport's own
integer-only DEBUG_LOG lines need no declaration: the scan carries them
(Plain-line sites).

A campaign that calls CheckSecrecy also calls
Test::RequestTelemetryNumbers() (test_log.h) unconditionally at its first
stage, before any row the scan may read, never under a condition and never
from code that read a fixture secret. From then on the shared helpers print
the numbers they measure, count or time - the GEOMETRY:, CheckNear,
post-paint, clocked-frame, probe and scan rows - as TelemetryNumbers, whose
digit runs the scan never counts, so no number such a helper printed can
fail the scan by coincidence (the shared-helper row under Failure
diagnosis); the caller text in those rows stays the caller's to format. The
call logs TELEMETRY_NUMBERS: requested once, and a row formatted before it
keeps ordinary integers.

The values stay in memory: the helper prints counts, public file names, TL
schema identifiers and the heads and field names of plain-line sites only,
never a secret, a field's value, a length or a whole scanned line.

• Classes and identity. It reads five classes: TestLog
  (test_log.txt), AppLog (the main log through Logs::full(), the text
  the logger holds), DebugLog and MtpLog (every DebugLogs/log_HH_MM.txt
  / mtp_HH_MM.txt part named for a quarter hour in [process start, scan]),
  and EarlierParts (only parts named in earlierParts). A part is accepted
  only when its first line is its own day index (yyyyMMdd); otherwise it is
  Foreign, Missing or Unreadable. A window part is scanned from its last
  NEW LOGGING INSTANCE STARTED!!! banner, so an earlier same-day launch's
  lines are not charged to this one. No last-write time takes part anywhere.
• Matching. A phrase counts as any ordered adjacent pair of its words
  (case-insensitive). Words are letter-and-digit runs: whitespace,
  punctuation (commas, quotes, brackets), a dump string's \n, \t,
  \\ and \" escapes, the dump's type tags ([STRING]) and the test
  log's \uXXXX escapes all separate them, and a run carries across the
  lines of one file. A phrase one word per line, comma-joined, escaped in a
  dump string or dumped as a one-element-per-line vector therefore still
  counts; a number is neutral, and any other word or an entry header ends
  the run. A short secret counts only when bounded — no letter or
  digit right before or after it; embedded occurrences are reported and never
  count. A token counts on every substring occurrence; a token shorter than 16
  characters is refused as "not a token; hand it as a short secret".
• Direction. MTP dump entries are classed by the transport's own
  Send: / Recv: header. Only what the client wrote — plain lines and
  Send entries — decides. Recv hits are server-sent content (a received
  value that holds a short secret by coincidence, or chat text that happens
  to hold two adjacent BIP-39 words) and are reported with their
  <top>/.<field> schema site in SECRECY_RECEIVED, never deciding.
• Plain-line sites. Every bounded short-secret hit in a plain line is
  reported at its <file>|<head>|<field> site, in its class's
  SECRECY_CLASS row (plainSites) and in that class's SECRECY: <class>
  subjects. The head is the message text after the app log's
  [yyyy.MM.dd hh:mm:ss] , a DebugLogs entry's [hh:mm:ss.zzz tid-index]
  or an mtp_ entry's (dc:<dc>) (a test-log row has no prefix, so its
  head keeps NOTE: ), up to the first name= field: an ASCII identifier
  at the message start or after a space, outside double quotes. A value runs
  to the next space, less a trailing ;, ,, . or : and one enclosing
  pair of quotes; <field> is the name of the field whose whole value the
  hit is, or -. The whole site is withheld as <file>|?|?, for every
  reason alike, when the line has no field, the hit lies in the head, the
  head is longer than 64 characters or holds anything but ASCII letters,
  digits, spaces and _.:-/, or the head (with the field name) holds any
  given secret. No value, length, offset or line is printed.
  One kind of line with no field still gets a site: the scan carries the
  MTProto transport's own DEBUG_LOG lines whose every placeholder prints
  one integer (TransportLines() in test_secrecy_scan.cpp: each format as
  its function in mtproto/session_private.cpp, mtproto/session.cpp or
  mtproto/mtp_instance.cpp writes it, and which of its numbers the client
  computes). A line is carried only in a DebugLogs/log_HH_MM.txt part (a
  window part or an accepted earlier part; never test_log.txt, the app
  log or an mtp_ part), and only when it is exactly a
  [hh:mm:ss.zzz tid-index] entry start in ASCII digits with no
  (dc:<dc>) , then the format with each placeholder one integer - an
  optional - and ASCII digits, nothing else - then DEBUG_LOG's
  ( : <digits>) and the end of the line. Its site is
  <file>|<head>|<slot>: the head is the format's own text before its
  first number, cut at the first character a head may not hold, and
  <slot> the table's name of the number whose whole integer, minus
  included, the hit is, or - for any other position. A hit before the
  first number, or a head and slot name that would print a given secret,
  keeps the withheld site, and so does every other shape: an added field,
  trailing text, another source file in the suffix, or a sign, decimal or
  digit the product never prints there.
• Declared computed fields. The fourth trap: a value the product
  computes and formats into its own diagnostic line can equal a short
  secret, and a count alone cannot tell that from a leak. Declare such a
  field in SecrecyScanArgs::computedFields as { .head, .field }, spelled
  exactly as its site prints them, only when the product source shows that
  the field is formatted from a value the product computes, never from
  fixture input; name that formatting site (file and function) in the
  campaign's test design, and decide from the site row and the source,
  never from the matched line. A hit that is exactly that field's value on
  a line with that head is reported in SECRECY_COMPUTED and never decides.
  The same value in any other field, in free text or in part of the value,
  a withheld site, and every word run, token and Send-entry hit still
  decide; a declaration that matches no printed site changes nothing.
  A carried transport line (Plain-line sites) needs no declaration, and
  a campaign declares nothing for it: its numbers belong to the product,
  not to a campaign - a launch with DebugLogs on can print them whatever
  the campaign does - a declaration needs a name= site such a line does
  not have, and a table tied to its product functions and proven by the
  scan's own self-test keeps the exemption out of a campaign's reach, so
  no harness or overlay row can be exempted this way. Only a slot that the
  product source shows the client computes or keeps itself - a size or
  count, its own clock, its routing state such as a dc id, a request id of
  its own maps, an id it generated - is computed; a number read straight
  from the server's bytes (an acked or received msg_id, a server time, a
  server salt) and a number glued to a letter stay deciding, and no
  declaration changes that. A hit that is exactly a computed slot's whole
  integer is reported in SECRECY_COMPUTED and never decides; the digits
  under its minus, another slot or position of the line, the suffix's line
  number, and every word run, token and Send-entry hit still decide, and
  the bounded and embedded classes are unchanged. The carried lines come
  from
  2026/10/13/keep-the-secrecy-scan-from-counting-a-coincidental-transport-number.
  A number an overlay prints into its own telemetry row is never such a
  field: print it with Test::TelemetryNumber instead (the overlay
  telemetry row under Failure diagnosis). Nor is a number a shared helper
  prints into its own row - a GEOMETRY: row, a CheckNear verdict, a
  post-paint, clocked-frame, probe or scan row: ask with
  Test::RequestTelemetryNumbers() at the first stage, or convert the
  helper (the shared-helper row under Failure diagnosis).
• Controls and canaries. A zero is certified only when it can be told
  from absence. The call plants a fresh public nonce through Note, LOG and
  MTP_LOG and requires it in every non-earlier class; a named control
  (testLogControl, appLogControl, debugLogControl, mtpLogControl, for
  example the served key hex or wallet_getState) must also be hit. A class
  is undecided with no accepted file, an unreadable part, no planted control,
  an absent named control, or an mtp_ part without headers of both
  directions. In-memory canaries run every given secret through the same
  matcher and dump walk on every call; a failing canary leaves the scan
  undecided.
• Output. One SECRECY: <class> DiscriminatingScan report per class,
  then the rows SECRECY_SCAN, SECRECY_WINDOW (every window candidate's
  identity), one SECRECY_CLASS per class (with its plainSites),
  SECRECY_RECEIVED and SECRECY_COMPUTED (the count of exact-value hits
  on declared fields and carried computed slots, with each one's
  <class>|<file>|<head>|<field> site, never the value), then three
  checks: <what>: every class decided, <what>: no client-written fixture secret, and <what>: the scan's own rows carry no fixture secret (the bytes
  it appended to test_log.txt, re-read). It returns decided && clean.
  The SECRECY: <class> reports are DiscriminatingScan rows and follow
  Test::RequestTelemetryNumbers() like any other: after the ask their
  examined=, subject(...)= and control(...)= counts, and a refusal's
  counts, print as TelemetryNumbers. The SECRECY_SCAN, SECRECY_WINDOW,
  SECRECY_CLASS, SECRECY_RECEIVED and SECRECY_COMPUTED rows and the
  three checks keep ordinary integers in both modes: they also print
  identifiers whose digit runs no number format removes (window times,
  DebugLogs part names), and judges read their counts as integers. The
  own-rows check re-reads exactly the bytes the call appended, whatever
  their format.

DebugLogs must be enabled (tdata/withdebug = 1), or the DebugLog and
MtpLog classes are undecided — MTP_LOG writes nothing without it. The scan
covers logs only: the post-run grep of promoted evidence, work/ artifacts
and receipts for 64-hex and UUID tokens stays the performer's job. The
matcher's own acceptance is Test::AppendSecrecyScanSelfTest, session-free,
over synthetic log trees and synthetic secrets.

Media fixtures and fixture gates Copy Chapter

A media document is a fixture only after the run has watched it play. Metadata
does not decide this: an undecodable upload left on the shared test account can
report song=1 audioFile=1 sharedMusic=1 with a plausible duration, so no
predicate over flags, title, performer, filename, or membership in some list can
tell it apart from real music. “The first song not already in profile Saved
Music” is exactly such a predicate, and it accepts an undecodable upload.
Observe playback instead:

1. Order the candidates the account already exposes by playability signals —
   already downloaded, then a longer duration, then a non-empty title or
   performer — and push known-synthetic names behind every other candidate.
   The order is a preference; nothing on it is trusted yet.
2. Really play each candidate in turn, through the ordinary production path
   (Window::SessionController::openDocument() with that candidate's own
   message as its MessageContext), and sample
   Media::Player::instance()->getState(AudioMsgId::Type::Song) around a
   bounded wait. Accept the first candidate whose TrackState::position
   strictly advances while length > 0 and the playing id and context are
   still that candidate's own document and message.
3. Stop the probe with Media::Player::instance()->stop(AudioMsgId::Type::Song)
   after every attempt and assert the player is stopped, so no probe state
   leaks into the measurement that follows.
4. Feed the one validated document to every stage that needs it — the fixture,
   any injection, and the negative control — instead of re-deriving it per
   stage.

The reported length corroborates a probe's verdict but never decides it.
Until the stream reports its own duration,
Media::Streaming::Player::prepareLegacyState() substitutes the document's
declared duration, so a length equal to the declared duration means only that
no stream duration has arrived yet — a healthy candidate sampled early reads
the same way. It is a bad sign only together with a position that never
advances, while a document that really opened reports a stream-measured length
instead (len=272910 against a declared 272000). Keep acceptance anchored on
the strict position advance.

When a scenario's subject needs a streaming fixture, a stage immediately before
the measured action must prove the track is already advancing while the subject
still exists. Classify that stage as a fixture gate, not a check: reverting the
diff under test cannot change its reading, so its failure makes the acceptance
criteria N/A and the run a test flaw — never a FAIL. Without that gate, a
frozen reading taken after the action cannot be told apart from the product
failing.

Scenario teardown before quit Copy Chapter

A scenario that deliberately leaks its State so it outlives a stage owns the
release of everything that State holds: every rpl::lifetime, every
watcher, every raw cross-stage pointer, and every base::Timer. Register
that release with Runner::onFinish. finish() runs those callbacks on
every path that reaches it — stage timeout, the scenario watchdog,
skip-to-end, and normal completion — exactly once, after the ticker and
watchdog are cancelled, before the kFinishDrainDelay fuse drain, and
before Complete() / Core::Quit(). A callback registered after finish()
has already run executes immediately and is never silently dropped.

A final teardown stage is still useful for work that must happen while the
session still exists and the runner is still stepping, but it is not the
release point. The stage is not guaranteed to run: a stage that times out,
and the scenario watchdog, make Runner finish immediately and skip every
stage after it, while a stage whose assertions FAIL does not — that run
still reaches its teardown. onFinish still runs in those abort paths, and
it also runs when a teardown stage already ran, so the callback must be safe
to call after teardown.
A main-window geometry change belongs in such a stage, one that waits for
the change to settle, and never in onFinish: it releases nothing and
starts an asynchronous chat-background re-cache that must not still be
painting at quit (see the d->allThreads.isEmpty() row under “Failure
diagnosis” below).

Skipping the hook costs a whole run. A leaked State whose two
rpl::lifetimes were never released kept observers subscribed to
Storage::Facade's and Data::Session's streams while ~Main::Session tore
those streams and their items down. The run reached TEST_COMPLETE after a
clean sweep and then died with Caught signal 11 (SIGSEGV), no assertion line
anywhere in the run's logs, and a 0-byte minidump because the runner had to
kill the process. With the release registered, three consecutive runs exited
0, wrote no crash report and left no minidump. After a timeout the same death
can follow TEST_COMPLETE, so read it as this signature rather than as a
second product fault, and keep the leaked State's session-observing
subscriptions no wider than the stages that need them.

Failure diagnosis Copy Chapter

Classify a sound assertion against changed behavior as an implementation bug,
not a test flaw. Classify a wrong fixture, target, readiness model, event
route, capture owner, or oracle as a test flaw. Preserve everything a failed
run proved, repair all visible harness faults together, and rerun the packed
scenario rather than fragmenting it into isolated launches.

When a flaw's cause is the instrument idiom rather than this task's fixture,
repair it here as well as in the overlay: add the missing helper, tighten an
existing contract, or add its row to the table above, in the same run that
diagnosed it. A diagnosis that stays in one task's notes is rediscovered by
the next task, which is how the Test::Probe window row and the
Test::DiscriminatingScan row above cost four runs each before they were
written down.

Api Credentials (`docs/api_credentials.md`) Copy Section

Obtaining your API credentials Copy Chapter

To build your version of Telegram Desktop you're required to provide your own api_id and api_hash for the Telegram API access.

How to obtain your api_id and api_hash is described here: https://core.telegram.org/api/obtaining_api_id

If you're building the application not for deployment, but only for test purposes you can use TEST ONLY credentials, which are very limited by the Telegram API server:

api_id: 17349
api_hash: 344583e45741c457fe1862106095a5eb

Your users will start getting internal server errors on login if you deploy an app using those api_id and api_hash.

Building Linux (`docs/building-linux.md`) Copy Section

Build instructions for Linux using Docker Copy Chapter

Prepare folder Copy Section

Choose a folder for the future build, for example /home/user/TBuild. It will be named BuildPath in the rest of this document. All commands will be launched from Terminal.

Obtain your API credentials Copy Section

You will require api_id and api_hash to access the Telegram API servers. To learn how to obtain them click here.

Clone source code and prepare libraries Copy Section

Install poetry, go to BuildPath and run

git clone --recursive https://github.com/telegramdesktop/tdesktop.git
./tdesktop/Telegram/build/prepare/linux.sh

Building the project Copy Section

Go to BuildPath/tdesktop and run (using your api_id and api_hash)

docker run --rm -it \
    -u $(id -u) \
    -v "$PWD:/usr/src/tdesktop" \
    tdesktop:centos_env \
    /usr/src/tdesktop/Telegram/build/docker/centos_env/build.sh \
    -D TDESKTOP_API_ID=YOUR_API_ID \
    -D TDESKTOP_API_HASH=YOUR_API_HASH

Or, to create a debug build, run (also using your api_id and api_hash)

docker run --rm -it \
    -u $(id -u) \
    -v "$PWD:/usr/src/tdesktop" \
    -e CONFIG=Debug \
    tdesktop:centos_env \
    /usr/src/tdesktop/Telegram/build/docker/centos_env/build.sh \
    -D TDESKTOP_API_ID=YOUR_API_ID \
    -D TDESKTOP_API_HASH=YOUR_API_HASH

The built files will be in the out directory.

Visual Studio Code integration Copy Section

Ensure you've followed the instruction up to the Clone source code and prepare libraries step at least.

Open the repository in Visual Studio Code, install the Dev Containers extension and add the following to .vscode/settings.json (using your api_id and api_hash):

{
    "cmake.configureSettings": {
        "TDESKTOP_API_ID": "YOUR_API_ID",
        "TDESKTOP_API_HASH": "YOUR_API_HASH"
    }
}

After that, choose Reopen in Container via the menu triggered by the green button in bottom left corner and you're done.

Building Mac (`docs/building-mac.md`) Copy Section

Build instructions for macOS Copy Chapter

Prepare folder Copy Section

Choose a folder for the future build, for example /Users/user/TBuild. It will be named BuildPath in the rest of this document. All commands will be launched from Terminal.

Note about disk space: The full build process will require approximately 55 GB of free space. This includes:

• ~35 GB for libraries (when building for both x64 and arm64 architectures)
• ~20 GB for the compiled Telegram app (in the out folder)

Obtain your API credentials Copy Section

You will require api_id and api_hash to access the Telegram API servers. To learn how to obtain them click here.

Clone source code and prepare libraries Copy Section

Go to BuildPath and run

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install git automake libtool cmake wget pkg-config gnu-tar ninja nasm meson

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

git clone --recursive https://github.com/telegramdesktop/tdesktop.git
./tdesktop/Telegram/build/prepare/mac.sh

Building the project Copy Section

Go to BuildPath/tdesktop/Telegram and run (using your api_id and api_hash)

./configure.sh -D TDESKTOP_API_ID=YOUR_API_ID -D TDESKTOP_API_HASH=YOUR_API_HASH

Then launch Xcode, open BuildPath/tdesktop/out/Telegram.xcodeproj and build for Debug / Release.

Building Mas (`docs/building-mas.md`) Copy Section

Build instructions for Mac App Store Copy Chapter

NB These are used for Mac App Store build, after the Build for macOS instructions.

Prepare breakpad Copy Section

Go to BuildPath and run

MACOSX_DEPLOYMENT_TARGET=10.12

cd Libraries

git clone https://chromium.googlesource.com/breakpad/breakpad
cd breakpad
git checkout bc8fb886
git clone https://chromium.googlesource.com/linux-syscall-support src/third_party/lss
cd src/third_party/lss
git checkout a91633d1
cd ../../..
git apply ../patches/breakpad.diff
cd src/client/mac
xcodebuild -project Breakpad.xcodeproj -target Breakpad -configuration Debug build
xcodebuild -project Breakpad.xcodeproj -target Breakpad -configuration Release build
cd ../../tools/mac/dump_syms
xcodebuild -project dump_syms.xcodeproj -target dump_syms -configuration Release build
cd ../../../../..

Building Win (`docs/building-win.md`) Copy Section

Build instructions for Windows

• Prepare folder
• Install third party software
• Choose architecture and initialize terminal
• Clone source code and prepare libraries
• Build the project
• Qt Visual Studio Tools

Prepare folder Copy Chapter

The build is done in Visual Studio 2026 with 10.0.26100.0 SDK version.

Choose an empty folder for the future build, for example D:\TBuild. It will be named BuildPath in the rest of this document. Create two folders there, BuildPath\ThirdParty and BuildPath\Libraries.

The default modern toolset from Visual Studio 2026 (v145) does not support Windows 7, so for Telegram Desktop you must use -vcvars_ver=14.44 (v144.4, based on v143 with Windows 7 support).

Obtain your API credentials Copy Section

You will require api_id and api_hash to access the Telegram API servers. To learn how to obtain them click here.

Install third party software Copy Chapter

• Download Python 3.10 installer from https://www.python.org/downloads/ and install it with adding to PATH.
• Download Git installer from https://git-scm.com/download/win and install it.

Choose architecture and initialize terminal Copy Chapter

Before preparing libraries and running build commands, initialize the Visual Studio environment for your target architecture.
The default modern toolset from Visual Studio 2026 (v145) does not support Windows 7, so for Telegram Desktop you must use -vcvars_ver=14.44 (v144.4, based on v143 with Windows 7 support).

For win (32-bit):

%comspec% /k "C:\Program Files\Microsoft Visual Studio\18\Community\VC\Auxiliary\Build\vcvars32.bat" -vcvars_ver=14.44

For win64 (64-bit):

%comspec% /k "C:\Program Files\Microsoft Visual Studio\18\Community\VC\Auxiliary\Build\vcvars64.bat" -vcvars_ver=14.44

Run both Clone source code and prepare libraries and Build the project sections in the terminal initialized with one of the commands above.

Clone source code and prepare libraries Copy Chapter

In the initialized terminal, go to BuildPath and run

git clone --recursive https://github.com/telegramdesktop/tdesktop.git
tdesktop\Telegram\build\prepare\win.bat

Build the project Copy Chapter

Go to BuildPath\tdesktop\Telegram and run (using your api_id and api_hash):

For win (32-bit):

configure.bat -D TDESKTOP_API_ID=YOUR_API_ID -D TDESKTOP_API_HASH=YOUR_API_HASH

For win64 (64-bit):

configure.bat x64 -D TDESKTOP_API_ID=YOUR_API_ID -D TDESKTOP_API_HASH=YOUR_API_HASH

• Open BuildPath\tdesktop\out\Telegram.slnx in Visual Studio 2026
• Select Telegram project and press Build > Build Telegram (Debug and Release configurations)
• The result Telegram.exe will be located in D:\TBuild\tdesktop\out\Debug (and Release)

Qt Visual Studio Tools Copy Section

For better debugging you may want to install Qt Visual Studio Tools:

• Open Extensions -> Manage Extensions
• Go to Online tab
• Search for Qt
• Install Qt Visual Studio Tools extension

Web Proxy Plan (`docs/web-proxy-plan.md`) Copy Section

Telegram Desktop WEB proxy: refined client design

The hosted half is specified in ../tproxy-server/PLAN.md. Its multiplexing frame
format and MessageChannel contract are authoritative. This document records the
reviewed Telegram Desktop design and the implementation now present in this tree.
The server-dependent execution procedure is intentionally separate in
docs/web-proxy-test-plan.md.

1. Scope and invariant Copy Chapter

WEB is an MTProxy whose primary carrier is one process-wide hidden native WebView:

MTProto session threads
  -> TcpConnection (existing MTProxy obfuscation and AES-CTR)
  -> WebProxySocket (one logical stream)
  -> process-wide WebProxy::Transport (one worker thread)
  -> one hidden platform WebView
  -> injected exact-origin TelegramWebProxy bridge
  -> https://relay.example/[base-path/]?bridge=<derived-capability>#android=<nonce>
  -> HTTPS carrier
  -> hosted relay
  -> stock MTProxy
  -> Telegram

The central invariant is that Telegram Desktop opens no external MTProto socket
while WEB is active. The hidden WebView's platform web engine makes the external
HTTPS connection. The hosted relay sees only bytes already transformed by the
existing MTProxy protocol layer; the MTProxy secret is never placed in HTML or
JavaScript.

The previous local-page/system-browser path remains a fallback. Telegram offers it
only after the hidden WebView is unavailable or has failed its ten-second startup or
health deadline. It never opens a browser automatically.

2. Design decisions Copy Chapter

The initial draft left several architectural choices open. They are now fixed:

1. There is one transport and one hidden WebView per process, not per account. Proxy
   selection is already process-wide, so all accounts using the selected WEB proxy
   share one multiplexed carrier.
2. The transport owns a dedicated QThread. QTcpServer, accepted fallback
   sockets, WebSocket framing, mux state, and queues live there. The native WebView
   stays on the application thread and exchanges bounded messages with the worker.
3. WebProxySocket and the transport are compiled in the main Telegram target.
   connection_tcp.cpp, the only factory site retaining the full ProxyData, is
   already in that target. No reverse dependency from td_mtproto is introduced.
4. The serialized host field stores only the canonical lowercase ASCII/IDNA
   A-label hostname. Scheme, port, path, query, fragment, user info, IP addresses
   (including WHATWG "ends in a number" shorthands such as 127.1 or 0x7f.1),
   and single-label names are rejected. port is fixed to 443; password stores
   the MTProxy secret; user stores the optional base path slug (§3.1).
   Operators should publish WEB hostnames in ACE (xn--…)
   form: ACE input round-trips unchanged on every platform, while a hand-typed
   Unicode host is mapped by the Qt version the build ships (IDNA2003/nameprep
   on the Qt 5.15 Windows builds, UTS #46 nontransitional on Qt 6), so hosts
   containing deviation characters (ß, ς, ZWJ, ZWNJ) or characters newer
   than Unicode 3.2 can normalise to different strings — and therefore different
   capabilities — per platform.
5. WEB entries are entered manually or imported from tg://webproxy /
   https://t.me/webproxy links (see §11); there is no tg://proxy?… form.
6. Inactive WEB entries are not checked and are removed from proxy rotation's
   candidate order in v1. Checking would require activating a WebView carrier and
   must not create background carriers for every saved proxy.
7. The loopback parent is one inline, dependency-free HTML response. A qrc asset
   adds no value for this small page and would create another generated-resource
   dependency.
8. While an explicitly opened fallback page's authenticated loopback WebSocket is
   open, the local parent maintains
   an empty RTCDataChannel between two same-page RTCPeerConnections. This is a
   best-effort Chrome background-lifecycle guard: it uses no media, STUN, TURN, or
   remote signaling, and failure to establish it never fails the carrier.

3. Data model and persistence Copy Chapter

MTP::ProxyData::Type::Web is appended to the enum and serialized as type code 4.
The existing five-field proxy blob remains unchanged:

type | host | port | user | password

WEB maps those fields as follows:

Validation requires a non-empty valid DNS hostname, a canonical base path, and a
supported MTProxy secret. Plain 16-byte and dd random-padding secrets are
accepted; ee TLS-emulation secrets are
rejected because the stock MTProxy would expect an inner TLS-emulation record that
this raw relay deliberately does not add. Unknown future serialized type codes
deserialize to None instead of reaching
Unexpected, so downgrades skip an unsupported proxy rather than crashing.

3.1 Optional base path Copy Section

A WEB proxy address is a hostname with an optional base path,
proxy.example.com or proxy.example.com/dobry-cola-super-app, so a production
origin can keep serving its own site and route only that prefix to the relay.
Every WEB endpoint moves under the prefix together; nothing stays at the root:

no base path:                 base path `dobry-cola-super-app`:
  GET  /?bridge=…               GET  /dobry-cola-super-app/?bridge=…
  POST /api/v1/session          POST /dobry-cola-super-app/api/v1/session
  POST /api/v1/up               POST /dobry-cola-super-app/api/v1/up
  POST /api/v1/down             POST /dobry-cola-super-app/api/v1/down
  GET  /api/v1/ws               GET  /dobry-cola-super-app/api/v1/ws

The address is one field everywhere it is entered, displayed, or shared: the
editor, the confirmation box, the proxy row, and the server link parameter all
carry host or host/path. The path is one or more /-separated ASCII segments,
each matching [A-Za-z0-9][A-Za-z0-9_-]*, at most 128 characters in total, stored
with no leading or trailing /. %xx escapes, Unicode and empty segments are
rejected rather than repaired, so the serialized value and the wire path are the
same string; . is not in the alphabet, so dot segments cannot occur. The host is
case-insensitive and stored lowercased, while the path is case-sensitive and never
folded, so Proxy.Example.COM/My-App normalizes to proxy.example.com/My-App,
and a pasted https:// prefix is stripped on save. Only the trailing-slash
form /<slug>/ is served; the client never requests /<slug> and the relay is not
expected to redirect it, which would add another observable branch.

The slug is a namespace, not a credential: it isolates the relay from the rest of
the site and keeps generic scanners away from the carrier endpoints, but the
bootstrap capability, session bearer, and MTProxy secret remain the authentication.
A random slug raises the cost of finding the deployment; it does not replace any of
them. Storing it in the otherwise unused user field keeps the serialized proxy
blob unchanged and makes a client without this feature report the entry as invalid
instead of silently connecting to the host root.

WEB behaves like MTProxy throughout the existing model:

• secretFromMtprotoPassword() accepts WEB.
• Qt's application proxy is NoProxy; WEB does not affect update or generic HTTP
  traffic.
• custom DC/proxy DNS resolution is disabled because the WebView engine, or the
  explicitly selected browser fallback, resolves the relay hostname.
• calls remain unsupported.
• TCP MTProto is enabled and the plain MTProto HTTP connection is disabled.
• DC endpoints are ignored; the hosted relay chooses its fixed stock-MTProxy target.
• initConnection reports the relay hostname and port 443 as client proxy metadata.

4. `WebProxySocket` Copy Chapter

mtproto/details/mtproto_web_proxy_socket.* implements AbstractSocket as a
logical byte stream over the shared transport.

On connectToHost, it registers a new 24-bit stream id. The address and port
arguments are intentionally ignored. It emits connected after the active carrier
has completed the relay WELCOME handshake and the transport has sent OPEN for
that stream.

Writes concatenate the one-time MTProxy connection prefix and body before queuing a
DATA frame. Incoming DATA is buffered and exposed through partial read() calls.
Every successful read replenishes exactly that many bytes of receive credit with a
WINDOW frame. Transport loss emits disconnected; protocol violations, queue
overflow, and explicit transport failures emit error.

The existing TcpConnection continues to own all MTProxy protocol work. For WEB it
uses secretFromMtprotoPassword() and Protocol::Create(secret) exactly as for
MTProxy, then selects WebProxySocket at the one socket-factory call site.

5. Process-wide transport and threading Copy Chapter

mtproto/web_proxy/web_proxy_transport.* provides a main-thread lifecycle facade and
runs all I/O state on its worker thread.

Main-thread lifecycle:

• Activate(proxy) creates the worker on first use, synchronously installs the
  selected valid proxy and creates one hidden WebView when the selected WEB proxy
  changes; the fallback listener stays unbound.
• OpenBrowser(proxy) binds the loopback listener if needed, mints a fresh
  one-shot capability and opens a new tab on explicit user request after fallback
  has been offered.
• Deactivate() closes streams, accepted clients, and the listener when the app
  changes away from WEB, and destroys the hidden WebView.
• Shutdown() runs after MTP accounts have stopped and joins the worker thread.

The WebView candidate performs its own HELLO / WELCOME handshake before the
worker adopts it. Startup, bridge initialization, write acknowledgement, and health
are each bounded. A failed candidate is destroyed and another candidate is tried
after an exponentially growing delay (2 s to 30 s); fallback is offered only once
the failure is terminal (see §8). If a retry succeeds while the browser fallback
is connected, logical streams reconnect through the WebView and the fallback socket
is closed; no relay session is migrated across carriers.

Session-thread interaction uses queued calls into the worker. Each stream stores its
socket context, and worker-to-socket delivery is queued to that socket's owning
thread. WebProxySocket destruction unregisters synchronously on the worker before
the QObject base destructor can invalidate the context. This creates a strict
ordering boundary: notifications already posted remain owned by Qt and are removed
with the QObject, while the worker cannot inspect or post through the context after
unregistration returns. The global transport pointer is atomic and remains alive
until all MTP sessions have been destroyed.

The principal state transitions surfaced to settings are:

Idle
  -> Connecting
  -> Connected
  -> WaitingForBrowser  (WebView unavailable, unhealthy, or failed)
  -> Connecting         (user confirmed the browser fallback)
  -> Connected

WaitingForBrowser
  -> Connected          (a 30-second WebView retry succeeds)

6. Shared relay frames Copy Chapter

All integers are big-endian. The implementation mirrors server plan section 7:

type:u8 | stream_id:u24 | length:u32 | payload:length

Each carrier message must contain one or more complete frames. The parser
accepts concatenated frames and rejects an empty message or trailing partial frame.
A payload is capped at 1 MiB. Known types are:

An incoming OPEN, a stream frame on stream zero, a session frame on a nonzero
stream, malformed WINDOW, data beyond granted credit, an unknown live stream, or
an unknown type is a protocol error for v1. The client retains up to 4096 recently
closed stream ids. Well-formed DATA, WINDOW, and CLOSE already in flight for a
retained id are discarded; this prevents an ordinary cross-direction close race from
failing unrelated multiplexed streams.

7. Flow control and memory bounds Copy Chapter

Both directions start with an implicit 4 MiB per-stream window.

Downlink flow control is exact: relay DATA consumes client receive credit, and
Telegram Desktop grants it back only when WebProxySocket::read() drains bytes into
the MTProto engine. This naturally bounds each socket's unread data.

Uplink has a constraint the initial draft missed: AbstractSocket::write() returns
void and provides no writable/backpressure event, so it cannot stop the MTProto
caller and resume later. The client therefore:

• spends relay-granted send credit before emitting each DATA frame;
• splits outgoing data into at most 64 KiB frames;
• queues excess data per stream;
• coalesces adjacent writes up to 64 KiB and avoids front-removal copies;
• fails the stream if its pending uplink exceeds 8 MiB or 1024 queued items;
• caps all queued cross-thread uplink data at 64 MiB and 8192 items;
• pauses stream flushing when the process-wide loopback socket write queue reaches
  4 MiB and resumes it as bytes drain;
• reserves 64 KiB of that socket budget for control traffic and bounds a separate
  64 KiB / 1024-frame control queue; and
• schedules ready streams round-robin, with at most 256 frames per worker turn.

If the active carrier makes no write progress for 30 seconds, the carrier fails and
normal MTProto reconnect logic replaces it. Exhausting a stream or transport budget
also fails promptly rather than allowing unbounded queued worker events. If
measurements show sustained multi-megabyte uploads can exhaust these bounds, a
future change must add writable backpressure to the AbstractSocket contract rather
than silently growing memory.

7.1 Performance envelope and built-in HTTP comparison Copy Section

The hosted bridge batches up to 2 MiB and runs uplink and downlink concurrently.
Each direction is sequenced stop-and-wait in v1, giving an RTT-only busy-direction
bound of 40, 20, 10, and 4 MiB/s at 50, 100, 200, and 500 ms web-engine-to-relay RTT,
respectively. Actual results include transfer time, the relay-to-MTProxy leg, and
web-engine scheduling. The 4 MiB stream window is two carrier batches so returned
credit does not reproduce the former 256 KiB bottleneck.

The built-in MTProto HTTP transport also copies request/response bodies and uses an
HTTP wait request, but QNetworkAccessManager may keep several POSTs active. WEB is
therefore more RTT-sensitive today. That serialization, fixed batch size, and most
buffer copies are implementation choices; a bounded ordered pipeline or compatible
streaming carrier can narrow them. Inherent WEB cost remains one platform web
engine, an extra relay/TLS path, a native JavaScript boundary, and shared-carrier
head-of-line exposure. The explicit browser fallback adds MessageChannel and
loopback crossings. With a well-placed relay, ordinary messaging and moderate media
should be in the same practical class as the built-in HTTP transport, while direct
TCP/MTProxy remains the latency and peak-throughput reference.

8. Hidden WebView boundary Copy Chapter

lib_webview exposes WindowMode::Hidden, HiddenSupported(), and Window::valid().
Hidden mode creates the platform web engine without a Telegram window or embedded
Qt widget:

• macOS retains a native WKWebView without wrapping it in a QWindow or widget;
• Windows uses modern WebView2 with an invisible controller and no widget container;
• all-other platforms keep WebKitGTK in the existing helper process and attach it to
  an unmapped native GTK toplevel, without creating an embed/compositor widget.

Hidden mode does not install the normal WebView dialog UI. New-window navigation is
rejected. The transport allows only the exact canonical HTTPS bridge navigation.
The bridge is injected only into the top-level document, and native messages are
accepted only from the configured HTTPS origin (compared in ACE form, so IDN hosts
on Qt-whitelisted TLDs work); a message without a source URL is rejected. The
scrubbed https://host/ history URL is accepted for messages but not as a fresh
navigation.

The carrier opens the WebView with restrictedOrigin set, which puts lib_webview
into its restricted profile: an ephemeral, per-carrier storage area; cookies never
accepted; downloads, new windows, subframe navigations, permission prompts,
authentication dialogs and non-https/wss requests to any other host refused;
and a document-start lock script, injected into every frame (so a fresh
about:blank realm cannot bypass it), that installs a <meta> CSP allowing only
inline script and connections to the exact origin, and defines undefined over
storage, workers, audio, speech, WebRTC (RTCPeerConnection and friends),
WebTransport, WebAssembly, notifications, payment, presentation, media capture,
file pickers, navigator.credentials/mediaDevices/getUserMedia/wakeLock/share/xr/ getGamepads/storage/locks/sendBeacon/permissions and similar. The operator's page
therefore only ever gets inline script plus fetch/WebSocket to its own origin.

Engine-level enforcement backs the script per platform:

• Windows (WebView2): the restricted profile owns its own user-data folder and
  browser process; it runs with --disable-features=msSmartScreenProtection
  and IsReputationCheckingRequired = FALSE (so the capability URL is never
  reported to SmartScreen) and
  --force-webrtc-ip-handling-policy=disable_non_proxied_udp (no direct UDP);
  requests to other origins are answered 403 from WebResourceRequested; page
  messages are not echoed back and new-window requests never reach the system
  browser.
• macOS (WKWebView): peerConnectionEnabled and mediaDevicesEnabled are turned
  off through the same KVC path used for developerExtrasEnabled, and on macOS 13+
  the configuration enables Lockdown Mode (no JIT, WebAssembly or WebGL). The
  lock script is a WKUserScript with forMainFrameOnly:NO.
• all-other platforms (WebKitGTK): enable-webrtc and enable-media-stream are
  set to false when the installed WebKitGTK exposes them, the 4.0/4.1 API path
  enables the web-process sandbox (webkit_web_context_set_sandbox_enabled),
  the engine already runs in the separate -webviewhelper process, and the lock
  script is injected with WEBKIT_USER_CONTENT_INJECT_ALL_FRAMES. The helper's
  script-message cap is 2 MiB, enough for a full 1 MiB relay frame in base64.

Debug builds evaluate a probe after the first bridge message and log a line if
RTCPeerConnection, WebTransport or WebAssembly is still reachable in the
top frame or in a freshly created about:blank iframe.

The page receives an exact-origin TelegramWebProxy object at document start. This
uses the same deployed bridge contract as Android: a fresh 32-byte URL-safe nonce in
#android=, tproxy-android-init version 1, and raw relay frames. Since the common
desktop WebView API carries strings, binary frames cross the native boundary as
strict base64 and are acknowledged by monotonically increasing write sequence. The
native queue is bounded to 8 MiB / 1024 items.

The candidate must receive exactly one valid WELCOME, and only after the nonce'd
tproxy-android-init. The handshake deadline is ten seconds, extended by another
ten seconds each time the bridge reports status: connecting|reconnecting (the
bridge's own retry budget is ~23–28 s), up to 45 seconds from navigation start.
Once adopted, the main thread probes JavaScript every three seconds; ten seconds
without a valid bridge message, or ten seconds without the acknowledgement for a
native write, fails the carrier.

The transport keeps at most 512 frames outstanding towards the WebView (control
frames may use the last 64 of them) and coalesces WINDOW grants per stream,
emitting them once 256 KiB accumulate or after 20 ms, so the carrier's hard
1024-item cap is unreachable in normal operation.

When a carrier is dropped after being adopted, the close control is evaluated in
the page and the WebView is kept alive for a further 200 ms so the bridge can send
its DELETE /api/v1/session.

WebView failures are retried with exponential backoff from 2 to 30 seconds (reset
on every successful adoption). The row shows connecting throughout; the
WaitingForBrowser state, and the confirmation box offering the system-browser
fallback, appear only for a terminal failure: hidden WebViews unsupported on the
platform (checked once per activation; nothing is retried), WebView creation
failed, or three consecutive failures without a single adoption. Retries continue
in the background at the maximum interval after that.

9. Explicit system-browser fallback boundary Copy Chapter

The worker binds QHostAddress::LocalHost on an ephemeral port only when the user
asks for the fallback (Open browser), and advertises the numeric origin
http://127.0.0.1:. The listener is closed again once a browser tab has
authenticated, when the minted capability expires unused, when the hidden WebView
takes over, and on deactivation, so there is no listening port unless the fallback
was requested. A page reload after that needs a fresh Open browser.

GET / serves the inline parent with no-store, nosniff, no-referrer, and a
fresh per-response script nonce. Its strict CSP permits only that nonce-bound
bootstrap, the configured HTTPS iframe origin, and its exact local WebSocket
endpoint.

GET /transport upgrades to RFC 6455 only when all of the following hold:

• peer address is loopback;
• method/path are exactly GET / or the /transport upgrade;
• Host is the exact numeric loopback host and current port;
• Origin is the exact loopback page origin;
• Upgrade, Connection, version 13, and a valid 16-byte key are present;
• duplicate HTTP header names are rejected;
• request bodies and transfer encodings are rejected on the local GET boundary;
• the HTTP header block is at most 16 KiB.

Client WebSocket frames must be masked. The parser supports 7/16/64-bit lengths,
text, binary, continuation, ping, pong, and close, with a 2 MiB message cap. Server
frames are unmasked as required by RFC 6455.

An accepted local client must complete capability authentication within ten seconds.
This bounds silent HTTP connections and unauthenticated WebSockets so they cannot
hold all 32 local client slots indefinitely.

The first complete WebSocket message must be UTF-8 JSON:

{"t":"auth","token":"<capability>","browser":"<user agent summary>"}

The capability is 256 random bits, URL-safe base64, carried only in the fragment of
the browser URL. The page removes it from the visible URL immediately. It is
one-shot, expires after five minutes, and is replaced when another tab is opened. A
newly authenticated tab replaces the previous authenticated tab and causes MTProto
streams to reconnect rather than attempting unsupported cross-tab resume.

After authentication:

• the client first sends the text message
  {"t":"bridge","url":"https://<host>/?bridge=<capability>"}; the derived
  capability is therefore only ever handed to a tab that proved possession of the
  one-shot fragment token, never embedded in the unauthenticated GET / page;
• binary WebSocket messages carry one or more shared relay frames;
• text messages from the page may only report bridge state as
  {"t":"status","state":"connecting|connected|reconnecting|failed"};
• pings from unauthenticated clients are ignored.

If an authenticated browser does not return the required WELCOME within 30
seconds, the client fails that carrier and closes its local WebSocket. This turns a
wrong bridge capability, iframe load failure, or ordinary public response into a
recoverable unavailable state instead of leaving the settings row connecting
forever.

10. Parent page and hosted iframe contract Copy Chapter

The local parent reads and scrubs its independent one-shot loopback capability,
connects the local WebSocket, waits for the bridge text message, and only then
creates an iframe (with limited sandbox flags and referrerPolicy set before
src) for that URL, which must begin with relayOrigin + base + '?bridge=', and
establishes a MessageChannel.

The parent also creates two same-page RTCPeerConnections with an empty ICE-server
list, exchanges their descriptions only in local JavaScript, rewrites exchanged host
candidates to 127.0.0.1, and retains an open, otherwise idle RTCDataChannel.
This avoids mDNS/interface-dependent self-connect behavior and keeps RTC packets on
loopback. No RTC state is exposed to the hosted iframe. The guard starts with the
authenticated loopback WebSocket, closes with it or on pagehide, and is recreated
on pageshow or with bounded backoff if the local RTC connection fails. Browsers
without usable WebRTC continue with the ordinary carrier. The guard reduces Chrome
background freezing, intensive timer throttling, and normal automatic discard risk,
but it is not a correctness dependency: manual tab closure, browser or OS
termination, and urgent discard remain ordinary transport loss.

For a canonical hostname H, a canonical base path P (empty at the host root),
and decoded WEB secret bytes S, including the leading dd byte when present, it
computes:

base     = P is empty ? "/" : "/" + P + "/"
context  = P is empty
             ? UTF-8("tdesktop-web-proxy-bridge-v1\n" + H)
             : UTF-8("tdesktop-web-proxy-bridge-v2\n" + H + "\n" + P)
bridge   = base64url-no-padding(HMAC-SHA256(key=S, message=context))
bridgeUrl = "https://" + H + base + "?bridge=" + bridge

The root derivation is the frozen v1 context, byte for byte. A base path uses its
own v2 context so a capability minted for one prefix authenticates nothing at
another prefix or at the root.

Normative vectors:

The derived capability is constructed in memory in tdesktop and is neither stored
nor shown in proxy settings. On iframe load the parent sends exactly:

iframe.contentWindow.postMessage(
  { t: 'tproxy-init', v: 1 },
  relayOrigin,
  [channel.port2]);

The target origin is exact and never *. Binary messages are transferred as
ArrayBuffers in both directions. Frames received locally before iframe
initialization are queued briefly and transferred after initialization. The parent
does not parse shared relay frames and never receives the MTProxy secret. Both the
hosted uplink queue and the parent's local-WebSocket queue are capped at 32 MiB; the
hosted queue also caps retained buffer objects at 16384. Exceeding either bound
closes the carrier instead of growing browser memory without limit.

The iframe's status objects update the visible tab and are forwarded to tdesktop.
When the local WebSocket closes, the parent sends {t:'close'} so the bridge can
delete its relay session. Closing the fallback tab drops the local WebSocket and
disconnects its logical sockets. Telegram Desktop does not reopen a tab
automatically. It keeps trying the hidden WebView with the backoff from §8.
Reloading cannot reuse the scrubbed, one-shot loopback capability (and the
listener is closed once a tab authenticated); after another failure, the
confirmation or row menu can mint a fresh capability and open a new tab.

11. Settings and app integration Copy Chapter

Proxy settings expose a fourth WEB radio option. The editor shows:

• one proxy address field, holding host or host/path, which also accepts a
  pasted https:// prefix and strips it on save;
• one MTProxy secret field;
• no socket host/port pair and no username/password controls.

Rows display only that address. Inactive WEB rows show not tested without creating
a checker, WebView, or browser tab. Only the exact active WEB row shows the live
transport lifecycle. Open browser is offered only after the built-in carrier has
failed. WEB remains unsupported for calls. Because the backend is still MTProxy,
WEB keeps the existing sponsored-proxy disclosure (in the editor and in the link
confirmation) and promotion refresh behavior. Like MTProxy, the WEB hostname is
what initConnection reports as the proxy address; QNetworkAccessManager traffic
outside MTProto is not routed through the WEB carrier.

WEB links use webproxy, a canonical address, and the MTProxy secret. Port 443 is
implicit and is neither accepted from the link nor displayed in its confirmation:

https://t.me/webproxy?server=<address>&secret=<secret>
tg://webproxy?server=<address>&secret=<secret>

<address> is the percent-encoded host or host/path, so a base path travels in
the same parameter as proxy.example.com%2Fdobry-cola-super-app. There is no
separate path parameter. A link that carries a path also encodes its secret as
unpadded base64url of 0x70 plus the real secret, so a client without path
support reports an unsupported proxy type and asks the user to update, instead of
normalizing the address to an empty host and offering to connect to it. A
root link keeps the plain secret and still works in those clients. Following
either link shows the address and secret with one connect action. It does not
check status or enable the proxy until that action is invoked. Saved WEB entries
can be shared as a public link or a direct-scheme QR link.

Application proxy changes configure/deconfigure the web transport before MTP
sessions restart. WEB follows the MTProxy path in Session, SessionPrivate, and
TcpConnection; the global Qt proxy remains disabled for it. Proxy rotation and the
settings availability checker deliberately skip inactive WEB entries instead of
opening a WebView or browser.

12. Constraints and boundaries Copy Chapter

• The listener is IPv4 loopback-only and validates peer, host, and origin.
• Local authentication requires the minted fragment capability.
• The local protocol has no arbitrary destination command. OPEN originates only
  from tdesktop and the relay is expected to dial one configured stock MTProxy.
• The configured value is a canonical DNS hostname plus an optional canonical base
  path; HTTPS and port 443 are fixed.
• The bridge URL contains only the domain-separated derived capability, never the raw
  MTProxy secret.
• Frame, WebSocket, HTTP-header, local-client-count, receive-window, and
  pending-uplink bounds prevent unbounded buffering.
• The parent iframe uses only sandbox="allow-scripts allow-same-origin".
• Payloads and secrets are never logged by this client code.
• WEB socket failures do not invoke tdesktop's direct HTTP time-sync fallback.
• CLOSE is an abort in both directions: undelivered DATA on a closed stream is
  dropped, exactly like tdesktop's existing TCP path, which never half-closes.
• Trust model: the operator is semi-trusted. Their page runs JavaScript inside the
  restricted profile (§8) and never sees the MTProxy secret; the derived
  capability is a stable bearer for (host, secret). A local process cannot obtain
  the capability from the loopback listener (§9); it needs tdata.
• Relay authentication (AUTH_CHAL / AUTH_RESP) is not implemented in v1. Adding
  it requires a fully specified challenge context and server test vectors; it must be
  computed in tdesktop without passing the secret to JavaScript.

13. Hosted-server requirements before execution testing Copy Chapter

The server must provide all of these before the separate test plan can pass:

1. https://<hostname>/[/]?bridge=<derived-capability> implements the
   exact derivation, ordinary-site fallback, MessageChannel, close, and status
   contracts above, with every carrier endpoint under the same prefix.
2. Its CSP allows framing by random numeric loopback origins. A suitable source is
   http://127.0.0.1:*; X-Frame-Options must not block the embed.
3. The bridge accepts the v1 HELLO frame, establishes a reliable ordered carrier,
   and returns WELCOME before stream traffic.
4. The relay implements all v1 stream frames, the implicit 4 MiB windows, and
   deduplicated/cursor-based reliability for polling carriers.
5. Every OPEN dials only the configured stock MTProxy endpoint.
6. The hosted code never logs frame payloads.
7. The v1 HTTPS long-poll carrier is operational; the deployed bridge does not
   require a public WebSocket or another carrier.

14. Implementation inventory Copy Chapter

Core transport:

• Telegram/SourceFiles/mtproto/web_proxy/web_proxy_frame.{h,cpp}
• Telegram/SourceFiles/mtproto/web_proxy/web_proxy_transport.{h,cpp}
• Telegram/SourceFiles/mtproto/web_proxy/web_proxy_webview.{h,cpp}
• Telegram/SourceFiles/mtproto/details/mtproto_web_proxy_socket.{h,cpp}

Native WebView support:

• Telegram/lib_webview/webview/webview_common.h
• Telegram/lib_webview/webview/webview_embed.{h,cpp}
• the macOS, Windows WebView2, and WebKitGTK platform backends

Integration:

• mtproto_proxy_data.*, core_settings_proxy.cpp
• connection_tcp.cpp, session.cpp, session_private.cpp, proxy_check.cpp
• application.cpp, main_account.cpp
• boxes/connection_box.{h,cpp}, lang.strings
• Telegram/CMakeLists.txt

The client-side implementation is complete without the hosted server. Remaining
verification is the hosted protocol, native-WebView/platform matrix, and explicit
browser-fallback matrix in docs/web-proxy-test-plan.md.

15. Explicitly deferred Copy Chapter

• checking inactive WEB proxies and auto-rotation into them;
• cross-tab or cross-process relay-session resume;
• relay-auth v2;
• alternate bridge paths, ports, or non-HTTPS relay origins;
• expanding AbstractSocket with true uplink writable backpressure.

Web Proxy Test Plan (`docs/web-proxy-test-plan.md`) Copy Section

Telegram Desktop WEB proxy: server-ready execution test plan

Execute this document only after a hosted relay matching
../tproxy-server/PLAN.md is deployed. Record every requested value and artifact in
one run log. Do not put the proxy secret, Telegram auth keys, message contents, or
the loopback fragment capability in logs or screenshots.

1. Release gate Copy Chapter

WEB is ready for wider testing only when all P0 and P1 cases below pass through the
native WebView on every supported desktop platform, and the explicit
system-browser fallback has no unexplained P0 failure in its browser matrix.

Severity:

• P0: transport boundary, corruption, crash, login, basic send/receive, or total
  reconnect failure.
• P1: large transfer, concurrency, bounded memory, lifecycle recovery, or carrier
  fallback failure.
• P2: status text, browser-specific lifecycle annoyance, or non-blocking polish.

2. Inputs to obtain from the server operator Copy Chapter

Record these before starting:

The operator must confirm:

• the bridge root response can be framed by http://127.0.0.1:* and is not prevented
  by X-Frame-Options;
• HELLO payload 01, WELCOME, implicit 4 MiB windows, and all v1 frame types
  match docs/web-proxy-plan.md;
• the polling carrier provides ordered retry/deduplication;
• OPEN can dial only the configured local stock MTProxy;
• payload logging is disabled.

Stop if any item is false. A client run cannot produce a meaningful result against
an incompatible bridge.

3. Client build and isolation Copy Chapter

1. Build the exact candidate commit in Debug:

   bash Copy

   cmake --build out --config Debug --target Telegram

2. Record the commit, build timestamp, OS version, native WebView engine/version,
   fallback browser name/version, and whether either is managed by enterprise policy.

3. Use a disposable Telegram test account and a separate portable/test profile. Do
   not overwrite an existing personal portable profile.

4. Preserve Debug logs for the run, but verify they contain no proxy secret or frame
   payload.

5. Start with WebView inspection and browser developer tools closed; either changes
   scheduling and would invalidate lifecycle observations.

6. Disable unrelated VPNs/proxies for baseline. Record DNS-over-HTTPS, browser proxy,
   and system proxy state.

4. Hosted endpoint preflight Copy Chapter

Run from the client machine:

curl -fsS -D /tmp/tproxy-site.headers -o /tmp/tproxy-site.body \
  https://RELAY_HOSTNAME/
curl -fsS -D /tmp/tproxy-invalid.headers -o /tmp/tproxy-invalid.body \
  'https://RELAY_HOSTNAME/?bridge=invalid'

Verify:

• TLS certificate and hostname are valid with no warning or redirect to HTTP;
• / looks like the intended ordinary site and contains no transport error details;
• an invalid or missing bridge query returns the same ordinary site without
  transport-branded errors;
• server unit tests pass both capability vectors from docs/web-proxy-plan.md;
• the valid bridge response has a compatible frame-ancestors CSP and no
  incompatible X-Frame-Options, verified without recording its query;
• transport APIs reject unsupported methods and malformed session identifiers;
• server health shows the stock MTProxy backend reachable.

Delete the captured bodies after inspection if the deployment embeds any
configuration. Keep sanitized headers with the run artifacts.

5. Configuration and first connection (P0) Copy Chapter

1. Launch the candidate.

2. Open Settings -> Advanced -> Connection type -> Proxy settings -> Add proxy.

3. Select WEB.

4. Enter the relay hostname only and the MTProxy secret.

5. Confirm that these invalid inputs are rejected without saving:

   • a value containing http:// or https://;
   • a hostname with an explicit port;
   • a value with username, path, query, or fragment;
   • an IPv4 or IPv6 address, including shorthand forms such as 127.1,
     0x7f.1, 0177.0.0.1 and 1.2.3;
   • a single-label name such as localhost;
   • an invalid IDNA name, empty label, overlong label, or trailing dot;
   • invalid or unsupported MTProxy secret;
   • an ee TLS-emulation MTProxy secret;
   • empty hostname or secret.

6. Save the valid entry and enable it.

7. Confirm no system-browser tab opens.

8. Confirm exactly one hidden platform WebView loads
   https://<canonical-host>/?bridge=<43-char-capability>#android=<43-char-nonce>.

9. Confirm the settings row moves from connecting… to online within ten seconds.

10. Confirm Telegram loads dialogs and receives updates without a Telegram WebView
    window, Qt widget container, taskbar item, or dock item appearing.

Pass conditions:

• no crash, assertion, TLS warning, CORS/LNA prompt, mixed-content error, or iframe
  refusal;
• server sees one relay session and the expected MTProxy stream connections;
• the WebView requests exactly the canonical bridge URL and then scrubs its query
  and fragment from history;
• the page, DOM, network request headers, and console never contain the
  MTProxy secret;
• closing proxy settings does not affect the connection.

Verify both canonical link forms with the same hostname and secret:

https://t.me/webproxy?server=proxy.example.com&secret=000102030405060708090a0b0c0d0e0f
tg://webproxy?server=proxy.example.com&secret=000102030405060708090a0b0c0d0e0f

Each must show a confirmation containing the canonical hostname and secret, no port
or status row, and one connect action. Dismissing it must not save or enable the
proxy. Sharing a saved WEB entry must reproduce the public form with server and
secret, without port. After disabling the saved proxy, its row must show
not tested; re-enabling that exact entry must replace it with the live transport
state. Inactive WEB rows must never start a proxy checker, WebView, or browser tab.

Repeat once with an IDN hostname on a TLD that Qt renders in Unicode (.de or
.com, e.g. bücher.de, not .example): the entry is stored as xn--bcher-kva.de,
the hidden WebView connects, and the capability derived for it is byte-identical on
a Qt 5.15 Windows build and a Qt 6 macOS/Linux build. Also confirm that
xn--strae-oqa.example is stored unchanged on both.

Repeat once with a profile secret that is valid MTProxy syntax but is not configured
on staging. The ordinary-site fallback must match other root responses. The row must
show connecting… while the hidden WebView is retried with growing delays (2 s,
4 s, 8 s); after the third consecutive failure — at most ~2 min including the
extended handshake — the client must offer to open the proxy page in the browser,
and keep retrying the hidden WebView every 30 seconds afterwards. Cancel the offer
and confirm no browser opens; then accept it and confirm exactly one numeric
http://127.0.0.1:<ephemeral>/#<capability> tab opens, and that no loopback port
was listening before that click.

6. Network-origin invariant (P0) Copy Chapter

While WEB is the only enabled Telegram proxy, collect connection ownership with an
OS tool. On macOS, for example:

lsof -nP -iTCP -sTCP:ESTABLISHED | egrep 'Telegram|Chrome|Chromium|Edge|Safari|Firefox'

Also capture a short packet trace or firewall connection log if permitted.

Verify:

• in the primary mode, Telegram Desktop's WebView/WebContent process owns the HTTPS
  connection to the relay and no loopback WebSocket is connected;
• Telegram's ordinary MTProto sockets have no external connection to the relay,
  stock MTProxy, or Telegram DCs; the relay connection belongs only to the platform
  WebView engine;
• a WEB connection failure does not trigger tdesktop's HTTP time-sync fallback;
• DNS resolution of the relay is attributable to the WebView/system resolver, not a
  custom proxy/DC resolver in tdesktop;
• external carrier traffic remains inside the WebView-owned TLS connection.

Repeat after explicitly accepting browser fallback. In that mode Telegram Desktop
must connect only to 127.0.0.1:<ephemeral> for this transport, and the browser must
own the external HTTPS connection to the relay.

Account for unrelated Telegram HTTP traffic such as update checks before declaring
a failure. The invariant applies to the MTProto transport, not every auxiliary HTTP
request made by the application.

7. Functional traffic (P0/P1) Copy Chapter

Run in order, checking both client behavior and relay/MTProxy stream metrics:

1. Fresh-account login, including code entry and 2FA if available. P0.
2. Dialog/history load and live incoming updates. P0.
3. Send and receive plain messages in private and group chats. P0.
4. Send and receive stickers, reactions, edits, deletes, and read receipts. P1.
5. Download thumbnails and several small media files. P0.
6. Download one file larger than 1 GiB. P1.
7. Upload one file large enough to exceed the 4 MiB window many times. P1.
8. Stream a video while downloading another file. P1.
9. Open media from CDN-backed storage and confirm shifted/CDN DC streams work. P1.
10. Leave the client idle for 30 minutes, then send and receive immediately. P1.
11. On all-other platforms (WebKitGTK), download a large file while polling is
    throttled (rate-limit the link so the relay coalesces DATA into 1 MiB
    frames, i.e. ~1.4 MiB base64 native messages); the download must complete
    with a matching hash and no carrier restart. P0.

For large transfers record:

• bytes and final content hash;
• average and minimum throughput;
• tdesktop, WebView/WebContent, fallback browser when used, and relay peak memory;
• number of logical streams and stock-MTProxy sockets;
• reconnect/retry count;
• pending-uplink overflow or flow-control errors.

Run the same payload once through direct MTProxy and once through tdesktop's built-in
HTTP transport under the same controlled capacity/RTT when those controls are
reachable. On a controlled link with at least 100 Mbit/s capacity, WEB should
sustain at least 40 Mbit/s at 200 ms web-engine-to-relay RTT and 20 Mbit/s at 500 ms,
through the hidden WebView. Repeat the browser-specific target with the fallback tab
in both foreground and ordinarily hidden states.
Also report WEB/direct-HTTP ratios for message round-trip p50/p95 and bulk transfer;
route differences must be reported separately from transport overhead.

No transfer may corrupt, silently truncate, duplicate an upload, or grow client
memory without returning toward baseline after completion.

8. Multiplexing and concurrency (P1) Copy Chapter

1. Start at least 16 simultaneous media downloads across chats.
2. Send messages continuously during the downloads.
3. Start a large upload at the same time.
4. If multi-account is available, sign in to two disposable accounts and generate
   traffic on both.
5. Confirm all logical streams use the same native bridge and relay session. Repeat
   through fallback and confirm one authenticated local WebSocket/browser session.
6. Confirm one slow or window-exhausted stream does not block unrelated streams.
7. Cancel half the transfers and verify the corresponding CLOSEs release relay and
   stock-MTProxy resources.
8. Let the remainder finish and compare hashes.

Monitor thread sanitizer output if a TSan build is practical. Otherwise run for at
least two hours while watching for cross-thread QObject warnings, stale stream
delivery, stream-id mixups, growing queues, and use-after-free crashes.

Add a focused destruction race run that repeatedly opens and destroys logical WEB
sockets while the worker concurrently delivers connected, DATA, CLOSE, and
failure notifications. Run it under ASan and TSan where supported. No notification
may begin after synchronous stream unregistration returns, and no callback may run
against a socket whose destructor has started.

9. WebView, browser, and transport lifecycle (P0/P1) Copy Chapter

The Settings code externalweb toggles a process-local test override. The first
invocation blocks and tears down the hidden WebView carrier; the second removes the
block and starts a fresh WebView candidate immediately. Each invocation shows its
new state in a toast. Use it to drive the fallback and recovery cases without
changing the proxy or network.

Execute each case from a connected baseline: